Keycloak set up

Keycloak is a user authentication service that runs in a pod on your Domino cluster.

Discover how to set up Keycloak, manage user groups, and configure local usernames and passwords.

Enable user registration via the Keycloak console so users can sign up to join your new Domino installation.

Keycloak offers various authentication methods:

Access Keycloak

To access your Keycloak instance, visit https://<your-domino-domain>/auth/.

You must sign in to the Keycloak admin console at least once to initialize the authentication service.

Retrieve the admin password

Before your first sign-in, you must retrieve the admin password.

If you haven’t already, install kubectl and sign in to Kubernetes.

Retrieve the administrator password from the keycloak-http Kubernetes secret:

kubectl -n <domino-platform-namespace> get secret keycloak-http -o yaml

The following is a sample response:

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 from the response:

echo '<encrypted-password>' | base64 --decode

Use this password to sign in to https://<your-domino-domain>/auth/ with the username keycloak.

Domino automatically configures Keycloak with a realm named DominoRealm, to create and manage new users. When you review or change settings for Domino authentication, ensure that you have DominoRealm selected. Keycloak realm configuration

Enable or disable user registration

You can enable or disable Domino user registration from the Keycloak admin console. Make sure to enable user registration, so users can join your fresh Domino install.

In the Keycloak sidebar menu, click Realm Settings.
Click the Login tab, and toggle User registration to On or Off.

Local username and password configuration

The simplest option for authentication to Domino is to use local usernames and passwords. When you choose local authentication, Keycloak stores all user data in Postgres.

Set login and email configurations in Keycloak for easy authentication to Domino.

Login configuration

When using local usernames and passwords, you find important login settings in the Login tab of the DominoRealm settings page.

Keycloak login

Note	Email as username is not supported. If you want to use the `Verify Email` option, an SMTP connection must be configured in the Email tab.

Email configuration

You can configure Keycloak to be able to send emails, such as for password resets. In the DominoRealm, navigate to Realm Settings > Email. The form contains fields that map to values provided by an SMTP email service provider or SMTP server.

User management

Your first sign-in as administrator automatically configures Keycloak with realms. A realm is the Keycloak equivalent of a tenant. It’s used to manage groups of users. The default Keycloak admin account is in the Master realm. Master realm accounts can view, create, or update accounts in other realms. Domino also automatically configures a realm called DominoRealm. DominoRealm accounts are non-admins and have ordinary user privileges.

In the Keycloak sidebar, from the menu, click DominoRealm.

Keycloak realm admin

Set permissions to activate or deactivate users

To activate or deactivate users from an admin account, you must assign the admin account the manage-users role. If the admin account doesn’t have that role, it’ll receive a 403 error if you sign in to it and try to update a user’s status.

From the Keycloak sidebar, go to Manage > Users.
Select the admin account you want to assign the manage-users role to.

Click the Role Mappings tab.
For Client Roles, in Available Roles, click manage-users.
If you’re already signed in to Domino, sign out and then sign in again.

To activate or deactivate user accounts, see Manage users.