Configure role mappings for Keycloak brokering

This guide describes the steps required to configure the APPUiO IdP so that claims from a foreign Keycloak can be used as roles. In this guide, we use the VSHN SSO as an example. The example shows how to map groups VSHN employee and Service APPUiOCloud to roles in APPUiO IdP. This guide assumes that you’ve already configured the brokering itself.

This page is meant to be growing and doesn’t contain the final configuration at this time.
Some steps require that APPUiO Keycloak extensions is installed.

For the purpose of this guide, we’ll use the following names, adjust as needed:

Key Description

Foreign Keycloak hostname


The display name of the identity provider in APPUiO IdP


Realm within APPUiO IdP


  • Installed APPUiO IdP

  • Logged in to APPUiO IdP as Administrator

  • Brokering with configured

  • provides group memberships of each user in claim groups

Create roles in APPUiO IdP

  1. Select realm appuio-cloud in APPUiO IdP.

  2. Create roles with Roles  Realm Roles  Add Role. For our example, we create roles vshneer-zone-access and appuio-zone-access.

Configure Identity Provider

  1. Go to VSHN SSO in "Identity Providers" and select tab "Mappers"

  2. Create a new mapper to map group VSHN employee to role vshneer-zone-access for users logging in via

    Name = vshneer-global-access
    Mapper type = Claim to Role
    Claim = groups
    Claim Value = VSHN employee
    Role = vshneer-zone-access
  3. Create a new mapper to map group Service APPUiOCloud to role appuio-zone-access for users logging in via

    Name = customer-global-access
    Mapper type = Claim to Role
    Claim = groups
    Claim Value = Service APPUiOCloud
    Role = appuio-zone-access