| Table of Contents |
|---|
This page contains information, code snippets and other information regarding using Keycloak with mod_auth_openidc.
Running on Azure
The code for the HEE customisations is here;
...
https://dev-api.transformcloud.net/auth/
...
Running locally
Keycloak is available from keycloak.org. It is an application embedded in a JBoss WildFly JEE container. The easiest way to get it working is to use an existing docker container. This container is set up to use with a MySQL datastore. To run Keycloak with a dockerized version of MySQL, try this:
$ docker run --name mysql -e MYSQL_DATABASE=keycloak -e MYSQL_USER=keycloak -e MYSQL_PASSWORD=keycloak -e MYSQL_ROOT_PASSWORD=password -d mysql$
Checkout dockerthe run TIS-itDEVOPS --link mysql:mysql -e MYSQL_DATABASE=keycloak -e MYSQL_USER=keycloak -e MYSQL_PASSWORD=keycloak -e KEYCLOAK_USER=admin -e KEYCLOAK_PASSWORD=admin -p 8080:8080 -p 9990:9990 jboss/keycloak-mysql
A docker-compose.yml file for the latter command is:
keycloak: image: jboss/keycloak-mysql environment: MYSQL_DATABASE: keycloak MYSQL_USER: keycloak MYSQL_PASSWORD: keycloak KEYCLOAK_USER: admin KEYCLOAK_PASSWORD: admin ports: - "8087:8080" - "9990:9990" external_links:- mysql:mysqlrepository and run the docker-compose file for the stack https://github.com/Health-Education-England/TIS-DEVOPS/blob/master/docker/stacks/keycloak/docker-compose.yml
Keycloak will create and populate the required database tables on initial startup. The admin console should then be available via http://localhost:8087 and the Admin Console link using the KEYCLOAK_* credentials from the above command (admin/admin in this example).
Tasks
Adding a realm
...
Initially, Keycloak has only one admin realm, which should be used for admin purposes only so we must add a non-admin realm. From the admin console, below the Keycloak logo on the left, click on "Master" with the down arrow symbol and select the "Add realm" button. Let's call the new realm heeadmin and save it.
Adding a client
...
Once the new realm has been added, we need to add a client. This client is the account that will be used by Apache to call into Keycloak to validate the authorisation code that Keycloak passes via the browser for logged in users.
...
On the credentials tab (second tab at the top of the page), make a note of the client secret: it's a UUID that will be needed when setting up Apache.
Adding users and groups
...
Click on the group menu item on the left-hand menu and then at the top right click "New" to add new groups.
...
In order to use the admin REST API an admin token is required. This can be obtained as follows:
| Code Block |
|---|
$ TOKEN=$(curl -s 'http://localhost:8087/auth/realms/master/protocol/openid-connect/token' -d "client_id=admin-cli&username=admin&password=admin&grant_type=password" | jq -r .access_token) |
(jq is a JSON parser that can extract values from JSON. The -r parameter means "raw output" and removes the quotes from the returned value.)
Create a realm
A realm can be created from a JSON template and added using the following:
| Code Block |
|---|
curl -i 'http://localhost:8087/auth/admin/realms' \ -H "Authorization: bearer $TOKEN" \ -H "Content-Type: application/json" |
...
\ -d '{"realm":"lin", "enabled":true}' |
This will return the URL of the new realm as an HTTP Location header.
Create a group
| Code Block |
|---|
curl -i 'http://localhost:8087/auth/admin/realms/lin/groups' \ -H "Authorization: bearer $TOKEN" \ -H "Content-Type: application/json" |
...
\ -d '{"name":"admins"}' |
Create a client
| Code Block |
|---|
curl -i 'http://localhost:8087/auth/admin/realms/lin/clients' \ -H "Authorization: bearer $TOKEN" \ -H "Content-Type: application/json" |
...
\ -d '{"clientId":"revalidation","redirectUris":["https://dev-api.transformcloud.net/revalidation/"], "secret":"longpassword"}' |
This will return the URL of the new client as an HTTP Location header.
Create a user
...
| Code Block |
|---|
curl -i 'http://localhost:8087/auth/admin/realms/lin/users' \ -H "Authorization: bearer $TOKEN" \ -H "Content-Type: application/json" |
...
\ -d '{"username":"jamesH","enabled":true,"email":" |
...
jamesH@example.com","attributes":{"gmc_id":["1125"],"NTN":["245/FGS/819"]}}' |
...
Adding
...
user
...
Use these calls:
...
to group
| Code Block |
|---|
curl -i 'http://localhost:8087/auth/admin/realms/ |
...
lin/users/{id}/groups/{groupId}' |
...
\ -H "Authorization: bearer $TOKEN" \ -X PUT |
Remove user from group
| Code Block |
|---|
curl -i 'http://localhost:8087/auth/admin/realms/ |
...
lin/users/{id}/groups/{groupId}' |
...
\
-H "Authorization: bearer $TOKEN" \
-X DELETE |