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:

  1. Local usernames and passwords
  2. Identity federation to LDAP / AD
  3. Identity brokering to a SAML provider for SSO



Accessing the Keycloak UI

You can access the Keycloak UI on any Domino instance at

https://<domino-domain>/auth/

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 keycloak-http.

Run 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 DominoRealm selected in the upper left.

_images/keycloak-realm.png



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.

Configuration

In this mode the key settings are on the Login tab of the DominoRealm settings page.

_images/keycloak-local-login-config.png

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.

User management

You can add, edit, and deactivate local users from the Users menu. Click View all users to load user data.

_images/keycloak-manage-users.png



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.

Configuring mappers

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:

  • username
  • firstName
  • lastName
  • email

For more details, read the official Keycloak documentation on LDAP mappers.




SSO configuration

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:

  1. Copy the Redirect URI from the Add identity provider page, and use it to configure a SAML client in your SSO service.
  2. Export client configuration metadata as an XML file from your SSO service.
  3. At the bottom of the Add identity provider page, click Select file and upload the client configuration metadata.
  4. Click Save, then navigate to the Domino UI to attempt a login.

For complete details on available options, read the official Keycloak documentation on Identity brokering and SAML settings.

Configuring mappers

To correctly create Domino users from SAML identities, you must configure assertions and mappers for the following attributes:

  • firstName
  • lastName
  • email

For cases when the username that comes through the assertion is in the form of email (e.g. user@domain.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.

See: https://www.keycloak.org/docs/5.0/server_admin/#_timeouts