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

Prerequisites

  • 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

id.appuio.cloud

APPUiO IdP hostname

id.vshn.net

Foreign Keycloak hostname

appuio-cloud

Realm within id.appuio.cloud

vshn-realm

Realm within id.vshn.net

vshn

The Alias given to id.vshn.net

VSHN_to_APPUiO_Cloud

The Client ID for id.appuio.cloud within id.vshn.net

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 = https://id.appuio.cloud/auth/realms/appuio-cloud/broker/vshn/endpoint*

  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 = https://id.vshn.net/auth/realms/vshn-realm/protocol/openid-connect/auth
Token URL = https://id.vshn.net/auth/realms/vshn-realm/protocol/openid-connect/token
Logout URL = https://id.vshn.net/auth/realms/vshn-realm/protocol/openid-connect/logout
User Info URL = https://id.vshn.net/auth/realms/vshn-realm/protocol/openid-connect/userinfo
Client Authentication = "Client secret sent as post"
Client ID = VSHN_to_APPUiO_Cloud
Client Secret = <The secret displayed in id.vshn.net 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 = appuio.io/default-organization
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