Preamble & pre-requisites

!! WARNING !! .

This article is for an obsolete and no longer supported version of Keycloak but for which there is still a large userbase.
To see the article based on the currently maintained version as of November 2023, please check Use Keycloak as both Identity Broker using Keycloak as Identity Provider – Based on Keycloak Quay.io v22.0.5

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: jboss/keycloak:16.1.1
    container_name: keycloakidp
    logging:
      driver: syslog
      options:
        tag: keycloakidp
    restart: always
    ports:
      - "1111:8080"
    environment:
      KEYCLOAK_USER: admin
      KEYCLOAK_PASSWORD: keycloak
      DB_VENDOR: postgres
      DB_ADDR: 192.168.22.22
      DB_DATABASE: keycloakidp
      DB_USER: keycloakidpdbadmin
      DB_PORT: 5432
      DB_PASSWORD: 'AverysecureDBpassw0rd'
      PROXY_ADDRESS_FORWARDING: "true"
      KEYCLOAK_LOGLEVEL: DEBUG
      ROOT_LOGLEVEL: DEBUG

version: "3.9"
services:
  keycloakauth:
    image: jboss/keycloak:16.1.1
    container_name: keycloakauth
    logging:
      driver: syslog
      options:
        tag: keycloakauth
    restart: always
    ports:
      - "9999:8080"
    environment:
      KEYCLOAK_USER: admin
      KEYCLOAK_PASSWORD: keycloak
      DB_VENDOR: postgres
      DB_ADDR: 192.168.22.22
      DB_DATABASE: keycloakauth
      DB_USER: keycloakauthdbadmin
      DB_PORT: 5432
      DB_PASSWORD: 'AnothersecureDBpassw0rd'
      PROXY_ADDRESS_FORWARDING: "true"
      KEYCLOAK_LOGLEVEL: DEBUG
      ROOT_LOGLEVEL: DEBUG

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_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: Client details

Once client is saved, you can see all the available parameter to be set.

Here are the important points:

Other parameters can be left to their default value.

Then go to the Credentials tab:

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

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_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 or OpenID Connect entry:

We have saved the JSON file containing the IdP details in the previous steps so we will now upload the file:

• Go at the botton of the page
• Upload the JSON file
• Click on Import
• Save the Identity Provider entry

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

• Client authentication can work when set at Client secret sent as post so we'll keep this. Other options can be used depending on the level of security hardening you want to apply.
  

• client ID and Client Secret are the values generated in the Identtity Provider platform's client setup.
  

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:///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 Mappers 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.