Skip to content

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

Create IdP

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

Create IdP

  • 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.

Create App Integration

  • 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.

Create App Integration

  • Click Save.

Create App Integration

Step 3: Capture Client Credentials

  • Retrieve the Client Secret from the Credentials section

Create App Integration

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

Client Credentials Client Credentials

  • 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.

Client Credentials

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

Client Credentials

  • 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

Client Credentials

Once saved, the OIDC app is configured in Keycloak.

Create IdP

Step 4: Configuring client scopes

Click on Clients scopes tab and ensure that the email, name, and groups client scopes are available. If they already exist, verify that they are added to the client’s assigned client scopes.

Create IdP

Step 5: 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.

Create IdP

Step 6: Adding the Group Membership Mapper

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

Create IdP

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.

Create IdP

  • 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.

Create IdP

Step 7: Webhook Configuration (Optional)

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

Client Credentials

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

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:

Client Credentials

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.

Client Credentials Client Credentials