Preamble & pre-requisites

This article is an update on a frequently referenced article: "Keycloak as an Identity Broker & an Identity Provider" by Abhishek Koserwal in 2020.

If you don\'t know how to set up Keycloak, check out the "Set up Keycloak to manage your users and their access to tools and platforms" article.

Why set up Keycloak as both Identity Provider and Broker ?

Option 1 : Internal structure of your organisation: securing your tools through task segregation

In this scenario, you could have:

• a team in charge of user configuration, for example HR.
• another team in charge of technical interconnexion

This limits access to technical configuration by non-technical users.
It also provides a level of confidentiality regarding user information in the Identity Provider as not all user details need to be pushed to Identity Brokers.

Option 2 : when connecting ressources from 2 (or more) different organisations using Keycloak

This scenario applies usually for bigger companies with offices in different locations or countries, each location having it\'s own local IT service meaning ressources are dupplicated.

An easy way to centralize user access management is to push all through a common portal: the Identity Broker Keycloak platform.

Technical set up

Technical context

For the following examples, we will be setting up 2 separate Keycloak instances using Docker-compose based containers using PostgreSQL databases hosted on dedicated DB servers.

Both Keycloak containers will be running on the same Ubuntu 22.04 server but expose different ports which will allow us to assign different sub-domains for each instance through Traefik.

And Traefik will handle the HTTPS certificates generation and renewals.

Files and folders configuration & setup

For this demonstration, 2 sub-directories have been created in /opt:

• /opt/keycloakIdP/
• /opt/keycloakAuth/

Both folders will use the same file & folder structure:

docker-compose.yml

version: "3.9"
services:
  keycloakidp:
    image: quay.io/keycloak/keycloak:22.0.5-0
    container_name: keycloakidp
    command: ['start']
    logging:
      driver: syslog
      options:
        tag: idp
    restart: always
    ports:
      - "1111:8080"
    environment:
      JAVA_OPTS_APPEND: -Dkeycloak.profile.feature.upload_scripts=enabled
      KEYCLOAK_ADMIN: admin
      KEYCLOAK_ADMIN_PASSWORD: keycloak
      KC_DB: postgres
      KC_DB_URL_HOST: 192.168.22.22
      KC_DB_URL_PORT: 5432
      KC_DB_URL_DATABASE: keycloakidp
      KC_DB_USERNAME: keycloakidpdbadmin
      KC_DB_PASSWORD: 'AverysecureDBpassw0rd'
      KC_DB_SCHEMA: public
      KC_HOSTNAME_STRICT: 'true'
      KEYCLOAK_LOGLEVEL: INFO
      ROOT_LOGLEVEL: INFO
      KC_HEALTH_ENABLED: 'true'
      KC_HTTP_ENABLED: 'true'
      KC_METRICS_ENABLED: 'true'
      KC_PROXY: reencrypt
      KC_HOSTNAME_URL: https://idp.nicksopenworld.com
      KC_HOSTNAME_ADMIN_URL: https://idp.nicksopenworld.com
    networks:
      - local
networks:
  local:
    name: local
    driver: bridge

version: "3.9"
services:
  keycloakauth:
    image: quay.io/keycloak/keycloak:22.0.5-0
    container_name: keycloakauth
    command: ['start']
    logging:
      driver: syslog
      options:
        tag: auth
    restart: always
    ports:
      - "9999:8080"
    environment:
      JAVA_OPTS_APPEND: -Dkeycloak.profile.feature.upload_scripts=enabled
      KEYCLOAK_ADMIN: admin
      KEYCLOAK_ADMIN_PASSWORD: keycloak
      KC_DB: postgres
      KC_DB_URL_HOST: 192.168.22.22
      KC_DB_URL_PORT: 5432
      KC_DB_URL_DATABASE: keycloakauth
      KC_DB_USERNAME: keycloakauthdbadmin
      KC_DB_PASSWORD: 'AnothersecureDBpassw0rd'
      KC_DB_SCHEMA: public
      KC_HOSTNAME_STRICT: 'true'
      KEYCLOAK_LOGLEVEL: INFO
      ROOT_LOGLEVEL: INFO
      KC_HEALTH_ENABLED: 'true'
      KC_HTTP_ENABLED: 'true'
      KC_METRICS_ENABLED: 'true'
      KC_PROXY: reencrypt
      KC_HOSTNAME_URL: https://auth.nicksopenworld.com
      KC_HOSTNAME_ADMIN_URL: https://auth.nicksopenworld.com
    networks:
      - local
networks:
  local:
    name: local
    driver: bridge

