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
- Login into the Keycloak admin console. For a development environment, you can use
https://authentication-dev.censhare.com
. - Choose the proper realm (default: censhare).
- Go to Identity providers.
- Click Add Provider and choose SAML v2.0 type.
- 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. - It is highly recommended to turn on Want AuthnRequests Signed, and Validate Signature. The parameter
SAML Signature Key Name
value must beCERT_SUBJECT
for ADFS. - Assign the proper Alias for this identity provider. The alias is displayed on the user login page.
- 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.
- Login into your server, open ADFS Management console.
- Open ADFS > Trust Relationships > Relaying Party Trust.
- In the Actions panel at the right panel, click Add Relaying Party Trust to open the wizard.
- Click Start to start the wizard.
- 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 ishttp://authentication-dev.censhare.com/auth/realms/censhare/broker/saml/endpoint/descriptor
. - Enter the display name of your Relaying Party Trust record, and click Next.
- 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.
- Enable the option Permit all users to access this relaying party and click Next.
- In this step, you can review your Relaying Party Trust settings on different tabs. To continue, click Next.
- 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.
- Click the Add rules button.
- From the Claim rule template drop-down, select Send Claims Using a Custom Rule.
- 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);
- 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.
- Click the Add rules button.
- From the Claim rule template drop-down list, select Send Claims Using a Custom Rule.
- 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);
- 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.
- Login into the Keycloak admin console. For a development environment, you can use
https://authentication-dev.censhare.com
. - Choose the proper realm (default: censhare).
- Go to Identity providers.
- Click on the identity provider record created on the stage 1.
- Switch to the
Mappers
tab - 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
- Click Create.
- 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.
- Name - any meaningful name for the mapper, for example -
- Click Save.
- Return to the list of mappers by clicking
Identity Provider Mappers
in the breadcrumb navigation.
4.1.2. Configure email mapping
- Click Create.
- 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.
- Name - any meaningful name for the mapper, for example -
- Click Save.
- Return to the list of mappers by clicking
Identity Provider Mappers
in breadcrumb navigation.
4.1.3. Configure first name mapping
- Click Create.
- 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.
- Name - any meaningful name for the mapper, for example -
- Click Save.
- Return to the list of mappers by clicking
Identity Provider Mappers
in breadcrumb navigation.
4.1.4. Configure first name mapping
- Click Create.
- 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.
- Name - any meaningful name for the mapper, for example -
- Click Save.
- 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.
- Login into the Keycloak admin console. For a development environment, you can use
https://authentication-dev.censhare.com
. - Choose the proper realm (default: censhare).
- Go to Identity providers.
- Click on the identity provider record created in the first step.
- Switch to the Mappers tab.
- Click Create.
- 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.
- Click Save.
- Return to the list of mappers by clicking
Identity Provider Mappers
in breadcrumb navigation. - 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