The SAML protocol provides single sign-on to applications across organizational boundaries. Keycloak serves as an identity broker between censhare and an identity provider.

Context

The setup is done in the censhare Admin Client and in the Keycloak administration console.

This article is only valid for censhare 2021.1. It is useful in the context of setting up SAML with the censhare Client (aka Java Client).


Prerequisites

Introduction

To use the external authentication with censhare 2021.1, a dedicated Keycloak authentication server is required. The user authentication is handled via this dedicated authentication server. Keycloak is used to log into censhare Web, the censhare Client, and the censhare Admin Client. Keycloak serves as an identity broker for the censhare Server.

On the Keycloak server, the censhare realm contains the clients and respective configurations that handle the user authentication to censhare Web and the censhare Clients. When a user logs in, Keycloak sends a SAML request to the identity provider. If the user credentials are valid, the identity provider sends back a SAML response that authenticates the user and provides the required user attributes to log in the user to censhare.

If you use already a Keycloak server in your organizational network, you can add the censhare realm to this service, and do not have to set up a new Keycloak instance. Otherwise, you must install and set up Keycloak first, before you proceed with this configuration.

To synchronize the user data between the identity provider and censhare via Keycloak, a mapping is required. The mapping pairs the user attributes from the identity provider with the corresponding censhare user attributes.

Authentication schema via Keycloak with SAML

Identity providers

Keycloak can connect with any SAML 2.0 compliant identity provider (IdP) for example, Microsoft AD FS, Octa or Google G Suite.

Configure the identity provider in Keycloak

To add your identity provider to Keycloak, do the following:

  1. Open the Keycloak URL and log in with your administration credentials.

  2. Select the censhare realm. If the censhare realm is not configured yet, you must add it first.

  3. In the left navigation, select Identity Providers.

  4. Click Add Provider and select SAML v2.0 from the list.

  5. Fill out all required fields with the settings from your SAML service data structure. Alternatively, you can import these settings:

    • Scroll down to the Import External IDP Config area.

    • To Import from URL, enter the complete URL of the XML configuration file on the identity provider server. Make sure that Keycloak can access the server and the directory, where the file is stored.

      Tip: To import the basic settings from ADFS, just add the suffix federationmetadata/2007-06/federationmetadata.xml to the FQDN of your ADFS server.

    • To Import from file, click Select file and upload the XML configuration file that you exported from the identity provider.

    • Click Import to import the data.

  6. We strongly recommend to switch the Want AuthnRequests Signed and Validate Signature toggles ON.

    Tip: For ADFS, the SAML Signature Key Name must be CERT_SUBJECT.

  7. Assign an Alias to the identity provider. The alias displays on the user login page.

  8. Click Save to save the configuration.

Add third-party trust to the identity provider

Note: This section describes the configuration of Microsoft ADFS, based on Active Directory setup for ADFS Management console version is 6.3.0.0. For other identity providers, this configuration can be different.

  1. Login to the ADFS Management console.

  2. Go to ADFS > Trust Relationships > Relaying Party Trust.

  3. In the Actions panel on the right side, click Add Relaying Party Trust. The wizard opens in a new window.

  4. Click Start.

  5. The simplest option is to enter the direct URL to the Keycloak broker description. To get this URL, add the suffix /descriptor to the Redirect URI field of your Identity Provider record in the Keycloak admin console.

    For example: https://auth-server.your-company.com/auth/realms/censhare/broker/saml/endpoint/descriptor.

  6. Enter the display name of your Relaying Party Trust record, and click Next.

  7. Select the option I do not want to configure multi-factor authentication settings for this relaying party trust at this time and click Next.

  8. Enable the option Permit all users to access this relaying party and click Next.

  9. Verify your Relaying Party Trust settings and click Next.

  10. Enable the field Open the Edit Claim Rules dialog for this relaying party trust when the wizard closes and click Close. For the Claim Rules configuration, see the next section.

Configure claim rules

Notes:

