Single sign-on (SSO)
This section describes the single sign-on integration of Eclipse Kapua.
This project provides a template to bootstrap single sign-on based on Keycloak.
The scripts for this are located in the director
Assuming you have already installed Kapua into OpenShift, it is possible to run the script
will create a new build and deployment configuration in OpenShift. This is based on the official Keycloak Docker
jboss/keycloak, adding a few steps for initial provisioning.
The default setup uses an ephemeral storage. So re-starting the Keycloak pod will delete the configuration unless you re-configure the setup with a persistent volume.
For this configuration to work, you will need some existing SMTP server which is capable of sending e-mails. This is required so that Keycloak can send user verification and password recovery e-mails. If you don't have and local SMTP server it is also possible to use some cloud based service like Mailgun, SendGrid or any other provider.
The deployment is triggered by running the
deploy script with a set of environment variables. Assuming your
bash as shell, this can be done like this:
SMTP_HOST=smtp.server.org SMTP_USER=user SMTP_PASSWORD=secret SMTP_FROMfirstname.lastname@example.org ./deploy
The following environment variables are being used:
- SMTP_HOST (required)
- The host name or IP address of the SMTP server
- SMTP_PORT (optional)
- The port number of the SMTP service
- SMTP_FROM (required)
- The sender e-mail used in the e-mail
- SMTP_USER (required)
- The user name used to authenticate with the SMTP server
- SMTP_PASSWORD (required)
- The password used to authenticate with the SMTP server
- SMTP_ENABLE_SSL (optional)
- If SSL should be used instead of STARTTLS
- KEYCLOAK_ADMIN_PASSWORD (optional)
- The password which will be assigned to the Keycloak admin user. The default is to generate a password.
After the build and deployment configuration was creates the script will also re-configure the Kapua OpenShift project
to use the newly created Keycloak instance. This is done by calling the script
can be called at a later time to re-configure Kapua (e.g. when re-installing Kapua).
Both scripts (
activate) require both Kapua and Keycloak URLs. Keycloak requires the Kapua web console
URL in order to allow request from this source, while Kapua requires the Keycloak URL in order to forward requests to Keyloak.
The URLs are being constructed from OpenShift routes, which are configured for both Kapua and Keycloak. However this requires
that Kapua is set up before Keycloak and that the
activate script can only be called after the
has been successfully run.