Friday, January 31, 2020

Configuring Kheops with Keycloak

This post discusses how to install Kheops and Keycloak in 2 Centos 7 VMs.

First, install docker and docker-compose in both VMs.

You may also need to add the user to docker group

$ sudo usermod -aG docker $USER

and either log out and log in again (or restart, in case of a VM).


Install Keycloak with Docker, together with a user account

First, create a fullchain.pem and privkey.pem from Letsencrypt.

Step 1: Keys!

Two options.

Option 1: Copy and rename the crt and key

$ cp keys-keycloak/fullchain.pem https/tls.crt

$ cp keys-keycloak/privkey.pem https/tls.key

Option 2: Create the crt and key with OpenSSL.

Alternatively, the crt and key can be created as below.

$ openssl x509 -outform der -in fullchain.pem -out tls.crt

$ openssl rsa -in privkey.pem -out tls.key

Move the tls.crt and tls.key to a separate folder (https) and cd to that directory.

Step 2. Set the permissions for the keys

$ cd https

$ chmod 700 .

$ chmod 600 tls.key

$ chmod 644 tls.crt

Step 3. Run the Keycloak container

$ docker run -d -p 443:8443 -e KEYCLOAK_USER=pradeeban -e KEYCLOAK_PASSWORD=password -v /home/pradeeban/https:/etc/x509/https --name kc jboss/keycloak

Keycloak will use port 443/https.

Now go to https://HOSTNAME

Log in with the user name and password you specified before.

Step 4. Now to configure a log in connect for Kheops

First create a new realm with the name, "demo".

1. Keycloak KHEOPS Login Client

Click the "Clients" tab, and choose the "Create" option.

Client ID = loginConnect

Click "Save", which will then open more configurations for the "LoginConnect" that you just created.

Turn on the option "Implicit Flow Enabled"

Turn off the "Direct Access Grants Enabled"

Valid Redirect URIs: https://KHEOPS-HOME/*

(for example:*)

Web origin: https://KHEOPS-HOME

