Keycloak authentication service¶
Domino uses Keycloak, an enterprise-grade open source authentication service to manage users and logins. Keycloak runs in a pod in the Domino Platform. There are three modes you can use for identity management in Domino:
- Local usernames and passwords
- Identity federation to LDAP / AD
- Identity brokering to a SAML provider for SSO
Accessing the Keycloak UI¶
You can access the Keycloak UI on any Domino instance at
Note that the trailing
/ in the URL is required.
To log in as the default
keycloak administrator user, you will need kubectl access to the cluster to retrieve
the password from a Kubernetes secret called
kubectl -n <domino-platform-namespace> get secret keycloak-http -o yaml to fetch the contents of the secret. The
output should look like the following:
apiVersion: v1 data: password: <encrypted-password> kind: Secret metadata: creationTimestamp: 2019-09-09T21:23:15Z labels: app.kubernetes.io/instance: keycloak app.kubernetes.io/managed-by: Tiller app.kubernetes.io/name: keycloak helm.sh/chart: keycloak-4.14.1-0.10.2 name: keycloak-http namespace: domino resourceVersion: "6746" selfLink: /api/v1/namespaces/domino/secrets/keycloak-http uid: 09009f96-d348-11e9-9ea1-0aa417381fd6 type: Opaque
Decrypt the password by running
echo '<encrypted-password' | base64 --decode. With this password you will be
able to log in to the Keycloak UI as the
keycloak administrator user in the master realm. Read the official Keycloak
documentation on the master realm to learn more.
Keycloak will be configured automatically by Domino with a realm named
DominoRealm that will be used for Domino
authentication. When reviewing or changing setting for Domino authentication, ensure that you have
selected in the upper left.
Local username and password configuration¶
The simplest option for authentication to Domino is to use local usernames and passwords. In this case all user information is stored by Keycloak in the Postgres database, and there is no federation or brokering to other identity providers.
In this mode the key settings are on the Login tab of the
DominoRealm settings page.
The one setting on this tab that is not supported is Email as username as that would automatically use email as
username and Domino currently does not support that as a valid username. Note also that if you want yo use the
Verify Email option, an SMTP connection must be configured in the Email tab.
You can add, edit, and deactivate local users from the Users menu. Click View all users to load user data.
LDAP / AD federation¶
Keycloak provides the ability to connect to an LDAP / AD identity provider and cache user information.
Adding a provider¶
This can be configured in the User Federation menu. Select
ldap from the Add provider… dropdown menu.
For details on all available options, read the official Keycloak documentation on User storage federation.
In addition to configuring the LDAP connection you may also need to review the LDAP mappers associated with the LDAP connection you have configured. Some mappers will be configured by based on the LDAP vendor that was chosen, but you may need to modify these based on the specific configuration of your provider. You will need to make sure that there are mappers for the following attributes:
For more details, read the official Keycloak documentation on LDAP mappers.
Keycloak also provides the ability to broker user identities with an external SAML v2.0 provider for a Single Sign-On experience.
Setting up SSO¶
This can be configured in the Identity Providers menu. Select SAML v2.0 from the Add provider… dropdown menu. The procedure for setting up this integration is as follows:
- Copy the Redirect URI from the Add identity provider page, and use it to configure a SAML client in your SSO service.
- Export client configuration metadata as an XML file from your SSO service.
- At the bottom of the Add identity provider page, click Select file and upload the client configuration metadata.
- Click Save, then navigate to the Domino UI to attempt a login.
To correctly create Domino users from SAML identities, you must configure assertions and mappers for the following attributes:
For cases when the username that comes through the assertion is in the form of email (e.g. email@example.com), the Domino Keycloak image has a special mapper called Email Prefix as Username Importer that will automatically use the prefix as the username since a fully qualified email is not a proper Domino username.
For more information, read the official Keycloak documentation on mappers.
Testing and troubleshooting¶
If you encounter errors from the Keycloak service while attempting an SSO login, you can view the Keycloak request logs
via kubectl by running
kubectl -n <domino-platform-namespace> logs keycloak-0.
Session and token timeouts¶
By default, sessions are limited to 60 days but can be configured differently as needed.