OpenID Connect (OIDC) Integration

Follow the steps documented below to integrate your Org with an OIDC-compliant Identity Provider (IdP) such as Keycloak for Single Sign On (SSO).

Important
Only users with "Organization Admin" privileges can configure SSO in the Web Console.

Step 1: Create IdP in Web Console

• Log in to the Web Console as an Organization Admin.
• Navigate to System → Identity Providers.
• Click New Identity Provider.
• In the IdP Configuration tab, provide a unique name for the Identity Provider.
• Optionally, enter a description for reference.
• Select OIDC as the Authentication Type.
• Choose Keycloak as the Provider Name.
• Enter the Domain associated with the organization (for example, mycompany.com).
• Provide an Admin Email ID (for example, admin@mycompany.com).
• Provide a Client ID

The remaining fields: Client Secret, OP Domain URL, and Group Attribute Name must be populated after configuring the corresponding Keycloak application and retrieving these details from Keycloak.

Once these values are available, return to this page, complete the remaining fields, and then proceed with the setup.

Important

• Within an organization, both the IdP Name and Domain must be unique. A domain used in one organization can be reused in a different organization.
• The Domain and Admin Email domain must match. For example, if the domain is mycompany.com, the admin email should also belong to the same domain (e.g., admin@mycompany.com).

After completing the IdP configuration steps, the Redirect URL is generated in the Web Console. This Redirect URL must be added in the Keycloak Valid Redirect URIs field when creating the OIDC client.

Step 2: Configure Keycloak App in Keycloak

• Login into your Keycloak Org as an Administrator

• Navigate to Clients and click Create Client

• Select OpenID Connect as the client type.

• Specify the Client ID (the same Client ID configured in Step 1: IdP settings) and click Next. This Client ID is the unique IdP name configured in Step 1.

• Enable Client Authentication and Standard Flow in the Capability Config tab. If Client Authentication is not enabled for the IdP client, the Client Secret will not be generated or available.

• Click Next.

• Click Save.

Step 3: Capture Client Credentials

• Retrieve the Client Secret from the Credentials section

• Navigate to Configure -> Realm Settings and retrieve the OP Domain URL and Discovery Endpoint from the page shown below

• Paste these values into the Console configuration page

• Provide the Group Attribute Name and click Update & Continue

🚨 Important: Ensure that the OP Domain URL includes the protocol prefix — http:// or https:// — to make it a valid URL. The process cannot proceed without a properly formatted URL.

• Copy the Redirect URL generated by the web console to update it in Keycloak

• Return to the Keycloak console, select the client created in Step 2, and paste the URL under Access Settings → Valid redirect URIs as shown below.

• Click Save

Once saved, the OIDC app is configured in Keycloak.

Step 4: Creating the groups client scope

• From the Manage section, select Client Scopes.
• Click Create Client Scope.
• Enter the required details such as Name, Description, Type as Default, and Protocol as shown in the example below.
• Ensure Display on consent screen and Include in token scope are enabled if required.
• Click Save to create the client scope.

Step 5: Adding the Group Membership Mapper

• Click the Mappers tab and select Configure a new mapper.
• From the list, choose Group Membership.

Configure the mapper with the required settings:

• Provide a Name for the mapper.
• Set the Token Claim Name (this is the claim under which group information will appear).
• Ensure Add to ID token and Add to access token are enabled so that group details are included in both tokens.
• Keep Full group path, Add to lightweight access token, Add to userinfo, and Add to token introspection disabled unless specifically required.

Note: In the group membership mapper details, the token claim name must match the group attribute name configured in Step 1 of the controller setup.

• Click Save to complete the mapper configuration.

The client scope includes group mappers. Similarly, add email and name mappers (given name and family name) to the client scope.

Step 6: Configuring client scopes

Click the Client Scopes tab and ensure that the email, profile, and the configured group client scopes from Step 4 are available. If they already exist, verify that they are assigned to the client.

Step 7: Webhook Configuration (Optional)

In the Web Console, configure the webhook if required, and click Save & Exit.

Once the configuration is complete, a verification email is sent to the admin email ID specified on the IdP Configuration page. Complete the verification before users can log in with OIDC

Note: On successful configuration, create a user and assign the user to the appropriate group in the IdP application.

Troubleshooting

Scenario 1: Required Scopes Not Configured in Keycloak

The IdP is configured in the Web Console, and the OIDC client is created in Keycloak. However, required scopes such as email, profile, and the custom group-mapping scope are not added to the client.

Error Message:

Resolution:

• Navigate to the Keycloak client.
• Open the Client Scopes tab.
• Click Add Client Scope and assign the required scopes (email, profile, and the custom group scope such as groupdemoclientscope).
• Ensure the custom group scope is set to Default. If not set to Default, Keycloak does not return group information, and group reconciliation fails.