Authorization mapper

Prerequisites

This feature is available as of censhare 2021.2.2 and has been enhanced for censhare 2021.2.4.

Introduction

To use censhare, each user requires at least one default role and one default domain. Additional roles and domains may be required. In Keycloak, you create user groups and optionally user attributes for this purpose. These are mapped to the censhare roles and domains. In Keycloak, a user group matches a censhare role. The censhare authorization mapper synchronizes these user data from Keycloak with the user table of the censhare server. censhare provides a template with a default mapping that you can use out of the box. It is based on the roles and domains of the Dedicated Solutions. You can customize the template to your needs. 

Prerequisites

The roles and domains that you create in Keycloak or specify in the mapping template must already exist in censhare. The authorization mapper cannot create new roles or domains. For example, if you want to use the standard roles and domains of the censhare dedicated solutions, first execute the Synchronize Dedicated solutions server actions in the censhare Admin Client. Else, create the required censhare roles manually according to your needs. For more information, see User roles for dedicated solutions, Domain framework for dedicated solutions.

Customization options

Decide where to create the mapping info, if you need to adapt the mapping template, and which user data should be synchronized.

Where to store the mapping info

You have several options where to store the mapping info:

• Mapping template. Convenient for mapping multiple users and groups between Keycloak and the censhare Server. 
• Keycloak. Role mapping is created with user-specific or group-specific attributes.
• Mix: You can combine both options.

What to adapt in the mapping template

Decide if you want to use the default mapping template or need to customize it (XSLT). You usually do not have to change the logic, but make changes only in the following places:

• new values for the fallback mappings when no suitable role or domain can be found: defaultRole, defaultDomain

• new entries in the group-role-mapping

Which user data to synchronize

Decide which kind of user data is synchronized between Keycloak and censhare. The synchronization options are set in the censhare Admin Client.

Mapping template

The Keycloak Party Mapping transformation asset(resource key: censhare:keycloak-party-mapping) maps Keycloak groups to censhare roles. It is distributed with the censhare standard product.

The XSLT contains default groups that are based on the censhare dedicated solutions. The groups already contain a set of roles and assigned domains.

It also contains a fallback mapping in case the appropriate groups or roles are not found.

Essential parts for customization are the Default attributes (fallback mapping) and the Group-Role mappings.

Default attributes

<xsl:attribute-set name="defaultPartyAttributes">
    <!-- Default values for auth_extern, auth_standard and sync_extern.
         Note that those values won't be used (by Java code) if the user already exists.
         This ensures that those values are never changed by the XSLT for existing users. -->
    <xsl:attribute name="auth_extern" select="1"/>
    <xsl:attribute name="auth_standard" select="0"/>
    <!-- 0: no synchronization, 1: synchronize basic information but not roles and groups, 2: complete sync -->
    <xsl:attribute name="sync_extern" select="1"/>
    <xsl:attribute name="isgroup" select="0"/>
  </xsl:attribute-set>

  <xsl:variable name="defaultDomain">root.global-share.</xsl:variable>
  <xsl:variable name="defaultDomain2">root.</xsl:variable>
  <xsl:variable name="defaultRole">no-permissions</xsl:variable>
  <xsl:variable name="defaultEmailNotification">1</xsl:variable>

Group-Role mapping

In Keycloak, a user group matches a censhare role. The group-role-mapping section is a mapping table, which maps Keycloak groups by name to a set of roles in censhare. If an entry for a Keycloak group is found in that mapping table, the role mappings are applied. If no entry is found, the default role and default domains are set for the user.

• The main-role, domain and domain2 variables can be used as a fallback, or to set fixed values.
• The user data and main-role, domain and domain2 are written as attributes into the <party/> element.

Example for a Media Consumer group role mapping in Keycloak Party Mapping, assuming that a group "Media Consumer" exists in Keycloak.

