thirdroom-keycloak-theme Keycloak theme project

Keycloak is a popular open-source identity provider: https://www.keycloak.org/

This is the Keycloak repository containing the thirdroom theme and extensions created with Blueshoe's keycloak-theme-template cookiecutter template (find it here).

Getting started

Please consult the official Keycloak documentation for creating a theme here.
Important: for a version older than latest you can find the associated documentation in the archive: https://www.keycloak.org/documentation-archive.html

Development

Environment

Bring up the development environment with docker-compose up. It starts a PostgreSQL database and a Keycloak instance.

Keycloak will now be available on http://localhost:8080. You can log into the Administration Console using admin as both user and password.

The theme from thirdroom/ will be mounted into the running Keycloak instance. Caching is already deactivated.

Theme and Realm

Keycloak provides the concept of realms. From their docs:

A realm manages a set of users, credentials, roles, and groups. A user belongs to and logs into a realm. Realms are isolated from one another and can only manage and authenticate the users that they control.

Themes are also configurable for each realm. Please find more information here. During development, the default "master" realm might be enough to work with.

More on the theme configuration here

Set up the realm

1. Login in at http://localhost:8080/auth/admin/

The default admin credentials are admin as both user and password.

2. Go to the Master realm theme settings http://localhost:8080/auth/admin/master/console/#/realms/master/theme-settings

Select for the Login Theme from the dropdown ("Select one...") thirdroom. Do the same for other theme aspects if your template provides customizations.

Don't forget to hit the Save button.

Coding

The templates are written in the Apache FreeMarker templating language. You can create drop-in replacements for the files from the original theme, for example thirdroom/login.ftl to insert theme-specific markup. If your template does not render because of templating errors (or other errors) you will get a status 500 page (you can customize this as well). Please refer to the logs with docker-compose logs keycloak to see what is causing the error.

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.

Changes to the CSS, Images, or the template files are immediately reflected. Just enter the view and find the results. The official creating-a-theme documentation will get you started.

Frontend frameworks and pre-processing

CSS pre-processors or any other heavy frontend framework (like Vue.js or React) can be integrated, too. Just please make sure that everything required (like weback build output) or minified CSS is written to thirdroom/ according to the specification.

Testing Keycloak e-mails

The local Keycloak server includes MailDev, a mock SMTP server that you can use to receive and view Keycloak e-mails. It is available on http://localhost:8081.

To set up the local Keycloak server to send e-mails to MailDev:

1. Log in to the local Keycloak server.

2. Go to the Email tab in Realm Settings

3. Enter the following details:

   • Host: maildev

   • From: keycloak@keycloak

4. Click on Save

5. Click on Admin in the top-right-hand corner of the page, and click on Manage Account

6. Add an e-mail address to the admin account.

   It doesn’t matter what e-mail address you add, as all e-mails will be caught by MailDev. But you do need to add one, otherwise Keycloak will not send e-mails for this account.

The local Keycloak server should now be set up to send e-mails to MailDev. To check that it’s working:

1. Click on the Back to Security Admin Console link
2. Click on the Login tab in Realm Settings
3. Enable Forgot password, and click on Save
4. Sign out.
5. On the Keycloak log in screen, click on the Forgot your password? link
6. Enter your username (admin) in the text field, and submit the form.
7. Visit MailDev. You should see a reset password e-mail from Keycloak.