Skip to content

Configure Keycloak

Caution

The Domino server task communicates with the REST API through the KeepManagementURL. It has a default value of http://localhost:8889. You can overwrite this ssetting in the notes.ini by editing (or creating if missing) the entry KeepManagementURL (case sensitive). Having configured an TLS certificate you need to make sure the entry starts with https:// and uses the host name your TLS certificate has been issued for. localhost, 127.0.0.1 or ::1 will not work. Configuring TLS doesn't change the port, so when you host, your TLS certificate is issued for, is domino.demo.com and your old entry was missing or is the default of http://localhost:8880, then your new value needs to be: https://domino.demo.com:8889 For more information, see Domino REST API task and ports.

Keycloak is an Open Source Identity and Access Management sponsored by RedHat.

Keycloak can be used to produce JWT Access Token for Domino REST API. Keycloak has many features like in its default configuration, Use Federation, Identity Brokering or Social Login. Those are topics not covered here, you want to consult a Keycloak Tutorial or the Keycloak documentation to learn more. This page focuses on the settings required for Domino REST API.

About this task

This section describes key concepts and provides the steps required to configure Keycloak successfully for Domino REST API (it can be used for classic Domino SAML as well).

Keycloak concepts

Listing only relevant concepts:

Keycloak concepts

  • Realm: The starting point for Keycloak identity management, contains all other elements.
  • Client: Each accessing application, client app, Single Page App or server app will have a client entry. The client entry contains application Id and, if required, the application secret.
  • Client Scopes: Attributes and properties available and/or assigned to client entries.
  • Mapper: Configuration entry to determine what information is available in a client scope.

Not listed: Users

We will create a realm, an user, two clients (one for a SPA, one for a server based app), a client scope for shared settings and a few mappers.

Procedure

Login to Keycloak. Click on the down angle next to the Master, add a new realm. In our example Trantor.

Keycloak Realm

Fill in the minimum information.

Keycloak Realm

Now create a user. In a production environment you probably would connect to an existing LDAP or Active Directory server. Check the documentation for details about that.

Keycloak User

To make it compatible with Domino and Domino REST API, we need the X500 style distinguished name of the user. This name can be in either "LDAP" format (comma-delimited) or "Domino" format (slash-delimited). We maintain that as the attribute dominoDN. In your environment it might have a different name, which you later need to use in the mapper.

Keycloak User

Next step is to create a client scope named keep-common which will contain the settings that are common to all clients (a.k.a apps) accessing Domino REST API.

Keycloak Client scope

Next step is to add two mappers for aud and for the distinguished name. Here, the name is mapped to the standard claim sub, but it can be mapped to a different name if desired.

Keycloak Mapper Audience Keycloak Mapper Subject

Next create a client. The example below is for an application server that can present a client id and a client secret. An example for a SPA (that can't keep a secret) follows further down.

Keycloak Client 1/3 Keycloak Client 2/3 Keycloak Client 3/3

Next step is to assign the client the common client scopes keep-common and offline_access (this one for the refresh token). Remove the Assigned Optional Client Scopes first, so they become available in Available Client Scopes.

Keycloak Client 3/3

Application specific scopes

The configuration so far will identify a user presenting the access token to Domino REST API, but not yet provide any access. We need to specify what scopes this application will be allowed to access. We can use any of the global scopes MAIL, $DATA or $DECRYPT or, preferably, a lowercase database alias. Multiple scopes are separated using a space.

Note

It's best practice to give an external application as little as possible access so it can function. So think twice before allowing any of the uppercase general scopes.

The Mapper for the client is individual per application (client):

Keycloak Application scope

Finally we can verify that an access token has all the required attributes:

Keycloak Application scope

SPA applications

An SPA (Single Page App) or a mobile client can't keep a client secret. For those, the use of Proof Key for Code Exchange (PKCE) (defined in RFC 7636) is recommended (read this intro for details). The only difference in Keycloak is to specify the client Access Type as public.

Keycloak Application scope

Important

It's SECURITY, so learn about Keycloak!

Configure the Domino REST API

You can find the full explanation here. For the short version:

  • Create a JSON file in keepconfig.d to contain the Keycloak related information
  • Restart the REST API
{
  "jwt": {
    "Trantor": {
      "providerUrl": "https://trantor.keycloak.yours/auth/realms/Trantor"
    }
  }
}

where:

key explanation
jwt Indicates that the config belongs to JWT
Trantor The sample Keycloak realm name. It must be unique in the jwt key. Replace it with your choosen realm
providerUrl Points to Keycloak's endpoint with the public key. Note that the last segment is the realm name. The string is case sensitive

Note

Keycloak's providerUrl is different from the general IdP practise to use /.well-known/openid-configuration, mainly since Keycloak can handle multiple realms, the well-known approach can't handle. Hence you need ro use /auth/realms/[RealmName]