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

Identity Providers Identity Broker
They are used to manage user accounts and configure them with the proper roles & groups so that they can access the ressources needed.
In this context, the Identity Provider Administrators are responsible for providing the correct information for each user: they are focused on information accuracy and integrity, not platform interconnexions.
Their role is to connect to external ressources using dedicated clients.
They will import user details from Identity Providers and User Federation and enrich it using automatic mapping rules.
The Identity Broker\'s Administrators will be focused on configuring the clients and the mapping rules properly but will not manage users.

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:

File docker-compose.yml Mandatory File at the root of the directory containing our running image configuration (see below)
Folder certs Optional Folder where the Letsencrypt certificate files will be stored.
Requires volume to be declared in docker-compose.yml:
- /opt/keycloak/certs/fullchain.pem:/etc/x509/https/tls.crt
- /opt/keycloak/certs/privkey.pem:/etc/x509/https/tls.key
Folder data Optional If you want to have persistence in the Keycloak data.
Requires volume to be declared in docker-compose.yml:
- /opt/keycloak/data:/opt/keycloak/data/

docker-compose.yml

keycloakIdP
keycloakAuth
    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

      Client ID Value of your choice.
      For our example: keycloakauth.
      Client Protocol For our example: openid-connect.
      Root URL Value of your choice.
      For our example: left empty

      Step 2: Client details

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

      Here are the important points:

      Parameter Value to set
      Enabled You can disable clients used for test purposes or because an integration is no longer needed but you don't necessarily want to loose the configuration details.
      For our example: On.
      Access Type We need a private client so that we can use client ID and Secret as authenticator.
      For our example: Confidential.
      Standard flow enabled For our example: On.
      Direct Access Grants Enabled Enables use of username & password in authentication.
      For our example: On.
      Service Accounts Enabled By default On.
      For our example: On.
      Authorization Enabled Allows for fine-grained authorization if On.
      For our example: On.
      Valid Redirect URIs URI pattern platform can redirect to.
      Use the URL for your Identity Broker using a wildcard.
      For our example: https://auth.nicksopenworld.com/*.

      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.

      0 0 votes
      Article Rating
      Subscribe
      Notify of
      guest
      0 Comments
      Inline Feedbacks
      View all comments
      0
      Would love your thoughts, please comment.x
      ()
      x