Set up Keycloak

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:

• Federated authentication through an LDAP Active Directory Provider
• Brokered authentication through single sign-on (SSO)

​

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 administrator password

Before your first sign-in, you must retrieve the administrator password. If you haven’t already, install kubectl and sign in to Kubernetes.

1. 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
   
2. Decrypt the password from the response:
   echo '<encrypted-password>' | base64 --decode
   
3. 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.

​

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.

1. In the Keycloak sidebar menu, click Realm Settings.
2. 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.

​

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.

​

Next steps

• Federated authentication through an LDAP Active Directory Provider
• Brokered authentication through single sign-on (SSO)
• Limit concurrent user sessions