# Single Sign-On

TIP

This documentation is In Progress

Hume integrates with Keycloak (opens new window) for Single Sign-On.

Keycloak is an Identity and Access Management system support by RedHat. It provides out of the box advanced features such User Federation, Identity Brokering and Social Login.

# Architecture

When SSO is configured in Hume with Keycloak, users are not managed by Hume anymore. The users are managed in the Keycloak Realm client and perform login on a dedicated secure page served by the Keycloak server.

Once successfully logged in, they are provided a token that the frontend application will use for any request to the Hume API. The Hume API will use this token and determine what are the permissions the logged in user has based on the information available in the token.

# Installation

Create a dedicated docker-compose file with the following content :

version: "3.7"
services:
  postgres:
      image: postgres:12.0
      volumes:
         - /datadisk/data/postgres2:/var/lib/postgresql/data
      environment:
        POSTGRES_DB: keycloak
        POSTGRES_USER: keycloak
        POSTGRES_PASSWORD: password
      command: -p 5433
      ports:
        - "5433:5433"
  keycloak:
      image: quay.io/keycloak/keycloak:10.0.1
      environment:
        - DB_VENDOR=POSTGRES
        - DB_ADDR=postgres
        - DB_PORT=5433
        - DB_DATABASE=keycloak
        - DB_USER=keycloak
        - DB_SCHEMA=public
        - DB_PASSWORD=password
        - KEYCLOAK_USER=admin
        - KEYCLOAK_PASSWORD=s3cr3tp@ss
        - PROXY_ADDRESS_FORWARDING=true
      ports:
        - 8090:8080
      depends_on:
        - postgres

Start the containers :

docker-compose up -d

And you can now login to Keycloak on http://localhost:8090 (opens new window)

Keycloak Login

And use the admin / s3cr3tp@ss credentials to login.

# Keycloak Configuration

# Create a Realm

Realm is a concept in Keycloak that refers to an object managing a set of users along with their credentials, roles and groups. A user in Keycloak belongs to only one realm and the user who logs in to Keycloak will log into that user’s realm. We can have multiple realms in a Keycloak server, these realms will be independent of each other and they only manage their users.

Create the Realm by clicking on Realms > Add Realm , specify hume as the realm name, finish by clicking on the create button.

Keycloak Login

# Create a Client

Clients are entities that can request Keycloak to authenticate a user. Most often, clients are applications and services that want to use Keycloak to secure themselves and provide a single sign-on solution.

We will create a hume-web client.

Go to Clients and click Create

Keycloak Login

Specify hume-web as the client name :

Keycloak Login

And click on Save.

Edit the client by clicking on its name or on the Edit button in the clients list. And provide then the following configuration :

Keycloak Login

# Add Roles to the Client

Client Roles are Roles that are specific to a client application. In our case, roles should be the same roles that we will use in our Hume application.

Create the following roles :

Keycloak Login

# Create a User

# Create the User identity

Go to Users > Add User

Give a username to the user, here humeadmin that will represent our Hume application administrator account. And click on the save button.

Keycloak Login

# Provide the default User credentials

Then click on the Credentials tab and provide credentials to the user, for example changeme, leaving the Temporary switch to On so that the first time the user will log in, the user will have to change the default password we just provided.

Keycloak Login

# Assign roles to the User

Go then to the Role Mappings tab. Here we will assign roles from our hume-web client to the created user.

Select the client, start by typing hume-web :

Keycloak Login

And select roles from the left column and click on the Add selected button to move them to the right column.

Keycloak Login

We gave this user the ADMINISTRATOR and USER roles which are Hume built-in roles.

Keycloak is now configured to act as identity and access management server for our Hume application, with the hume realm and there is one configured client, the hume-web client.

We now need to configure Hume itself to act as a client of the Keycloak server.


# Hume Configuration

To configure Hume, we will need to modify two services. The web (frontend) service so that when it receives a 401 Unauthorized response from the api, it has to redirect the user to the secure login page on the Keycloak server.

We will also need to modify the api service to switch from native to keycloak authentication provider. For every request to the api, it will validate the token to the Keycloak server and instantiate the user object internally with the roles provided in the token.

# Web service configuation

The web service section in your docker-compose.yml file should look like this. The urls of the API and the Keycloak server might differ based on your infrastructure.

web:
    image: docker.graphaware.com/public/hume-web:{{hume_version}}
    restart: always
    environment:
      - HUME_API_URL=http://localhost:8080
      - KEYCLOAK_ENABLED=true
      - KEYCLOAK_URL=http://localhost:8090/auth/
      - KEYCLOAK_REALM=hume
      - KEYCLOAK_CLIENT=hume-web

# Api service configuration

The api service should contain the following :

api:
    api:
    image: docker.graphaware.com/public/hume-api:{{hume_version}}
    restart: always
    ports:
      - "8080:8080"
    environment:
      ... // initial configuration not included for brevity
      - hume.security.provider=keycloak
      - keycloak.auth-server-url=http://localhost:8090/auth
      - keycloak.realm=hume
      - keycloak.resource=hume-web
      - keycloak.public-client=true
      - keycloak.principal-attribute=preferred_username
      - keycloak.use-resource-role-mappings=true
      - keycloak.enabled=true

# Login into Hume with SSO

Restart Hume and going to http://localhost:8081 (opens new window) will now redirect you to the secure login page of keycloak and prompt you to change your password.

Keycloak Login

After changing it, you will be redirect to Hume and logged in as the humeadmin user with the ADMINISTRATOR and USER roles.

Keycloak Login

You've now successfully configured Single Sign-On with Hume. Note that you will have to replicate the roles created in Hume (Custom roles) in the Keycloak realm client as well so they can be assigned to users.