Keycloak Integration

Keycloak Integration

ohmage 2.18.0 offers integration with the keycloak project to support external authentication with ohmage. Rather than offering a new feature to support each of oauth2, ldap, saml, the keycloak project allows us to integrate and abstract each of these methods through the support of keycloak. The instructions below are a primer on getting started with our integration. Before integrating, you may be interested in the JWT spec that allows all of this to happen with a reasonable amount of trust!

Setting up keycloak

Please follow the project's detailed install instructions to get started. If you're looking for an extremely fast setup just to test, we'd recommend their docker container or their openshift gear.

Once you have keycloak running, you can integrate with a number of different services. To keep things simple, we'll just use internal keycloak users instead of google/facebook/ldap or saml integration for the remainder of this "tutorial".

clients, and keycloak.json

The main requirement to use ohmage with keycloak is the addition of two keycloak clients, one for the ohmage client-side javascript, and one for the ohmage api server. Create a realm to hosue these in (keycloak allows for many "realms" to offer one keycloak server/cluster to offer many different authentication methods to many different sets of servers). After creating a realm (we'll call ours "sample-realm") you can get started creating some clients. Note the client names below are not hardcoded, we've just picked "js" and "ohmage" for clarity of purpose.

js

Creating a new client should look a bit like this:

Most importantly, you need Access Type to be set to "public" and the root url, valid redirect uri and web origins set to values that match the domain your frontend will be served from.

Once you're that far, you can click the "installation" tab, and select the json option. It should look a bit like this:

{
  "realm": "sample-realm",
  "realm-public-key": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA0ZYJD2FnmUTbnU02UYh5+ptuirIxOzU41Hq7RtuSxQkeTDXWqdwrDwEfXUN7R20fBh5ZKJ/VuCqLQ0fsOHA8ctHJ5YwqzenKmpoNcXubInwPApspGi7nIikpRWK2F583DcLR+QJytLEDriRFtudMdM3E7cdQNXdabG6+IhJkc6k/aQNRCUgHAXKR/2BPNhE8Gs1vpKNBxQMe+98s4sxnw/PlOXSPofgiFUByc788inujDWOMLeb0FmHB1svow5ArYBbWy1yFNPmpocY8iy5l3+adqWIIp9q6OB+lJfCtOPp6Btp+dptkPdthiGftq1oyICN5KQNGgfQCmXbszWXpaQIDAQAB",
  "auth-server-url": "https://keycloak-sample.example.com/auth",
  "ssl-required": "external",
  "resource": "js",
  "public-client": true
}

This file (named, very importantly, keycloak.json) can be added at the root of the mobilizingcs/navbar project. The navbar (which handles logins for ohmage) will take care of the rest on the client-side.

ohmage/backend

This client will be set up similarly to the js client, with the noticeable difference that it is intended to be "bearer-only" (meaning, the API server cannot actually log a user in, only validate the use of an existing user's JWT from keycloak).

Create a new client with Access Type set to "bearer-only" and grab the json output, which will be similar to the above:

{
  "realm": "sample-realm",
  "realm-public-key": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA0ZYJD2FnmUTbnU02UYh5+ptuirIxOzU41Hq7RtuSxQkeTDXWqdwrDwEfXUN7R20fBh5ZKJ/VuCqLQ0fsOHA8ctHJ5YwqzenKmpoNcXubInwPApspGi7nIikpRWK2F583DcLR+QJytLEDriRFtudMdM3E7cdQNXdabG6+IhJkc6k/aQNRCUgHAXKR/2BPNhE8Gs1vpKNBxQMe+98s4sxnw/PlOXSPofgiFUByc788inujDWOMLeb0FmHB1svow5ArYBbWy1yFNPmpocY8iy5l3+adqWIIp9q6OB+lJfCtOPp6Btp+dptkPdthiGftq1oyICN5KQNGgfQCmXbszWXpaQIDAQAB",
  "bearer-only": true,
  "auth-server-url": "https://keycloak-sample.example.com/auth",
  "ssl-required": "external",
  "resource": "ohmage"
}

This file needs to be available to ohmage. To make that a bit easier, the ohmage.conf tells ohmage where to look by the use of the parameter: keycloak.config=/path/to/keycloak.json.

Enabling keycloak authentication in ohmage

Now that you have a keycloak.json file, ohmage will parse it on app start and attempt to contact the keycloak server to make sure everything in that file checks out. Assuming all has gone well, ohmage is ready to use keycloak. However! We still need to enable it in the app. This is done by editing the ohmage preferences table like so: update preference set p_value= 'true' where p_key = 'keycloak_enabled';. Once you've done this, you should notice that the navbar on login now has a new button, which will send the user to keycloak to authenticate.

[OPTIONAL] Disabling local authentication in ohmage

Now that you can have keycloak users log in, you may be interested in disabling local authentication altogether. The ohmage preferences table can handle this as well: update preference set p_value= 'false' where p_key = 'local_auth_enabled';. It should be noted that you absolutely make sure a keycloak user has been granted admin privileges before doing this, or no users will be able to perform admin functions in ohmage!