(for example:

Click "Save" again.

2. Client Scope (kheops)

Click the "Client Scopes" tab, and choose the "Create" option.

Name: kheops

Turn off the "Display On Consent Screen"

Click "Save"

Click "Clients" again and go to "LoginConnect"

Go to the "Client Scopes" tab.

Choose "kheops" from the Available Client Scopes and choose the "Add selected" option. Remove all the other options from the Assigned Default Client Scopes as well as Assigned Default Client Scopes.

Add the email and full name token mappers to the kheops Client Scope by clicking on the Add Builtin button.

3. Service Account

Create another client "kheopsAuthorization".

Save, and then disable "Standard Flow Enabled" and "Direct Access Grants Enabled".

Change "Access Type" to "Confidential". and save.

Change "Service Accounts Enabled" to "On" and save.

The Service Account’s credentials (secret) can be found under the Credentials tab.

Choose the "KheopsAuthorization" Scope mappings. Under the "scope", disable "Full Scope Allowed" option. Choose "realm-management" as the "Client Roles", and add "view-users" option.

Now, repeat the above step for "Service Account".

The Service Account’s credentials (secret) can be found under the Credentials tab. Copy it to replace the default secret provided in kheopsDocker/kheops/secrets/kheops_keycloak_clientsecret, or provide it as the secret when prompted during the Kheops configuration.

4. Logging Impersonations

Under the "LoginConnect" client's Mappers tab, click "Add Bulletin", and add the Impersonator User ID."

Change the "Token Claim Name" to "act.sub". Then disable "Add to ID token" option.

Finally, click "Save". This is supposed to conclude the configurations unless I missed something.

Export your realm for later use from the host:

$ docker exec -it kc /opt/jboss/keycloak/bin/ -Dkeycloak.migration.action=export -Dkeycloak.migration.provider=singleFile  -Djboss.http.port=8888 -Djboss.https.port=9999 -Dkeycloak.migration.file=kkconf.json

Copy the file to the host machine, from the Docker container.

$ docker cp kc:/kkconf.json .

At the time of writing, Keycloak documentation had some issues that are fixed in the above command. 
Then next time, you can easily import this realm, rather than configuring everything from scratch:
    -e KEYCLOAK_IMPORT=/tmp/example-realm.json -v /tmp/example-realm.json:/tmp/example-realm.json jboss/keycloak 


Step 5: Configure Kheops


Run Kheops with Docker

$ git clone

$ cd kheopsDocker

$ git checkout install-secure

$ sh            [See footnote at the end of this post].

Follow the prompts.

Enter the secret: Enter the secret copied from Keycloak in the previous step.

What is the Keycloak host ? (ex:

What is the Keycloak realm ? demo

What is your hostname ? (ex:

Add your public and private key in the directory kheops/secrets (fullchain1.pem / privkey1.pem)

$ cp keys-kheops/fullchain.pem kheopsDocker/kheops/secrets/fullchain1.pem

$ cp keys-kheops/privkey.pem kheopsDocker/kheops/secrets/privkey1.pem

Press enter to start KHEOPS

Now, access Kheops from

To enable registrations of new users for Kheops, go to Realm Settings -> Login tab in your Keycloak instance and turn on User registration. If you do not want to allow anyone to create an account, you may instead click on Users -> Add user to manually create users.

Feb 19, 2020: As of today, there is a minor tweak needed for this to get working.

In the .env file, set:
before running the


  1. Hi,
    thanks for your previous answer. I followed your advice and switched to a two VM setup. I then repeated all the steps suggested in this post and now kheops is able to connect to keycloack. I configured keycloak exactly as you suggest here, but the rendering of the login form fails at this point:

    login-status-iframe.html:70 GET 403

    "entrolytics" is the domain that links to the kheops VM.
    it looks like there is something still missing in the configuration.
    Thanks, cheers

    1. Did you try the last suggestion in ?

      I found it by a Google search of your error.

  2. Thank you. I was able to complete the setup and Kheops and keycloak are able to interact. Later on, I enabled User registration in the way you suggest, I registered and started to use the platform.
    There is still an issue however, whenever I interact with the Kheops UI doing something like loading the study list or creating a new album, the corresponding API call (to one of the /api endpoints) returns "401 Unauthorized". I'm trying to figure out what is still missing. Cheers

    1. Probably you are accessing when the account is logged out? Browser caches?

      Use an incognito window, register a new account, log in, and then try what you were trying?

    2. I am struggling with the same error Gianni. Did you solve the problem?

  3. I'm testing from an incognito window, I always have the same error. From the Kheops docker-compose logs I can see the /api calls to load the studies and albums generate this exception:

    03-Mar-2020 09:13:57.035 WARNING [http-nio-8080-exec-7] online.kheops.auth_server.filter.SecuredFilter.filter User not found http://....../authorization/albums?limit=50&offset=0&sort=-last_event_time
    kheopsauthorization | online.kheops.auth_server.user.UserNotFoundException: online.kheops.auth_server.keycloak.KeycloakException

    If I go to the Keycloak admin console I can see the User without problems.
    I double checked the official keycloak docs about installation and matches the configuration that I have.


    1. Did you follow the footnote in red font, in the end of this blog post?

  4. yes, I did.
    I also repeated the installation process multiple times, but the result is the same.
    It looks like the authentication flow is working (login, token generation, etc), but the
    authorization flow (kheopsAuthorization in Keyloack) is not.
    It seems the authorization server is not able to match the user Id in the access token to any user,
    but I decoded the token and verified that indeed matches the one in Keycloak.

    1. Are you using the RESTful interfaces to invoke the API or invoke the Kheops web interface through browser? I have never tested the RESTful interfaces directly. So I cannot talk much about that.

  5. No, I'm just using the browser, the behaviour is the same in all browsers,
    whenever the 'inbox' or 'albums' view is refreshed/open, the corresponding /api calls fail.
    I have the system running on two VMs in DigitalOcean.

    1. ok, I couldn't guess what could be going wrong. Probably you need to consult the Kheops to ask for further assistance.

  6. Hi Pradeeban Kathiravelu, Ph.D.Hello, requesting your support. I already have a secure instance of kheops with keycloak in separate vms running without problem. Now I want to incorporate kibana which already installs the containers indicated in the docker-compose.yml. my open ports 8081, 80 and 443 but the proxy nginx only has 443 and 80. how do i add 8081 to reach kibana from https. Best regards


You are welcome to provide your opinions in the comments. Spam comments and comments with random links will be deleted.