Add VSHN SSO for brokering

This guide describes the steps required to configure the APPUiO IdP so that a foreign Keycloak as Identity Providers can be used. In this case, we will use the VSHN SSO as an example. Please adjust the settings for your own case where necessary.

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.

keycloak brokering.drawio


  • Installed APPUiO IdP (see Install Keycloak)

  • Administrator console access to APPUiO IdP

  • Administrator console access to foreign Keycloak

It’s easiest to configure brokering if you have both administration console ready in 2 browser tabs next to eachother.

For the purpose of this guide, we will use the following names, interchange them as needed:

Key Description

APPUiO IdP hostname

Foreign Keycloak hostname


Realm within


Realm within


The Alias given to


The Client ID for within

Add new Client to VSHN SSO

  1. Log in as administrator to admin console in VSHN SSO and select the desired realm.

  2. Add a new Client and configure the following settings:

    Client ID = VSHN_to_APPUiO_Cloud
    Access Type = confidential
    Direct Access Grants Enabled = True
    Valid Redict URIs =*
  3. Add the group memberships to the tokens. Go to the "Mappers" tab and create a new Mapper.

    Name = group membership
    Mapper type = Group Membership
    Token Claim Name = groups
    Full group path = false (1)
    1 If this is true (the default), then the group name for group /Company/admins is /Company/admins, which might be undesirable. If this is false, the group name is just the value of the leaf node instead, for example group /Company/admins will be assigned the name admins.
  4. After saving, go into edit mode again and select the "Credentials" tab.

  5. Keep the displayed Secret ready for copy-pasting.

Configure Identity Provider

  1. Log in as administrator to admin console in the APPUiO IdP instance and select the desired realm.

  2. Add a new Identity Provider (select Keycloak OpenID Connect) and configure the following settings:

    Alias = vshn
    Display Name = A human friendly name displayed in the Login page
    Trust Email = True
    Sync Mode = force
    Authorization URL =
    Token URL =
    Logout URL =
    User Info URL =
    Client Authentication = "Client secret sent as post"
    Client ID = VSHN_to_APPUiO_Cloud
    Client Secret = <The secret displayed in Credentials tab>
  3. Add a "Claim to Group" mapper to the client via the "Mappers" tab

    Name = import-groups
    Sync Mode Override = inherit
    Mapper Type = Claim to Group
    Claim = groups
    Match pattern = (VSHN (openshiftroot|employee)|Cust\s.*) (1)
    Create groups if not exists = True
    Lowercase names = True (2)
    Trim whitespace = True (3)
    Trim Prefix = (Cust\s|\semployee) (4)
    1 Only the groups matching this regex are synced.
    2 Disable this option if you don’t want to normalize the resulting groups with all lowercase names
    3 Disable this option if you don’t want to trim leading and trailing white space, and replace other white space with dashes
    4 The first occurrence of this regex is removed from group names. This is executed before the "Lowercase names" and "Trim whitespace" options are applied.
  4. Add a "Claim to Attribute" mapper to the identity broker via the "Mappers" tab

    Name = default-organization
    Sync Mode Override = inherit
    Mapper Type = Claim to Attribute
    Claim = groups
    Target attribute =
    Overwrite existing attribute value = false
    Ignore entries pattern = (1)
    Search entries pattern = ^(Cust\s.*|VSHN employee) (2)
    Lowercase names = True (3)
    Trim whitespaces = True (3)
    Trim prefix = (Cust\s|\semployee) (3)
    1 Groups matching this regex are ignored when configuring the target attribute. Left empty for the default configuration for VSHN.
    2 Only groups matching this regex are considered to configure the target attribute. The "Ignore entries pattern" takes precedence over this pattern.
    3 These fields work the same as the fields with the same names for the "Claim To Group" mapper. Make sure these fields are configured the same for the "Claim To Group" and "Claim To Attribute" mappers if you want to match attribute values to group names.

(Optional) Configure as Default Identity Provider

You have the option to set the brokered Keycloak as the default identity provider, which will make the APPUiO IdP automatically redirect to brokered Keycloak. This can be helpful if you only have a single identity provider and no local users.

  1. Select the desired realm in APPUiO IdP

  2. Go to Authentication  Flows

  3. Select flow "Browser"

    If role-based access control was enabled, you might need to configure this for flow "Browser Rbac" instead.
  4. Select Actions  Config on the "Identity Provider Redirector" sub-flow to configure a default identity provider

    Alias = indentity-provider-redirector-config
    Default Identity Provider = vshn (1)
    1 The alias of the configured identity provider