To develop an application in VSETH it will be necessary to implement an authentication flow. To test this while developing locally you can include a Keycloak container in your docker-compose orchestration and set up your user, groups and serviceaccounts once. This guide explains how you can do this to improve your local development process.

Flowable and gsuite-api already use such a setup.

docker-compose setup

You have to include the official keycloak container as a service in your docker-compose.yaml file.

  keycloak:
    container_name: keycloak
    image: jboss/keycloak:15.0.2
    environment:
      - KEYCLOAK_USER=keycloak
      - KEYCLOAK_PASSWORD=keycloak
      - DB_VENDOR=h2
    command: -Dkeycloak.migration.action=import -Dkeycloak.migration.provider=singleFile -Dkeycloak.migration.file=/tmp/realm-export.json -Dkeycloak.migration.strategy=OVERWRITE_EXISTING
    volumes:
      - "$PWD/keycloak/realm-export.json:/tmp/realm-export.json"
    ports:
      - "8181:8080"

When you start this service with docker-compose you can access localhost:8181 and log in with the admin user keycloak. This user and its password is specified in the environment variables. The command and the volume make it possible to have an export of your keycloak realm in your repository, that keeps all your configurations.

You need to setup the environment of your application to match the SIP configuration, by setting the following environment variables in the service of your application:

environment:
      - SIP_AUTH_OIDC_JWKS_URL=http://keycloak:8080/auth/realms/test/protocol/openid-connect/certs
      - SIP_AUTH_BACKEND_CLIENT_ID=my-application-client

Keycloak setup

You can find a simple getting started guide here:  https://www.keycloak.org/getting-started/getting-started-docker

Create a realm

Creating a realm is quite straight forward, just click on the current master realm at the top left of the admin interface, choose a name (i.e. local-test-realm) and be sure to have Enabled at ON. You might want to create different realms to test different scenarios.

Create a client for your application and its roles

When creating a client make sure to choose openid-connect as client protocol. In the settings choose Access Type bearer-only. 

In the roles tab you can now create any roles your application knows.

Create a group

Just click on the group item in the menu and click New. When selecting an existing group and creating a group, you create a subgroup.

In the Role Mappings tab of a group you can assign a role of your client to a group.

You have to manage the members of a group via users.

Create a user

You can create a user by choosing a username. You can then in the menu of a user assign it to groups and assign client roles. You can also change and get its credentials. 

Create a serviceaccount

A serviceaccount is a client with a different configuration than the application client. You create the serviceaccount client with openid-connect as client protocol. In its settings you set the access type to confidential, the Standard Flow Enabled to OFF and Service Accounts Enabled to ON. After saving those changes you can assign this client/serviceaccount roles in the Service Account Roles tab. 

Export your realm

You do not want to do this setup work everytime you restart your keycloak container, so you need to export your configuration. This way you save all your realms into a JSON file. Your container still needs to run when you execute this. When the export is done, you will get the message, that keycloak has started - then you can press Ctrl+C.

docker exec -it keycloak /opt/jboss/keycloak/bin/standalone.sh -Djboss.socket.binding.port-offset=100 -Dkeycloak.migration.action=export -Dkeycloak.migration.provider=singleFile -Dkeycloak.migration.usersExportStrategy=REALM_FILE -Dkeycloak.migration.file=/tmp/realm-export.json

This command only exports the realm into the keycloak container, so you still need to copy it to your local directory. 

docker cp keycloak:/tmp/realm-export.json keycloak/realm-export.json

The export should be saved to the correct location in your project, because it is mapped in the docker-compose.yaml file to its location in the container.