As you can see, the files are the same just using different databases and sub-domains.

Note: these examples use a web domain but if you want to do a local deployment, simply replace the domain values by http://localhost:port

If both Keycloak services run on the same host server, they could be managed in one docker-compose file rather than splitting them but having it this way allows us to modify 1 platform with absolutely no risk to the other.

Configure the IdP platform

First log-in: securing Admin account

Connect to the UI using the credentials defined in the docker-compose.yml by the KEYCLOAK_ADMIN_PASSWORD variable and promptly update that password in the User management of the Master Realm.

Note: make sure it's not a temporary password.

Create your test user

While you're in the user management, add a new user with just the basic information:

• First name
• Last name
• Username
• Email

And set up a password.
Note: make sure it's not a temporary password.

Dedicated Realm creation and information retrieval

Then create a new Realm.
For our example, we have created the Realm "IDP".

We then need to retrieve the different URL values to be used to configure the Identity Provider entry in the Identity Broker Keycloak:

You can either click on "OpenID Endpoint Configuration" and access the content through the broswer of right-click on the link and save it to a JSON file.

Setting up client for the Identity Broker

Go to Clients and create a new client.

Step1: General parameters

Step 2: Authentication parameters

The client creation will ask the Authentication requirements and flow:

Then go to the Credentials tab:

• Regenerate the secret
• Show and save the Client secret value

Step 3: URLs and redirect URIs configuration

Here, we will simply put the Root URL value as the URL for our Identity Broker with a wildcard:

https://auth.nicksopenworld.com/*

It\'s important to note that these values can be updated later on so once we have a working system, we will be able to proceed with hardening measures such as setting the allowed web origins.

Configure the Broker platform

First log-in: securing Admin account

Connect to the UI using the credentials defined in the docker-compose.yml by the KEYCLOAK_ADMIN_PASSWORD variable and promptly update that password in the User management of the Master Realm.

Dedicated Realm creation and information retrieval

Then create a new Realm.
For our example, we have created the Realm "nicksopenworld".

Setting up the entry for the Identity Provider

Go to Identity providers and add a Keycloak OpenID Connect entry:

By default, Keycloak offers to import the Identity Provider information by using the ./well-known discovery endpoint:

We will disable this in order to upload the JSON file containing the IdP details generated in the previous steps:

Most of the fields will be automatically updated.
Only remain the client ID and Client Secret fields to be filled in:

And you can update :

• the Identity provider Alias
• the Display name: string that will be used on the login page
  For our example: Keycloak IDP 9999

Then click "Add".

You should now have an additional button corresponding to the added Identity provider on your Identity Broker page:

https://KEYCLOAK_DOMAIN/realms/REALM_ID/account/

For our example, it would be:

https://auth.nicksopenworld.com/realms/nicksopenworld/account/

Note: URL doesn't work.

Click on "Sign in" and check the login page for a button matching the Identity Provider entry's Display name:

Testing authentication

Simply click on the "Keycloak IDP 9999" button and use the credentials for the test user created at the start of the setup.

If all works well, you will be redirected to the user account page on the Identity Broker Keycloak.

And when connected as an Administrator, you should now see your test user in the Users management menu of your Identity Broker Realm:

Fine tuning the information sent from the IdP to the Broker

On the Identity Provider platform

Go back to the keycloakauth client:

• In the Roles tab, you can add roles and assign them to users.
  This allows you to enrich the user information with role-specific Attributes, which in turn can be pushed to the Broker and allow ressource access filtering based on assigned roles.
  

• In the Client scopes tab, you can define the user information that should be sent to the Broker by keeping it or removing it and also decide if this information is Optional or not.
  For example the user address information is rarely needed by the Brokers for Authentication purpose so we could remove it from the Keycloakauth's client scope.

On the Identity Broker platform

Open the Identity Provider entry we have created and go to the Mapper tab: this allows you to redirect or transform some of the information.

This allows you for example to map roles or groups from the Identity Provider platform to roles on the Identity Broker platform.

But it can also allow automatic conditional attribute assignment for users based on the information sent by the Identity Provider.

Check out the Mapping claims and assertions for more information.

Conclusion

So now any user created on the Keycloak Identity Provider platform ( https://idp.nicksopenworld.com ) should be able to log into the Keycloak Identity Broker platform ( https://auth.nicksopenworld.com ).

And if we want to add access to platforms/applications, we simply need to configure the appropriate clients on the Identity Broker platform and make sure the needed information is sent by the IdP to the Broker through proper client scope and Identity Provider mapper configuration.