Keycloak for Micado

[mthsbk]

@gioppoluca following issue describes what we discussed/learned about Keycloak in Antwerp:

Keycloak general concepts

• Realms (= tenant)
• Client (= app)
• Groups (= team)
• Users (= subject)

How to manage Keycloak

• Keycloak features an Admin API: https://www.keycloak.org/docs-api/14.0/rest-api/index.html
  • ideal to automate provisioning and updating of local Micados
• Keycloak can federate to other identity provider (like another keycloak, or LDAP, AD, Google, ...)
  • this would be a nice option to have for Antwerp.

How to implement Keycloak for Micado

• There should be one Keycloak realm in keycloak per Micado installation.
• Each application (PA, Migrant, NGO, Countly, Weblate, ...) will be a client in Keycloak
• Each Micado user type (Admin, NGO user, Migrant user) will be represented by a group in Keycloak (admins, ngo users, migrants, ...). The groups are defined on the realm.
• Each group in keycloak will have multiple roles, which are connected to the client application. These roles define what a user (in that group) can do on the given client application.
• Each user will be put in the correct group accordingly to his function. And will thus have all the roles from the group.

[gioppoluca]

can a user belong to more than 1 group within the same app?

[mthsbk]

Yes, a user can be in multiple groups.

[mthsbk]

Keycloak theming

Adding themes to Keycloak

Custom themes reside in the keycloak/themes directory (/opt/jboss/keycloak/themes in our Docker image).

So we need to create a /opt/jboss/keycloak/themes/micado directory there and link a local directory as a volume to that folder.

That way each local administration can use their own theme files in the local directory, that will be picked up by Keycloak.

Developing a theme

The best way to create a custom theme is to extend an existing one. That way you only have to override the resources you want to adapt.

You can either extend the base or keycloak theme, with the latter being more complex and having images.

⚠️ If you decide to override HTML templates bear in mind that you may need to update your custom template when upgrading to a new release.

Details about how to implement the actual themes can be found in the official documentation: https://www.keycloak.org/docs/latest/server_development/#creating-a-theme

Selecting themes in Keycloak admin

1. Log into the Admin Console.
2. Select your realm from the drop-down box in the top left corner.
3. Click Realm Settings from the menu.
4. Click the Themes tab.
5. Select the newly added theme