How mapping works

An introduction to authorization mapping.

Introduction

When a user logs in, censhare needs to know which role, domain, and second domain they are assigned. Otherwise, the user will see no assets. More about censhare‘s permission concept in general can be found here.

In one of the previous articles, you have learned How Keycloak works with censhare . The present article explains how user information and permission rights are synchronized between the two systems and what needs to be set up to make it all work.

How mapping works

Permission rights in Keycloak: a short overview

Keycloak UI is different from censhare and uses different terminology when it comes to user access. it has attributes and user groups.

Keycloak user groups are not identical to user groups in Censhare.

What are Censhare user groups?

In Censhare, user groups have nothing to do with permissions. They are just a convenient way to create user “lists”, e.g., for defining a team of collaborators as a workflow target.

There are two ways how Censhare roles and domains can be represented in Keycloak. In the end, each role or each domain is “matched” with a corresponding attribute in Keycloak.

The main role, domain, and second domain can be mapped:
1. to Keycloak user attributes: each to its own attribute
2. to a Keycloak user groups: as a “bundle” of all three values
Other – not main – Censhare roles and domains are always bundled together and mapped to user groups in Keycloak. Most of the time, multiple such combinations (a role and two domains) are mapped to one and the same user group in Keycloak.
Each Censhare user group is mapped to one attribute in Keycloak.

Default mapping

Any Censhare system comes with a set of predefined roles and domains. They are part of Dedicated Solutions. See User roles for dedicated solutions and Domain framework for dedicated solutionsfor more information. If the out-of-box mapping is enough for you, you can just execute the Synchronize Dedicated solutions server action in the censhare Admin Client.

Data flow upon a user login

Upon a user login, Keycloak sends to Censhare an XML-formatted snippet with the user information.

Among other information, the snippet contains a list of user attributes. Inside the censhare system, they need to be translated into the correct format: roles, domains, and optionally Censhare user groups.

Such mapping is done by an XSLT-transformation. The output is written to the user table in the database.

Based on the output, the Censhare system authorizes the user and serves the content to their browser according to that user‘s role.

Sample Keycloak snippet

XML

<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>

Authorization mapping can be customized. Before you proceed with any customizations, please read the following sections to understand the user data synchronization. It will be affected by such changes.