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

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: 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

      Client Type OpenID Connect
      Client ID Value of your choice.
      For our example: keycloakauth.
      Name Value of your choice.
      For our example: ${client_broker}.
      Description Value of your choice.
      For our example: left empty
      Always displace in UI If active, this client will always be visible in the Account UI, even if the user does not have an active session..
      For our example: Off.

      Step 2: Authentication parameters

      The client creation will ask the Authentication requirements and flow:

      Parameter Value to set
      Client authentication If Off, the client is considered public.
      We need a private client so that we can use client ID and Secret as authenticator.
      For our example: ON.
      Authorization Allows for fine-grained authorization if On.
      For our example: Off.
      Authentication flow Indicates the flow(s) we want that client to support.
      For our example: Standard flow, Direct access grants and Service accounts roles.

      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.

      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