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