This article covers the Keycloak setup as an Identity Broker for SAML-based Identity Provider.

Purpose

There are many benefits of central user data management. To utilize them, Keycloak offers the functionality of an Identity Broker. It serves as an intermediate chain link between a Service Provider (cenTaur) and an identity provider.

With the Keycloak authentication architecture, users authenticate at censhare via Keycloak with their SAML-based service credentials. The user profiles are created or updated according to the policies configured in app/modules/server/login-keycloak.xml. No password is stored on the Keycloak server or on the censhare Server.

Prerequisites

Before you configure this system, you should be familiar with the SyncParty process. For more informatoin about SyncParty, see https://developer-documentation.censhare.com/developer/docs/auth-configural-methods.html#custom-ldap.

To setup SAML for Keyclaok, you need the following:

  • All attribute mapping configurations ready and available.
  • The SAML-based service name, address and login credentials (username/password).
  • Admin credentials to login into the corresponding Keycloak instance.

Important The examples in this article use Microsoft Active Directory Federation Service (ADFS) server as identity provider. For other implementations, read the SAML solution vendor documentation.

1. Configure identity provider in Keycloak

  1. Login into the Keycloak admin console. For a development environment, you can use https://authentication-dev.censhare.com.
  2. Choose the proper realm (default: censhare).
  3. Go to Identity providers.
  4. Click Add Provider and choose SAML v2.0 type.
  5. Fill out all required fields accoring to your SAML service data structure. For ADFS you can import the basic settings from a dedicated URL: just add the sufix federationmetadata/2007-06/federationmetadata.xml to the FQDN of your ADFS server and click Import.
  6. It is highly recommended to turn on Want AuthnRequests Signed, and Validate Signature. The parameter SAML Signature Key Name value must be CERT_SUBJECT for ADFS.
  7. Assign the proper Alias for this identity provider. The alias is displayed on the user login page.
  8. Click Save.

2. Configure ADFS - Add Third-party trust

Important This section describes Microsoft ADFS configuration, based on Active Directory setup for ADFS Management console version is 6.3.0.0.

  1. Login into your server, open ADFS Management console.
  2. Open ADFS > Trust Relationships > Relaying Party Trust.
  3. In the Actions panel at the right panel, click Add Relaying Party Trust to open the wizard.
  4. Click Start to start the wizard.
  5. The simplest option is to enter the direct URL to the Keycloak broker description. To get the URL, take it from the Redirect URI field of your Identity Provider record in the Keycloak admin console, and add the sufix /descriptor. For the example, the URL for the development environment is http://authentication-dev.censhare.com/auth/realms/censhare/broker/saml/endpoint/descriptor.
  6. Enter the display name of your Relaying Party Trust record, and click Next.
  7. Make sure that the option I do not want to configure multi-factor authentication settings for this relaying party trust at this time is enabled and click Next.
  8. Enable the option Permit all users to access this relaying party and click Next.
  9. In this step, you can review your Relaying Party Trust settings on different tabs. To continue, click Next.
  10. In the final step, leave the default check box Open the Edit Claim Rules dialog for this relaying party trust when the wizard closes disabled, and click Close. The wizard closes, and the Claim Rules dialog opens. For the Claim Rules configuration, see the next section.

3. Edit claim rules

To open the Edit Claim Rules dialog, select the required Relaying Party Trust and in the Actions panel, click Edit Claim Rules.

3.1. Add rule for required attributes

First, create the rule that is required for automatic user profile creation in Keycloak. If the required data cannot be retrieved from the SAML service, Keycloak prompts the user to enter the attributes. This approach is not desired in production environments.

  1. Click the Add rules button.
  2. From the Claim rule template drop-down, select Send Claims Using a Custom Rule.
  3. Enter the rule name. For example, Required fields rule, and enter the following content:
c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", Issuer == "AD AUTHORITY"]
 => issue(store = "Active Directory", types = ("userPrincipalName", "sAMAccountName", "givenName", "sn"), query = ";userPrincipalName,sAMAccountName,givenName,sn;{0}", param = c.Value);

  1. Click Finish.

3.2. Add rule for necessary user data

To create proper user profiles in Keycloak and on the censhare Server, the required data attributes must be retrieved from the SAML service. The attributes that are required depend on the customer environment. In this example, we use a non-production environment and the respective attributes. We defined a list of user attributes that are send to the censhare Server. In this initial step, we configure these attributes to be sent from SAML service to Keycloak inside the SAML data structure.

  1. Click the Add rules button.
  2. From the Claim rule template drop-down list, select Send Claims Using a Custom Rule.
  3. Enter the rule name at your choice (for example, User synchronization fields rule), and enter the following content:
c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", Issuer == "AD AUTHORITY"]
 => issue(store = "Active Directory", types = ("c", "cn", "displayName", "distinguishedName", "dSCorePropagationData", "givenName", "instanceType", "l", "lastLogonTimestamp", "mail", "manager", "memberOf", "name", "objectCategory", "objectClass", "objectGUID", "objectSid", "primaryGroupID", "sAMAccountName", "sAMAccountType", "sn", "st", "telephoneNumber", "userAccountControl", "userPrincipalName", "uSNChanged", "uSNCreated", "whenChanged", "whenCreated"), query = ";c,cn,displayName,distinguishedName,dSCorePropagationData,givenName,instanceType,l,lastLogonTimestamp,mail,manager,memberOf,name,objectCategory,objectClass,objectGUID,objectSid,primaryGroupID,sAMAccountName,sAMAccountType,sn,st,telephoneNumber,userAccountControl,userPrincipalName,uSNChanged,uSNCreated,whenChanged,whenCreated;{0}", param = c.Value);

  1. Click Finish.

