OL Keycloak Developer Resources - mitodl/ol-keycloak-customization GitHub Wiki

This page is intended to provide instructions, descriptions, and resources for OL Keycloak developers.

Development Setup

This section provides instructions to setup Keycloak locally and apply the MIT OL customizations from this repository.

Keycloak OOTB setup

Before you start Be sure to have JDK 11 installed: https://openjdk.java.net/

Instructions

  1. Visit https://www.keycloak.org/downloads and download the "Server" specified with "Distribution powered by Quarkus"
  2. Unzip the downloaded folder from step 1
  3. In a terminal, navigate to the folder produced from step 2
  4. Run bin/kc.sh start-dev --features=preview --spi-theme-static-max-age=-1 --spi-theme-cache-themes=false --spi-theme-cache-templates=false
  5. Pretty quickly you should see Running the server in development mode. DO NOT use this configuration in production. and the output from step 4 should stop. You can now visit http://localhost:8080/ and setup an administrator username and password.
  6. In order to stop Keycloak, you can press control and c on the keyboard.

MIT OL Keycloak custom themes

To apply MIT OL Keycloak custom themes from this repository to your local Keycloak instance, follow the instructions below:

  1. Download or clone this repository
  2. Copy the /themes/odltheme folder from this repository and paste it into the /themes/ folder inside the Keycloak server folder
  3. Stop and start Keycloak
  4. You should now be able to use the odltheme for certain types by visiting https://{KEYCLOAK_BASE_URL}/admin/{REALM_NAME}/console , clicking "Realm settings" from the left menu bar, clicking the "Themes" tab and selecting the drop-down next to the different types shown.

Notes: A theme's type refers to a single or collection of pages associated with a section of the application. For instance, the theme type login can contain customizations that apply to the login page where an existing user would enter their username and password, but the login type can also contain customizations that apply to the registration page where the user would enter their account details (first name, last name) when creating their account.

MIT OL Keycloak local development configuration import

Before starting Ensure that you have the odltheme with types login, account, and email within the Keycloak themes folder.

The instructions below explain how to load a Keycloak configuration file which will pre-configure the following in Keycloak:

  • Use OL custom themes for Login, Account, Email
  • Define custom user attributes and validations required for mitxonline
  • Login screen user registration and forgot password configuration
  • Realm HTML display name and Display name configuration
  • Preconfigured mitxonline client for use when running mitxonline locally.
  1. Use a new instance of Keycloak
  2. Create the following folder structure in the root of the Keycloak folder: data/import/
  3. Download this realm export and place it in the import folder from step 1
  4. Start Keycloak with the following command: bin/kc.sh start-dev --features=preview --spi-theme-static-max-age=-1 --spi-theme-cache-themes=false --spi-theme-cache-templates=false --import-realm
  5. Go to http://localhost:8080/ and create a new admin user and password
  6. View the imported realm at http://localhost:8080/admin/master/console/#/local-development
  7. Import the user attribute configuration by going to http://localhost:8080/admin/master/console/#/local-development/realm-settings/user-profile, clicking the "JSON editor" and pasting in the content from here
  8. Go to any client in Keycloak that you wish to use and regenerate the client secret. Replace the client secret within the associated client application's .env on your computer

Connecting local client with local Keycloak (mitxonline)

The instructions in this section will walk you through configuring your local mitxonline instance to work your local instance of Keycloak.

  1. It is assumed that you already have mitxonline up and running locally
  2. Checkout the following branch https://github.com/mitodl/mitxonline/tree/collins-oidc-test-demo
  3. Add the following to your .env file in mitxonline
