Appearance

SAML SSO Integration Guide ​

This guide explains how to configure SAML Single Sign-On (SSO) integration with our platform. We'll cover setup instructions for three popular identity providers: Keycloak, Azure Entra ID (formerly Azure AD), and Google Workspace.

General Requirements ​

Before setting up SSO, you'll need the following information from our platform:

  • Entity ID (Audience URI): https://your-domain.com
  • Assertion Consumer Service (ACS) URL: https://your-domain.com/api/auth/saml/callback
  • Name ID Format: urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

Group Mapping ​

Our platform supports automatic team and role assignment through SAML group mapping. Groups should follow this format:

bcl-<team>-<role>

Available roles:

  • viewer: Can view loan requests and summaries
  • bankLoanAgent: Can create and manage loan requests
  • bankLoanManager: Can manage loan requests and assign agents
  • bankLegal: Can perform legal tasks and reviews
  • bankApprover: Can approve loan request actions
  • bankAdmin: Can manage users, teams, and settings
  • bankThemeAdmin: Can manage users, teams, and settings
  • professional: Third-party professionals appointed by the bank

Example: <company prefix>-bcl-development-bankLoanAgent

Identity Provider Setup Instructions ​

Before configuring your Identity Provider, you'll need to set up an SSO provider in Banclo and gather the necessary information.

Configuring SSO Provider in Banclo ​

  1. Navigate to the SSO Providers section in Settings: SSO Providers Landing Page

  2. Create a new provider. Give it a name and bind it to a domain . This will be checked against the emails. Exmple acme.com will check all users with email login @acme.com

  3. After creating a provider, click the View/Edit button to access provider details: SSO Provider Details

  4. Copy the Issuer and ACS URL - you'll need these for your IdP configuration: Copy Issuer and ACS URL

  5. Once you've configured your IdP, return to this screen to enter the Certificate, SSO URL, and IdP Issuer: Configure IdP Details

1. Keycloak ​

  1. Create a new SAML Client:

    • Log in to Keycloak Admin Console
    • Select your realm
    • Go to Clients > Create Client
    • Select SAML as the Client Protocol

  2. Configure Client Settings:

    Client ID: <Entity ID from Banclo>
Client Protocol: saml
Client SAML Endpoint: <ACS URL from Banclo>

  3. Configure Mappers:

    • Create a "Group Membership" mapper:
      • Name: groups
      • Mapper Type: Group list
      • Group attribute name: groups
      • Full group path: OFF

  4. Download Certificate:

    • Go to SAML Keys
    • Download the certificate (X.509 format)

  5. Configure Groups:

    • Create groups following our naming convention (e.g., bcl-development-bankLoanAgent)
    • Assign users to appropriate groups

2. Azure Entra ID (formerly Azure AD) ​

  1. Register Enterprise Application:

    • Go to Azure Portal > Azure Entra ID
    • Enterprise Applications > New Application
    • Select "Create your own application"

  2. Configure SAML:

    • Select "Single sign-on" > SAML
    • Basic SAML Configuration:
      Identifier (Entity ID): <Entity ID from Banclo>
Reply URL (ACS URL): <ACS URL from Banclo>
Sign on URL: <Your application login URL>

  3. Configure User Attributes & Claims:

    • Add group claims:
      • Select "Edit" in User Attributes & Claims
      • Add group claim
      • Select "Security groups" with format bcl-*-*

  4. Download Certificate:

    • Download the Base64 certificate from SAML Signing Certificate section

  5. Configure Groups:

    • Create security groups following our naming convention
    • Assign users to appropriate groups

3. Google Workspace ​

  1. Add Custom SAML App:

    • Go to Admin Console
    • Apps > Web and mobile apps
    • Add Custom SAML App

  2. Configure SSO Settings:

    ACS URL: <ACS URL from our platform>
Entity ID: <Entity ID from our platform>
Name ID Format: EMAIL

  3. Configure Attribute Mapping:

    • Add group membership attribute:
      App attribute: groups
Category: Basic Information
User field: Groups

  4. Download Certificate:

    • Download the X.509 certificate from the SSO settings

  5. Configure Groups:

    • Create Google Groups following our naming convention
    • Ensure group names are synced correctly in SAML attributes
    • Assign users to appropriate groups

Testing the Integration ​

  1. Create a test user in your IdP
  2. Assign the user to appropriate groups
  3. Try logging in to our platform using the test user's email
  4. Verify that:
    • SSO login works successfully
    • User is assigned to correct teams and roles based on groups

Troubleshooting ​

Common issues and solutions:

  1. Login fails with "Invalid SAML Response":

    • Verify the certificate is correctly uploaded
    • Check that the Entity ID matches exactly
    • Ensure clock synchronization between systems

  2. Groups not mapping correctly:

    • Verify group names follow the exact format: bcl-<team>-<role>
    • Check group attribute mapping in IdP configuration
    • Ensure groups are being included in the SAML assertion

  3. User not receiving correct permissions:

    • Verify user is assigned to the correct groups in IdP
    • Check group naming matches our required format
    • Review SAML response for correct group attributes