Skip to content

Configure an identity provider

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 setting in the notes.ini by editing, or creating if missing, the entry KeepManagementURL (case sensitive). Having configured a 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 won't 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.

In its default configuration, Domino REST API uses Domino as its identity provider (IdP). This allows you to start evaluating and testing out of the box. To enable this, you need to have an HTTP password configured in Domino and good enough for internal use.

However, for an actual deployment, you might want to configure your own IdP and authentication flow. The only IdP requirements are use of a supported algorithm for signing and a token with the expected format.

About this task

The provided information guides you of configuring your own IdP and authentication flow for use in an actual deployment.

Identity providers

Domino REST API supports identity providers that can produce JWT access tokens. Some examples are:

Tip

Check out the Keycloak example configuration.

Example For Encode JWT

You can use the official JWT site to decode and inspect the encoded token.

JWT Encode & Decode

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJUaGUgRGVtbyBXaXp6YXJkIiwic3ViIjoiQ049RG9jdG9yIE5vdGVzL0
89UHJvamVjdEtlZXAiLCJzY29wZXMiOiJNQUlMICREQVRBIiwiaWF0IjoxNjE4NTA2MzM5LCJleHAiOjE2MTg1MDk5MzksI
mF1ZCI6IkRvbWlubyJ9.HJC2MTu8OPT8KnsZnLWqIIc3CoPaEmzQwnygEaRjapk

When decoded, this translates to:

HEADER: ALGORITHM & TOKEN TYPE

{
  "typ": "JWT",
  "alg": "HS256"
}

PAYLOAD: DATA

{
  "iss": "The Demo Wizzard",
  "sub": "CN=Doctor Notes/O=ProjectKeep",
  "scope": "MAIL $DATA",
  "iat": 1618506339,
  "exp": 1618509939,
  "aud": "Domino"
}

wherein:

  • iss stands for Issuer and refers to the name of the IdP providing the claim.
  • sub stands for Subject and refers to the full qualified X500 expanded Notes name, which starts with CN=.

  • scope refers to the databases and services that the user accesses. For more information, see Scopes.

  • iat stands for Issued at and refers to the epoch time of creation.

  • exp stands for Expiry and refers to the epoch time of expiration. It must fit into maxJwtDuration number of minutes.
  • aud stands for Audience and MUST have a value of Domino (case-sensitive).

VERIFY SIGNATURE

HMACSHA256(
  base64UrlEncode(header) + "." +
  base64UrlEncode(payload),

your-256-bit-secret

) secret base64 encoded

Add your own IdP

To add an IdP:

  1. Create a JSON file in the keepconfig.d directory.
  2. Allow access to the public key from your IdP.

The JSON file looks like this:

{
  "disableJwtExpiryCheck": false,
  "jwt": {
    "oicd": {
      "active": true,
      "algorithm": "RS256",
      "keyFile": "10-jwt.pubkey"
    }
  }
}

wherein:

  • disableJwtExpiryCheck: By setting the value to true, the enforcement of JWT expiration can be disabled. DO NOT do this on a production system (default is false).
  • jwt: Entry is related to JWT authorization.
  • oicd: The name you give your IdP. It could be Rumpelstielzchen but needs to be unique on your server.
  • active: True/false.
  • algorithm: Currently supported: RS256.
  • keyFile: Path to public key file (PEM format), either relative to keepconfig.dor an absolute path.

Domino REST API supports more than one IdP, distinguished by the name oicd in the example. Access checking takes longer the more identity providers you configure since Domino REST API checks every provider's key until it finds a match.

Obtaining the public key directly from the IdP

TO ease configuration and simplify key rollover, the public key for JWT verification can be directly obtained from the key server. You are responsible to only use trusted connections.

{
  "disableJwtExpiryCheck": false,
  "jwt": {
    "somother": {
      "active": true,
      "providerUrl": "https://someidp.your.domain"
    }
  }

The Domino REST API will extend this URL to https://someidp.your.domain/.well-known/openid-configuration and check for a JSON return containing the jwks_uri key. When your IdP doesn't use the .well-known approach (e.g. Keycloak), you need to directly point to they key URL.

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]