4. Configure identity provider mappings in Keycloak

In this step, the required user attributes that are sent via SAML service to Keycloak are mapped to the respective censhare attributes. For better compresensibility, all attributes from the SAML service are forwarded to Keycloak with the exact same names as stored in the SAML service. In the mappings, the atttributes are passed for the censhare Server again with the exact same names as in the SAML service. In production environments with an existing SAML service, these names can be different.

  1. Login into the Keycloak admin console. For a development environment, you can use https://authentication-dev.censhare.com.
  2. Choose the proper realm (default: censhare).
  3. Go to Identity providers.
  4. Click on the identity provider record created on the stage 1.
  5. Switch to the Mappers tab
  6. Add mappers as described in the following sections.

4.1. Add mappers required for user auto-registration in Keycloak

Once a user is successfully authenticated, the corresponding user profile must be created or updated in the Keycloak database. There are four attributes required for this. If the corresponding mappings are not configured, or the data is missing in the SAML message for some reason, Keycloak prompts the user to enter the missing attribute values. This approach is not desired in production environments.

4.1.1. Configure username mapping. This one will be user's unique identifier in the Keycloak, and this username will be used in the censhare Server as well
  1. Click Create.
  2. In the dialog, fill out the following fields:
    • Name - any meaningful name for the mapper, for example - auto registration - username.
    • Mapper Type - Select Username template importer.
    • Template - Type ${ATTRIBUTE.sAMAccountName}. sAMAccountName is the name of one of the claims configured in the ADFS as part of Required fields rule.
  3. Click Save.
  4. Return to the list of mappers by clicking Identity Provider Mappers in the breadcrumb navigation.
4.1.2. Configure email mapping
  1. Click Create.
  2. In the dialog, fill out the following fields:
    • Name - any meaningful name for the mapper, for example - auto registration - email.
    • Mapper Type - Select Attribute importer.
    • Attribute Name - Type userPrincipalName. This is the name of one of the claims configured in the ADFS as part of Required fields rule.
    • User Attribute Name - Type email. This is one of the required properties for Keycloak user profiles.
  3. Click Save.
  4. Return to the list of mappers by clicking Identity Provider Mappers in breadcrumb navigation.
4.1.3. Configure first name mapping
  1. Click Create.
  2. In the dialog, fill out the following fields:
    • Name - any meaningful name for the mapper, for example - auto registration - first name.
    • Mapper Type - Select Attribute importer.
    • Attribute Name - Type givenName. This is the name of one of the claims configured in the ADFS as part of Required fields rule.
    • User Attribute Name - Type firstName. This is one of the required properties for Keycloak user profiles.
  3. Click Save.
  4. Return to the list of mappers by clicking Identity Provider Mappers in breadcrumb navigation.
4.1.4. Configure first name mapping
  1. Click Create.
  2. In the dialog, fill out the following fields:
    • Name - any meaningful name for the mapper, for example - auto registration - last name.
    • Mapper Type - Select Attribute importer.
    • Attribute Name - Type sn. This is the name of one of the claims configured in the ADFS as part of Required fields rule.
    • User Attribute Name - Type lastName. This is one of the required properties for Keycloak user profiles.
  3. Click Save.
  4. Return to the list of mappers by clicking Identity Provider Mappers in breadcrumb navigation.

4.2. Add mappers required for user profile synchronization between Keycloak and censhare Server (for current environment)

This section explains how to configure the mappings for SAML claims that are required for each particular environment. This set of fields depends solely on the SAML data, the SyncParty process configuration, and the environment setup. However, the approach is identical.

  1. Login into the Keycloak admin console. For a development environment, you can use https://authentication-dev.censhare.com.
  2. Choose the proper realm (default: censhare).
  3. Go to Identity providers.
  4. Click on the identity provider record created in the first step.
  5. Switch to the Mappers tab.
  6. Click Create.
  7. In the dialog, fill out the following fields:
    • Name - name of the mapper, for example - mapped SAML claim name.
    • Mapper Type - Select Attribute importer.
    • Attribute Name - mapped SAML claim name.
    • User Attribute Name - SAML claim name.
  8. Click Save.
  9. Return to the list of mappers by clicking Identity Provider Mappers in breadcrumb navigation.
  10. Repeat the steps 6 - 9 for all attributes that are required in your environment. For the example given in this article, the attributes list is a as follows:
auto registration - email
auto registration - first name
auto registration - last name
auto registration - username
c
cn
dSCorePropagationData
displayName
distinguishedName
givenName
instanceType
l
lastLogonTimestamp
mail
manager
memberOf
name
objectCategory
objectClass
objectGUID
objectSid
primaryGroupID
sAMAccountName
sAMAccountType
sn
st
telephoneNumber
uSNChanged
uSNCreated
userAccountControl
userPrincipalName
whenChanged
whenCreated

5. You are ready

When you have finished these configuration steps, the Keycloak SAML synchronization is ready to use in a test environment.

Last Updated: 08 April 2020