Copyright (c) 2019 California Community Colleges Technology Center
Licensed under the MIT license.
A copy of this license may be found at https://opensource.org/licenses/mit-license.php
Keycloak
An extension of the jboss/keycloak official image (i.e., a Dockerfile FROM).
This image provides a script based configuration for CCTC.
Configuration
The default docker-compose.yml
contains all the configuration settings needed to start and run keycloak locally with a temporary database. This configuration has two keycloak instances and runs them in a cluster.
Build a Keycloak docker image
From the root dir run
docker build . -t keycloak-ha-postgres-unicast_keycloak
Running Keycloak
Docker Compose
Simply run with:
docker-compose up --build
As noted above, the default configuration starts 2 keycloak instances in a cluster. If you want to run only one instance, you can use docker-compose up keycloak
.
Browse to http://localhost:8083 to connect to the first instance (log in : keycloak/keycloak).
Browse to http://localhost:8084 and check that changes in first instance are visible from the second one and vice versa (note: due to browser session sharing, one of the browsers should be in incognito / private mode)
Realm Configuration
On Keycloak's startup, Keycloak's DB will be updated with the realm configuration defined in init.sh.
NOTE: The existing ccctc
realm is the recommended one for all new CCCTC applications / microservices.
HA support and realm cache
Testing has shown in HA, when one node generates a new client secret, only that new secret will work to retrieve a token. However, in Keycloak's UI, you may access a node that's cached the "old" secret and will display the incorrect value.
Therefore, follow these instructions to clear the cache of what you're viewing to ensure you have the latest and greatest.
Adding a New Realm using Keycloak's UI
- You can create/define a realm in keycloak's UI, then export the realm configuration into this git repo.
- Import your exported realm file with the script init.sh
- Use keycloak cli API to define the rest of the realm not supported with the import command
- It's recommended you add postman test for your realm in postman-api-tests
The problem with this approach and using the UI is the exported realm configuration doesn't include the passwords. So you have to manually set the users and PWs in scripts anyway. Additionally, adding users, mapping users to roles, adding service accounts and mapping roles to service accounts are also not supported with this method and have to be done using scripts.
Configuring a realm using scripts
Loading / configuring realm is driven from the init.sh script.
The easiest thing to do is use the test
or ccctc
realm as a template. These are the most recent realms and have various examples of setting thigns up.
Adding Themes
To add a theme create a new folder in the existing theme folder. Follow the folder structure found at https://www.keycloak.org/docs/3.2/server_development/topics/themes.html to override each Keycloak theme. The name of the folder will appear in the admin console under realms on the theme tab after Keycloak is restarted or the domain.xml file is configured for development. The domain.xml settings are also documented in the previous link. Once the domain.xml is configured you can copy changes to the theme and reload the page to see the results without having to restart Keycloak. I recommend using an incgonito window to avoid having to clear the browser cache.