Setting up Keycloak as an OpenID Connect provider

Download and start Keycloak

Keycloak and a Postgres backend can be set up conveniently using Docker and docker-compose. Here is an example for a possible docker-compose.yml file:

version: '3.3'
services:
 
  postgres:
    image: "postgres:10"
    ports:
      - 5432:5432
    environment:
      - POSTGRES_USER=keycloak
      - POSTGRES_PASSWORD=keycloak
      - POSTGRES_DB=keycloak
    volumes:
      - ./pgdata:/var/lib/postgresql/data
 
  keycloak:
    image: "jboss/keycloak:latest"
    ports:
      - 8080:8080
    depends_on:
      - "postgres"
    environment:
      - DB_VENDOR=postgres
      - DB_ADDR=postgres
      - DB_PORT=5432
     #- KEYCLOAK_LOGLEVEL=DEBUG
      - DB_DATABASE=keycloak
      - DB_USER=keycloak
      - DB_PASSWORD=keycloak
      - KEYCLOAK_USER=keycloak
      - KEYCLOAK_PASSWORD=keycloak

Refer to Keycloak's Docker Hub page for details.

Create a realm

The latest Keycloak documentation can be found here. Create a new realm within Keycloak with default settings.

Create a client for Border Gateway

We need to create a client for Border Gateway in the newly created realm. Border Gateway uses information included in access tokens to answer authorization requests. Authorization rules will be added to access tokens in custom attributes (see below). Also Border Gateway relies on the client id to be included in the "aud" field of an access token. In case of Keycloak, this means we need to create a mapper for the audience field (also see below).

1. Create a new client (e.g. call it "bgw_client")
2. Got to tab "Settings" and set buttons "Standard Flow Enabled" and "Direct Access Grant Enabled" to On. Add https://<your_domain_used_in_certificate>:443/callback to "Valid Redirect URIs".
3. Go to tab "Mappers" and create the following mappers:
   • Audience mapper:
     • Choose "Audience" as "Mapper Type".
     • Enter "add_client_id_as_audience" in "Name" field.
     • Choose "bgw_client" as "Included Client Audience".
     • Make sure "Add to access token" is on.
   • User attribute mapper:
     • Choose "User Attribute" as "Mapper Type".
     • Enter "bgw_rules" in fields "Name", "User Attribute" and "Token Claim Name".
     • Make sure "Add to access token" is on.

• • Group attribute mapper (optional - only if you have user groups defined in Keycloak and want to use them for authorization):
    • Choose "User Attribute" as "Mapper Type".
    • Enter "bgw_rules_<group_name>" in fields "Name", "User Attribute" and "Token Claim Name".
    • Make sure "Add to access token" is on.

Add rules to users and groups

Rules are defined as custom attributes that are then included in the access token. The rules format allows wildcards # and + in the same way it is commonly used for MQTT topics. See Authentication and Authorization.

• Add an attribute for a specific user with key "bgw_rules". Multiple rules should be separated with spaces.
• Add an attribute for a specific group key "bgw_rules_<group_name>" and make sure you have the . Multiple rules should be separated with spaces.