SAML

In this guide, we will cover how to set up Keycloak as a Security Assertion Markup Language (SAML) 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 settings, add your tenant's email domain then navigate to Authentication methods, then SSO and select SAML. Add the same email domain as the SSO Domain for the tenant.

Then under SSO Configuration, select enter the connection details manually and enter the following information:

• SSO URL: https://your_keycloak_url/realms/your_keycloak_realm/protocol/saml
• Entity ID: https://your_keycloak_url/realms/your_keycloak_realm

The certificate will be added later. Then set the Subject NameID Format to Email.

2. Creating the SAML Client in Keycloak

In Keycloak, navigate to Clients and create a new client. Set the client type to SAML and the client ID to the Descope Entity ID from your new tenant's SSO settings under Service Provider.

Copy the ACS URL from the tenant's settings and paste it into the Valid redirect URL in Keycloak. Also include the beginning of the URL as the root URL in Keycloak.

Note: The ACS URL and root URL will be different if a custom CNAME is configured.

Set the name ID format to email, enable include AuthnStatement, optimize REDIRECT signing key lookup, and sign documents in Keycloak.

Then go to the Keys tab and activate client signature. After activating it, download the Request Signing Key from the tenant's settings in Descope and upload it as the client signature certificate.

Now under client scopes, delete the role_list scope. In the client's scope settings, add predefined mappers for role list and X500 email.

Then navigate to Realm Settings in Keycloak and go to the Keys tab. Here, view the RS256 certificate and copy it. Paste it into the certificate space in SSO Configuration in Descope. Then under SSO Mapping, map the IdP user value email to the Email Descope user attribute.

If more attributes need to be mapped, add the predefined mapper in the client's scope settings and include it in the SSO Mapping section of the new Tenant's settings. To map groups/roles in Descope, make sure the role list mapper is added to the client scope in Keycloak. Then, map the Keycloak role to a Descope role in the Tenant's settings under SSO Mapping in the Descope Console. The name of the attribute in the SAML assertion can be changed by modifying the role attribute name under the role list mapper in Keycloak. The mapper can also be configured in Keycloak to have all roles under one attribute value or have each role under its own attribute.

You can now add the SSO action step to a Descope flow to authenticate with SAML SSO. Make sure to use an email with the domain that you used earlier.

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!