Configure Domino Rest API IdP

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.

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.

Prerequisite

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.

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 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 is 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.

      Note

      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.

      Note

      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.