OIDC

In this guide, we will cover how to set up Keycloak as an OpenID Connect (OIDC) Identity Provider (IdP) to implement SSO for any Descope project.

Configuring SSO with Keycloak

1. Create the Tenant in Descope

From the Tenants page in the Descope Console, create a new Tenant in the top right of the page.

In the tenant's settings, set an email domain for the tenant. The navigate to Authentication Methods under the tenant's settings and select SSO and choose OIDC. Include the email domain that will be used for this SSO tenant.

2. Create the client in Keycloak

Now in Keycloak, navigate to the Clients page and create a new client. Make sure the Client type is OpenID Connect. Under capability config, toggle client authentication and implicit flow on. Then, create the client.

In the client's settings, under access settings, include the following URLs:

Note: These will be different if a custom CNAME is configured, read more here.

Now under Keys in the client's settings, enable JWKS URL and enter the following URL: https://your_keycloak_url/realms/your_realm_name/protocol/openid-connect/certs.

Then navigate to Credentials and copy the Client Secret.

3. Configuring the IdP in Descope

In the Descope Console, in the new tenant's settings under SSO, find the SSO Configuration settings. Paste the Client ID and Client Secret from Keycloak and name the IdP with the Provider Name. Include openid, profile, and email in the scopes and make the grant type implicit. Under Connection Settings, use the following formats for the URLs:

• Issuer: https://your_keycloak_domain/realms/your_realm_name
• Authorization Endpoint: https://your_keycloak_domain/realms/your_realm_name/protocol/openid-connect/auth
• Token Endpoint: https://your_keycloak_domain/realms/your_realm_name/protocol/openid-connect/token
• User Info Endpoint: https://your_keycloak_domain/realms/your_realm_name/protocol/openid-connect/userinfo
• JWKs Endpoint: https://your_keycloak_domain/realms/your_realm_name/protocol/openid-connect/certs

Then under SSO Mapping, map the email attribute from Keycloak to the Email attribute in Descope.

If more attributes need to be mapped, add it to the scopes and include it in the SSO Mapping section of the new Tenant's settings.

Now the SSO action can be added to a flow and used. Using the user's email domain, it will see which SSO Tenant is enabled for the user and use Keycloak as the IdP.

The SSO action can now be added to a flow and used to login with Keycloak. Using the user's email domain, the flow will detect if SSO is enabled for the user and redirect to the Keycloak tenant as the SSO IdP.

Get started by going to the Tenants page in your Descope Console! You can read more about SSO Tenants here.

If you have any other questions about Descope or our flows, feel reach to reach out to us!