This section describes the configuration of Microsoft ADFS, based on Active Directory setup for ADFS Management console version is 6.3.0.0. For other identity providers, this configuration can be different.

In the example, we define a set of user attributes that are sent to the censhare Server. In production environments, the required attributes depend on the customer use case and the system configuration (domains, roles, permissions).

To create proper user profiles in Keycloak and on the censhare Server, the required_attributes must be retrieved from the SAML service. The claim rules define, which attributes are required to successfully authenticate a user via Keycloak.

In the initial step, these attributes are sent from the SAML service to Keycloak inside the SAML data structure. The second step, which maps the retrieved attributes to the censhare user attributes, is configured in the following section.

  1. In the Action panel of the Relaying Party Trust that you configured in the previous step, click Edit Claim Rules to start the wizard.

  2. In the wizard, click the Add rules button.

  3. Open the Claim rule template list, and select Send Claims Using a Custom Rule.

  4. Enter a rule name (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);

  5. Click Finish.

Configure attribute mappers in Keycloak

Keycloak queries the user ID and user attributes from the identity provider and passes them to the censhare Server via SyncParty. For this purpose, mapping is required. Keycloak serves as identity broker between the SAML service (identity provider) and the censhare Server. The mappers ensure that SyncParty can log in a user to the censhare Server with the required user attributes.

The actual mapping to the respective censhare user attributes is configured in censhare. This is described

below.

To configure the Mappers in Keycloak, do the following:

  1. In the side navigation, select the Identity provider that you configured in the first step, and click to open the configuration.

  2. Switch to the Mappers tab.

  3. Click Create.

  4. In the dialog, fill out the following fields:

    • Name: Enter a name for the Mapper. The name is only used internally and not part of the mapping.

    • Mapper Type: Select Attribute importer.

    • Attribute Name: Enter the mapped SAML claim name.

    • User Attribute Name: Enter the SAML claim name.

  5. Click Save.

  6. Return to the mappers list and repeat the previous steps for all required attributes. For the example from the Configure claim rule section above, the attributes list is as follows:

    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


You can add fixed values to the mapping. For example, to map all users to the same default domain. To do so, in the Mapper Type select Hardcoded Attribute and enter the desired attribute name and attribute value.

Configure the Keycloak module in censhare

Important: If you are not familiar with the censhare domain framework and user configuration, contact censhare solution development for the proper configuration of the internal server module.

In the internal server module, you configure the censhare query and the user attribute mapping. To set up the module, do the following:

  1. In the censhare Admin Client, go to the Configuration/Modules/Server Internal Modules directory and open the Login by Keycloak configuration.

  2. In the dialog, click Edit XML file.

  3. Note: The <search/> query and filter parameters are not used in the module! You do not need to edit them.

  4. Edit the <mappings/> section with the user attribute mappings. The mapping defines all required and optional attributes to create or synchronize a censhare user.

    • The <group name="ldap2party-search"/> element maps the user ID to the corresponding censhare party.

    • The <group name="ldap2party"/> element maps the LDAP user attributes to the corresponding censhare user attributes and sets the defaults.

  5. Click OK to save your changes and close the XML editor.

  6. Click OK to save your configuration.

Configure the clients

To log in via Keycloak from the censhare Client and the censhare Admin Client, on the client computers, do the following:

  1. Open the hosts.xml configuration. The default path is ~/Users/[USER]/Library/Preferences/censhare/hosts.xml.

  2. In the <host/> entry of the desired server, set the attribute authentication-method="external".

  3. Save the configuration.

Configure censhare Web

The login via Keycloak from censhare Web works without any further configuration. However, you can configure alternative login methods to censhare Web in the System asset.

Result

When users log in to censhare Web, the censhare Client, or the censhare Admin Client, they are redirected to the Keycloak login page. When they enter their credentials, Keycloak retrieves the user data from the LDAP server and passes them to the censhare Server. The users are logged in with their default domain and role. New users can log in likewise. Their user profile is added to the censhare master data with the respective attributes.