Keycloak – SSO & Connector Permissions

This guide provides a comprehensive, step-by-step walkthrough for administrators to set up Single Sign-On (SSO) with Keycloak for FSI Server, secure the integration using OpenID Connect (OIDC) with PKCE and confidential client authentication, and manage fine-grained access to different Source Connectors on FSI Server.

It covers architecture considerations, realm isolation, client configuration, protocol mappers for token claims, user federation (such as Active Directory / LDAP synchronization), identity brokering, and security hardening.

Realm Architecture: Master Realm vs. Dedicated Application Realm​

Keycloak organizes users, credentials, roles, and clients into Realms. A realm manages a distinct set of users and applications, providing complete logical isolation:

In the following steps, all configuration actions are performed inside your dedicated application realm (e.g., fsi).

Identity Directory Models: Local Groups vs. LDAP/AD Federation vs. Identity Brokering​

Keycloak provides versatile options for managing directory identities and assigning group permissions:

Architecture & Data Flow​

On FSI Server, digital assets are organized into Source Connectors (such as local storage directories, SAN/NAS shares, or cloud buckets). Access to each connector is governed by FSI Server Groups.

The following diagram illustrates how user attributes in Keycloak map to security groups, pass through the OIDC authorization code flow, and resolve to connector permissions on FSI Server:

Scenario Overview:​

Keycloak Administration Console Configuration​

Step 1: Create or Select the Application Realm​

