Configure Domino Rest API IdP

About this task

Domino REST API implements an OAuth2 provider. The following is a guide for setting up and configuring Domino REST API's OAuth2 provider.

Before you begin

The oauth.nsf database exists in your Domino data directory. The Domino IdP uses the oauth.nsf to store content and refresh information.

Note

• If you are using Domino+Domino REST API docker image, the oauth.nsf should already be in the image but may not be fully configured.
• If for some reason you need to create the oauth.nsf, see Set up oauth.nsf, and save it in your Domino data directory.

Client Ids

When configuring an external identity provider using OpenID Connect (OIDC) or OIDC-idpcat with HCL Domino and the Domino REST API, you must specify a client ID. The default recommendation is to use Domino as the client ID for the Domino REST API server. However, your identity provider administrator might require a different value depending on your organization’s configuration.

Separate client IDs (application registrations) are required to support the Admin UI and Office Forms Based Authentication (OFBA). To support these features, configure at least the following clients in your identity provider:

• A client used by the Domino REST API server. You can name the client Domino or any descriptive name. The client secret might be managed through idpcat.nsf.
• A client used by the Domino REST API Admin UI. You can name the client keepadminui or any descriptive name. Configure this client if you want administrators to authenticate through the external identity provider.
• A client used for OFBA round-trip editing of Office documents. You can name the client keepofba or any descriptive name.

You should also create separate clients for each custom application that connects to the Domino REST API.

Procedure

1. Configure Domino REST API to access the oauth.nsf.

   1. Create an oauth.json file using a text editor.

   2. Copy the following JSON object to the JSON file.

      {
      "oauth": {
         "active": true,
         "database": "oauth.nsf",
         "url": "https://sample.keep.io:8880",
         "authCodeExpiresIn": 120,
         "accessTokenExpiresIn": 3600,
         "refreshTokenExpiresIn": 525600
         }
      }
      

      For more information, see the following table:

      Property	Description
      active	Required It has a boolean value indicating if the provided token is now active. If the token is issued by this authorization server, it isn't revoked by the user, and it's not yet expired, the value should be true.
      database	The nsf file where the authorization details are stored.
      url	Server URL
      authCodeExpiresIn	The code expiration time in seconds.
      accessTokenExpiresIn	The access token expiration time in seconds.
      refreshTokenExpiresIn	The refresh token expiration time in seconds.

   3. Change the value of the url parameter to match your Domino REST API host.

      The indicated url value in the JSON object above is just an example value.

   4. (Optional) Adjust the expiration time values as needed.

   5. Save the JSON file in the keepconfig.d directory located in your Domino data directory.

      You need to create the keepconfig.d directory if not yet existing.

   6. Restart Domino REST API.

2. Add the OAuthAdmin role for the ACL entry.

   Be sure to thoroughly examine the ACL.

   • By default, the configured access level is Author with the capability to create information but unable to remove it.
   • All servers involved must have at least an Editor access level and the OAuthAdmin role assigned. If you DON'T have this role, you'll only see your documents or records.

   • Administrators requiring troubleshooting capabilities should have Editor access level and the OAuthAdmin role assigned.

   • Enforce a consistent ACL.

   • Ensure the database is copied to all servers involved.