Set up SSO with an external identity provider

Configure single sign-on (SSO) so users can log in to the appliance through your organization's existing identity provider (IdP). Any standards-compliant OpenID Connect (OIDC) provider is supported, including Okta, Azure AD / Entra ID, PingFederate, Auth0, and Keycloak.

After setup is complete, the appliance redirects users to your IdP for authentication. The appliance never stores user passwords, it receives only a signed token confirming who the user is and what role they should have.

You perform steps in two parts: Steps 1–2 in your IdP's admin console, then Steps 3–5 in the appliance's admin console. Admin access to both consoles is required.

Before you begin:

  • You have admin access to your IdP's admin console.

  • You have admin access to this appliance's admin console (/server-setup, or /setup if initial setup is not yet complete).

  • You have admin access to Keycloak's admin console. This is a separate login from the appliance console, at https://<THIS_APPLIANCE_FQDN>/idp/admin/. Default credentials are admin / admin; you are prompted to change them on first login.

  • You have at least one existing test user in your IdP to verify the login in Step 6.

  • You have your IdP's root CA certificate or public TLS certificate as PEM text. You upload it in Step 3.

Before you start, decide on an IdP alias, a short name for this connection on the appliance side, for example my-idp. You use this alias in Step 1 to construct the redirect URI and again in Step 4 when you configure the identity provider in Keycloak.

Step 1: Register this appliance as an OIDC client in your IdP

In your IdP's admin console, create a new OIDC client or application registration for this appliance:

  1. Set the client type to Confidential client, Authorization Code flow. The exact wording varies by IdP, for example, Keycloak uses Client authentication: On and Standard flow: On; Azure AD uses a Web platform registration with a client secret.

  2. Set the redirect URI to the following value, replacing <alias> with the alias you chose:

    https://<THIS_APPLIANCE_FQDN>/idp/realms/unified-compliance/broker/<alias>/endpoint

  3. Set the scopes to at minimum openid.

After you create the client, record the Client ID, Client secret, and your IdP's discovery endpoint URL. You need all three values in Step 4.

Step 2: Confirm that roles or groups appear in the ID token

Most IdPs include role and group information in the access token by default, not the ID token. The role mapping in Step 5 reads the ID token specifically. Without this step, logins succeed but users have no permissions.

In your IdP's admin console:

  1. Confirm your IdP can include a roles or groups claim in the ID token for the client you created in Step 1. For example, if Keycloak is your IdP then go to Client scopes > roles > Mappers > realm roles, then turn on Add to ID token. Make sure you are in the correct realm, every realm has its own separate copy of this setting.

  2. Note the exact claim name or path the ID token includes, for example, roles, groups, realm_access.roles, or a custom claim name. You need this exact value in Step 5.

To confirm the claim is present before Step 5, log in through your IdP and decode the resulting ID token.

Step 3: Trust your IdP's TLS certificate

If initial appliance setup is not yet complete, perform this step from /setup. If setup is already complete, perform it from /server-setup, then restart the CDS service stack or reboot the appliance for the change to take effect.

  1. Open /setup or /server-setup, then select Network Security > TrustStore.

  2. Select ... > Add Certificate.

  3. Select Upload Certificate, paste the PEM contents of your IdP's certificate, then select Submit.

To verify the certificate is trusted, open Identity providers > <alias> in Keycloak after completing Step 4, then re-save the discovery endpoint URL. If the certificate is trusted, the authorization, token, JWKS, and issuer fields auto-fill without error.

Step 4: Add your IdP as an identity provider in Keycloak

In Keycloak's admin console (https://<THIS_APPLIANCE_FQDN>/idp/admin/), switch the realm dropdown from master to unified-compliance, then:

  1. Select Identity providers > Add provider > OpenID Connect v1.0.

  2. In Alias, enter the alias you used in the redirect URI in Step 1.

  3. In Discovery endpoint, paste your IdP's discovery endpoint URL from Step 1. The authorization, token, JWKS, and issuer URLs auto-fill. If this fails, confirm TLS trust in Step 3.

  4. In Client ID and Client secret, enter the values you recorded in Step 1.

  5. Set Client authentication to Client secret sent as basic auth or as post, depending on what your IdP expects.

  6. Set Scopes to openid, then select Add or Save.

Step 5: Map tenant context and roles to your users

Without this step, users who log in through your IdP don't have the tenant context or permissions needed to use the app.

In Keycloak's admin console, on the unified-compliance realm, select Identity providers > <alias> > Mappers > Add mapper. Set Sync mode override to Force on each mapper so it re-applies on every login.

Add the following mappers:

Mapper type

Configuration

Hardcoded Attribute

User Attribute: domain = <THIS_APPLIANCE_FQDN>

Hardcoded Attribute

User Attribute: organizationId = (see below)

Hardcoded Attribute

User Attribute: tenant = (see below)

Claim to Role

Claim: <claim name from Step 2>, Value: <role or group value in your IdP>, Role: admin@cds

Claim to Role

Claim: <claim name from Step 2>, Value: <role or group value in your IdP>, Role: viewer@cds

To find the organizationId and tenant values for your appliance: in the Keycloak admin console, switch the realm dropdown to unified-compliance, select Users, open any existing user, and copy the exact values from the Attributes tab. The tenant value is a JSON string, copy it verbatim, because a single incorrect character breaks tenant resolution for that user.

For the role mappers, Value is whatever your IdP actually sends for that claim (for example, a group name such as CDS-Admins), not the role names themselves. Role is fixed: admin@cds grants full access; viewer@cds grants read-only access. Do not use Hardcoded Role for role mapping, that assigns the same permission level to every user who logs in through your IdP.

Step 6: Verify the setup

  1. Open the Perforce Unified Compliance login page in a new private or incognito browser window.

  2. Select the button for your IdP, or append ?kc_idp_hint=<alias> to the login URL to go directly to your IdP.

  3. Log in as a test user. You should be redirected to your IdP and then back to the app.

Troubleshooting

Symptom

Resolution

redirect_uri mismatch error

The alias in Step 1's redirect URI must exactly match the alias in Step 4.

After login, a "Tenant not set up" screen appears

The user is missing the tenant, domain, or organizationId attributes. Review the mappers in Step 5.

Login succeeds but the user has no permissions

The ID token isn't carrying the roles or groups claim, or the claim name in Step 5's mappers doesn't match what your IdP sends. Decode a real ID token to check the actual claim name and value before retesting.