<group-role-mapping group-name="Media Consumer">
  <main-role>
    <party_role role="consumer" domain="root.solution-admin.organization.media." domain2="root." enabled="1"/>
  </main-role>
  <roles>
    <party_role role="consumer" domain="root.common-resources." domain2="root." enabled="1"/>
    <party_role role="consumer" domain="root.solution-admin.organization.media." domain2="root." enabled="1"/>
    <party_role role="specialist" domain="root.global-share." domain2="root." enabled="1"/>
    <party_role role="specialist" domain="root.solution-admin.organization.share." domain2="root." enabled="1"/>
  </roles>
</group-role-mapping>

Result

The user data that censhare gets back from Keycloak is an XML-formatted snippet with user attributes. The XML snippet that Keycloak sends back to censhare is processed in the Keycloak Party Mapping transformation. The output is written into the user party in the master data, and applied to the logged-in user. See the following example:

<root>
  <exp>
    1649251336
  </exp>
  <iat>
    1649251036
  </iat>
  <auth_time>
    1649251036
  </auth_time>
  <aud>
    account
  </aud>
  <realm_access>
    {roles=[default-roles-censhare, offline_access, uma_authorization]}
  </realm_access>
  <resource_access>
    {account={roles=[manage-account, manage-account-links, view-profile]}}
  </resource_access>
  <scope>
    openid profile email
  </scope>
  <name>
    Johnny Smith
  </name>
  <preferred_username>
    js
  </preferred_username>
  <given_name>
    Johnny
  </given_name>
  <family_name>
    Smith
  </family_name>
  <email>
    john.smith@example.com
  </email>
  <attributes>
    <attr name="login" value="js"/>
    <attr name="email" value="john.smith@example.com"/>
    <attr name="firstname" value="Johnny"/>
    <attr name="name" value="Smith"/>
    <attr name="group" value="Media Consumer"/>
  </attributes>
</root>

Set synchronization options

In the censhare Admin Client, in the Users master data, set the synchronization options according to your needs. For information on the options, see Synchronization options.

1. Select Authentication  > External Data Synchronization
2. Select the value:
   1. Don't synchronize (0)
   2. Basic synchronization (1). 
   3. Complete synchronization (2). 

The user data is mapped accordingly.

Mapping via template

Create groups in Keycloak

The Authorization Mapper uses the Keycloak groups to map them to the censhare roles and domains.

1. In Keycloak, go to the censhare realm.
2. From the side navigation, select User and create a new user or select an existing one.
3. From the side navigation, select Groups.
4. Click New and enter the group name. No other settings are required. 
5. Assign a suitable group to the user: Select the user, click the Groups tab, select a group from Available groups and click Join. 
6. Repeat the above steps for all users and groups that you want to create and assign.

Specify mapping in the template

1. In censhare Web, search for the Keycloak Party Mapping.
2. To modify the default mapping, create a Resource Replace Variant from the Keycloak Party Mapping asset.
3. Use the example below to adapt the transformation variant regarding fallback attributes (defaultRole, defaultDomain) and group-role-mappings

Mapping via Keycloak

Alternatively or additionally, you can define the role mapping by user-specific or group-specific attributes in Keycloak without changing the XSLT.

Check the synchronization options before you start.

Create roles and domains via User attributes in Keycloak

Set the following custom attributes on a Keycloak user to define the main role and corresponding domains of the user in censhare:

1. In Keycloak, go to the censhare realm.
2. From the side navigation, select User and create a new user or select an existing one.

3. For the selected user, select the Attributes tab. Enter the following keys and add the respective value for each key. The values specify existing roles or domains in censhare. 

   

   Note that new censhare roles or domains cannot be created via Keycloak.

• cs_locale: The key of the locale, which will be set to the language of the user. 

  

  Note that for new users, the attribute cs_locale is not mapped in censhare on the Person asset. Locale changes in Keycloak are only applied to the Person asset, if the user already exists in censhare.

• cs_main_role: The key of the censhare role, which will be the main/default role of the user.

• cs_main_domain: The key of the censhare domain, which will be the main/default domain of the user.

• cs_main_domain2: The key of the second censhare domain that will be the second domain of the user.

If the cs_main_role attribute is present on a Keycloak user, it will be used, and any matching main-role template definition in the XSLT will be ignored.

If it is not present, the first matching group-role-mapping/main-role template will be used to define the main role and main domains.