1. Log in to the Keycloak Administration Console (e.g., https://<keycloak-domain>/admin/).
2. Open the realm dropdown menu at the top of the left sidebar.
3. Click Create Realm (or select your existing organizational realm, e.g., fsi).
4. Enter the Realm name: e.g., fsi.
5. Ensure Enabled is switched to ON.
6. Click Create.

Step 2: Create Groups for Connectors​

In the left navigation menu under your chosen realm, navigate to:
👉 Groups → Create group

1. Create the groups corresponding to your connector permissions:
   • fsi-marketing
   • fsi-products
   • fsi-archive
   • fsi-administrators
2. Click Create for each group.

Step 3: Register and Configure the Client​

1. In the left navigation, navigate to:
   👉 Clients → Create client
2. General settings:
   • Client type: OpenID Connect
   • Client ID: fsi-server
   • Name: FSI Server
   • Description: FSI Server Media Platform Single Sign-On
   • Click Next.
3. Capability config:
   • Client authentication: ON (Mandatory: Configures Keycloak as a Confidential Client requiring a Client Secret).
   • Authorization: OFF.
   • Authentication flow:
     • ☑ Standard flow (Authorization Code Flow)
     • ☐ Direct access grants (Uncheck unless Resource Owner Password Credentials / ROPC is explicitly required)
     • ☐ Implicit flow (Leave unchecked)
     • ☐ Service accounts roles (Leave unchecked unless programmatic backend tokens are used)
   • Click Next.
4. Login settings:
   • Root URL: https://<fsi-domain>
   • Home URL: https://<fsi-domain>/fsi/interface/
   • Valid redirect URIs: https://<fsi-domain>/fsi/interface/
     (Example: https://fsi.example.com/fsi/interface/ – Ensure the trailing slash / is included!)
   • Valid post logout redirect URIs: https://<fsi-domain>/fsi/interface/
   • Web origins: + (or explicitly https://<fsi-domain>)
5. Click Save.

Step 4: Configure Back-Channel Logout​

To ensure that logging out from Keycloak or terminating an SSO session immediately invalidates the user's active session on FSI Server, configure Back-Channel Logout:

1. In the client configuration of fsi-server, navigate to the Advanced tab (or scroll down to Logout settings).
2. Configure the following fields:
   • Frontchannel logout: Leave empty / disabled.
   • Backchannel logout URL: Enter the FSI Server logout endpoint:
     https://<fsi-domain>/service/oidc/logout
   • Backchannel logout session required: ON (enabled).
   • Backchannel logout revoke offline sessions: OFF.
3. Click Save.

Step 5: Obtain the Client Secret​

1. In the client menu for fsi-server, navigate to the Credentials tab.
2. Verify that Client Authenticator is set to Client Id and Secret.
3. Copy the string in the Client secret field.
   (If needed, you can regenerate this secret at any time using the regenerate button).

Step 6: Configure Token Group Claims (Protocol Mapper)​

By default, Keycloak does not include user group memberships in the generated ID token. You must add a Group Membership Protocol Mapper to the client's dedicated scope:

1. Navigate to:
   👉 Clients → fsi-server → Client scopes tab.
2. Click on the dedicated client scope link: fsi-server-dedicated.
3. In the mappers list, click Add mapper → By configuration.
4. Select Group Membership from the mapper types.
5. Configure the mapper settings:
   • Name: groups
   • Token Claim Name: groups
   • Full group path: OFF (Disabled – see tip below)
   • Add to ID token: ON (Enabled – Critical: FSI Server reads groups from the ID token)
   • Add to access token: ON (or OFF)
   • Add to userinfo: ON
6. Click Save.

"groups": ["fsi-marketing", "fsi-administrators"]

"groups": ["/fsi-marketing", "/fsi-administrators"]

Step 7: Assign Users & Manage Federation​

Option A: Local Keycloak Users​

1. In the left navigation, navigate to: 👉 Users → Add user.
2. Fill in Username, Email, First name, and Last name.
3. Under the Credentials tab, set a password for the user.
4. Under the Groups tab, click Join Group and select the appropriate connector group (e.g., fsi-marketing or fsi-administrators).

Option B: Active Directory / LDAP User Federation​

In enterprise deployments, Keycloak frequently synchronizes users and groups from Active Directory or OpenLDAP:

1. Navigate to: 👉 User federation → Add provider → ldap.
2. Configure connection settings, Bind DN, Users DN, and sync intervals.
3. Once created, go to the Mappers tab of the LDAP provider and click Add mapper:
   • Mapper type: group-ldap-mapper
   • LDAP Groups DN: OU=FSI Groups,DC=corp,DC=example,DC=com
   • Group Object Classes: group (Active Directory) or groupOfNames (OpenLDAP)
   • Mode: READ_ONLY (or SYNC)
4. Benefit: Enterprise Active Directory security groups are automatically mirrored into Keycloak groups, which FSI Server translates into connector access rules via groupMapping without manual provisioning.

Option C: Multi-Factor Authentication (MFA / WebAuthn / Passkeys)​

• Under Authentication → Flows, administrators can bind MFA policies (WebAuthn, Passkeys, Google Authenticator / FreeOTP) to the browser flow.
• Users logging into FSI Server are automatically prompted to complete MFA before Keycloak issues the authorization code.

Option D: Identity Brokering (Upstream Corporate IdP)​

• If Keycloak acts as an identity broker for external IdPs (such as Okta, Google Workspace, or Ping Identity), navigate to Identity providers → select or add the upstream provider.
• Under the provider's Mappers tab, add a Claim to Group or Attribute to Group mapper to assign external directory users into Keycloak's fsi-* connector groups automatically upon login.

FSI Server Configuration (settings.yml)​

Configure the OIDC authentication module in settings.yml (located in the FSI Server configuration directory, e.g., /etc/fsi/fsi-server/config/settings.yml or ./config/settings.yml).

The example below shows all parameters, highlighting mandatory settings and default values:

authentication:
  authModules:
    - type: "oidc"                                # Mandatory: Module type
      enabled: true                               # Default: true
      name: "Keycloak (SSO)"                      # Display label on login button
      provider: "keycloak"                        # Provider identifier

      # 1. Credentials from Keycloak Client (Steps 3 & 5)
      clientId: "fsi-server"                      # Mandatory: Client ID from Keycloak
      clientSecret: "your-client-secret-from-keycloak" # Mandatory: Client Secret value

      # 2. Issuer URL (Endpoints are automatically discovered via .well-known/openid-configuration)
      # Mandatory: Keycloak Realm URL (https://<keycloak-domain>/realms/<realm-name>)
      issuerUrl: "https://auth.example.com/realms/fsi"

      # 3. Redirect URI
      # Default: Uses base request URL if omitted.
      # Recommendation: Specify explicitly with [IP_ADDRESS] to match Keycloak Valid Redirect URIs.
      redirectUri: "https://[IP_ADDRESS]/fsi/interface/"

      # 4. Token Claims
      usernameClaim: "preferred_username"         # Default: "preferred_username" (or "email")
      groupsClaim: "groups"                       # Default: "groups"

      # 5. User Provisioning & Session Mode
      autoProvision: true                         # Default: true (provisions user upon first SSO login)

      # 6. Group Mapping: Map Keycloak Group Names to FSI Server Groups
      # Note: FSI Server groups must correspond to defined group names
      groupMapping:
        # Full Administrator (Access to server settings & all connectors)
        "fsi-administrators": "administrators"

        # Marketing Team (Mapped to marketing connector)
        "fsi-marketing": "marketing"

        # Products Team (Mapped to product catalog connector)
        "fsi-products": "products"

        # Archive Team (Mapped to internal archive connector)
        "fsi-archive": "archive"

    # Optional: File-based XML authentication module as local administrative fallback
    - type: "file"
      enabled: true

Troubleshooting & Common Issues​