SOCIAL_AUTH_ODL_OIDC_OIDC_ENDPOINT =http://host.docker.internal:8080/realms/local-development/
ODL_OIDC_ENDPOINT=http://host.docker.internal:8080/realms/local-development/
SOCIAL_AUTH_ODL_OIDC_OIDC_KEY=mitxonline-client-id
SOCIAL_AUTH_ODL_OIDC_OIDC_SECRET={CLIENT SECRET FROM KEYCLOAK}
USERINFO_URL=http://host.docker.internal:8080/realms/local-development/protocol/openid-connect/userinfo
ACCESS_TOKEN_URL=http://host.docker.internal:8080/realms/local-development/protocol/openid-connect/token
AUTHORIZATION_URL=http://host.docker.internal:8080/realms/local-development/protocol/openid-connect/auth
  1. Retrieve the client secret from Keycloak by visiting http://localhost:8080/admin/master/console/#/local-development/clients/
  2. Assuming you imported the configuration from the "MIT OL Keycloak local development configuration import" section above, click on the mitxonline-client-id client
  3. Click the "Credentials" tab
  4. Copy the "Client secret" value and replace {CLIENT SECRET FROM KEYCLOAK} in your mitxonline .env with that value
  5. Go back to Keycloak and click the "Keys" tab within the client configuration
  6. Turn on "Use JWKS URL" and complete the form which pops up.
  7. You should now be able to start mitoxnline locally, click the "Sign In" link in the top right corner of the mitxonline homepage and be redirected to Keycloak. At the login page of Keycloak you will need to click "Create Account" and complete the registration form. When you complete the form, you should be redirected back to mitxonline where your account will be created and you will be logged in.
  8. To give your user Django Admin permissions, go back to the Keycloak Administrative console and add your user to the odl-client-django-admin group. Close the mitxonline browser (to end the session) and log back into mitxonline. You will now have Django Admin access.

Connecting local client with hosted Keycloak

You can use the instructions in this section to connect your local mitxonline instance with the hosted instance of keycloak at https://keycloak-ci.odl.mit.edu/.

  1. Add the below information to your .env in mitxonline
SOCIAL_AUTH_OIDC_OIDC_ENDPOINT=https://keycloak-ci.odl.mit.edu/realms/local
OIDC_ENDPOINT=https://keycloak-ci.odl.mit.edu/realms/local
SOCIAL_AUTH_OIDC_KEY=mitxonline-client-id
SOCIAL_AUTH_OIDC_SECRET={CLIENT_SECRET_FROM_KEYCLOAK}
USERINFO_URL=https://keycloak-ci.odl.mit.edu/realms/local/protocol/openid-connect/userinfo
ACCESS_TOKEN_URL=https://keycloak-ci.odl.mit.edu/realms/local/protocol/openid-connect/token
AUTHORIZATION_URL=https://keycloak-ci.odl.mit.edu/realms/local/protocol/openid-connect/auth
  1. Get the value for CLIENT_SECRET_FROM_KEYCLOAK from another team member or find the client in the Keycloak Administrative Console
  2. Checkout the following branch https://github.com/mitodl/mitxonline/tree/collins-oidc-test-demo
  3. Start mitxonline and create a new account when logging in

Keycloak development guidance

By following the below guidance, developer can ensure a high level of integrity and conformance across our configurations and customizations.

  • The Account Management API should be used when reading user data or making any user updates from client applications on the behalf of the user; for instance, updating a user attribute in Keycloak from a client application. The reason for this is to allow reading and updates for information that is related to that user only, and to restrict a user from being able to update or read other user's information.
  • New objects should prepend "ol" where possible in order for other developers to sort and clearly identify all customizations. This should apply to: scopes, user attributes, roles, etc.
  • Do not make changes to the master realm.
  • Achieving custom functionality through customizations should be done in the least intrusive way, such that, Keycloak acknowledges the customization entry point as a conforming and public interface. For most of our work, I imagine we should consider the following customization interfaces in order of least to most complex: theme customization, extend public SPI, extend private SPI, custom SPI.

Keycloak developer resources and materials

UK Gov Keycloak theme: https://github.com/UKHomeOffice/keycloak-theme-govuk

  • This is a helpful resource to see how to perform different theme customizations.

Keycloak Account Management OpenAPI: https://gist.github.com/xgp/2d77cbebc6164160faae6aa77d127a57

  • This is a helpful resource to import into Postman and refer to as you integrate calls from your client applications. The Account Management API is not well documented within the official Keycloak documentation - don't confuse it with the Admin API. The Account Management API should be used when reading user data or making any user updates from client applications on the behalf of the user; for instance, updating a user attribute in Keycloak from a client application. The reason for this is to allow reading and updates for information that is related to that user only, and to restrict a user from being able to update or read other user's information.

Recommended IDE

  • I found it was easiest to view the Keycloak source while using https://www.jetbrains.com/idea/. When customizing and extending Keycloak, it is helpful to have a copy of the Keycloak source code open in IntelliJ IDEA in order to create new theme templates or extend interfaces.