Note: It is not necessary to select any groups in Keycloak in this case.

Create additional roles via Group attributes in Keycloak

The mapping to additional roles can also be defined in Keycloak.

1. In Keycloak, go to the censhare realm, the User section and select the user. 
2. For the user, select the Groups tab. From Available groups, select a group and click Join.
3. From the Keycloak side navigation, go to Groups and select the group you just assigned.
4. For the selected group, select the Attributes tab. Enter the following keys and add the respective value for each key. The values specify existing roles or domains in censhare. 

The following custom attributes are supported on any Keycloak group:

• cs_role: The key of the censhare role, that this group will be mapped to.

• cs_domain: The key of the censhare domain, that this group will be mapped to.

• cs_domain2: The key of the second censhare domain that will be the second domain of the user.

The Authorization mapper will create a <party_role> relation from the user to the role with proper domain settings accordingly.

If the cs_role custom attribute is present on a Keycloak group, it will be used, and any matching role template in the XSLT will be ignored for that group.

censhare user groups mapping

The authorization mapper is able to connect users to censhare user groups.

what is a group in censhare?

In censhare, users can be organized in groups. Groups are a logical collection of users, for example as a workflow target. A typical example is a group of copy-editors. A group in censhare is not defined by a shared set of roles or permissions and not related to the censhare permission model. Groups in censhare are therefore different from groups in Keycloak. Groups in censhare are represented as a relation to another special party (parent_partyrel).

Create resource replace variant 

1. In censhare Web, search for the Keycloak Party Mapping transformation asset.
2. To modify the default mapping, create a Resource Replace Variant from the Keycloak Party Mapping asset.
3. Use the example below to adapt the transformation variant regarding the user groups (parent_partyrel).
   
   

Find out censhare user group ID

1. In the censhare Admin Client, go to the Master Data section.
2. Select User groups.
3. Open the target group or create a new one and copy the ID of the group.

Specify group in Keycloak

1. In Keycloak, go to the censhare realm, select the User section and select the user. 
2. For the user, select the Groups tab. From Available groups, select a group and click Join.
3. From the Keycloak side navigation, go to Groups and select the group you just assigned.
4. For the selected group, select the Attributes tab.
5. Enter the key cs_group_id. As a value paste the internal censhare ID that you copied in the Admin Client. 

<!-- Map groups (partyrels)) -->
    <xsl:variable name="partyRels" as="element(parent_partyrel)*">
      <!-- Extract partyrels by groups that have a @cs_group_id attribute set. -->
      <xsl:for-each select="$keycloakXML/attributes/attr[@name='group' and exists(keycloak_atrs[@name='cs_group_id'])]">
        <parent_partyrel enabled="1" parent_id="{keycloak_atrs[@name='cs_group_id']/@value}"/>
      </xsl:for-each>
      <xsl:copy-of select="$groupRoleMapping/groups/parent_partyrel"/>
    </xsl:variable>

Example

Example for a censhare SysAdmin group. The group ID SysAdmin has the value "2" in censhare, in this case.

<group-role-mapping group-name="sysadmin">
  <main-role>
    <party_role domain="root." domain2="root." role="admin"  enabled="1"/>
  </main-role>
  <roles>
  </roles>
  <groups>
   <parent_partyrel parent_id="2" enabled="1"/>
  </groups>
</group-role-mapping>

Fallback mapping

If no role is configured via custom user attributes in Keycloak and no matching role template is found for a user in the mapping transformation, a default role No permissions is assigned to the user. A user with No permissions is only allowed to log in, but cannot see any asset content and is not allowed to modify anything. As an administrator, you have to assign the appropriate roles to the user via the censhare Admin Client.

No mapping

If you select the option Don't synchronize option in the user table of censhare Admin Client, you need to add the user data directly in the censhare Admin Client.  For more information, see Add new users to Keycloak.

Result

When users log into censhare, they are authenticated with their credentials by the Keycloak server. Keycloak then redirects the users to the censhare Server. Users are logged in with their mapped roles, domains, and groups accordingly. For new users, a Person asset is created.