OAuth DSAPI Extension

The OAuth DSAPI Extension allows the Domino server to consume OAuth2 access tokens generated by the domino-iam-service. The OAuth DSAPI extension communicates with the domino-iam-service via OAuth2 Introspection Protocol to determine the user identity and level of authority represented by an access token.

Configuration Overview

The introspection requests from the Domino server are authenticated by domino-iam-service and therefore require credentials authenticating the Domino server. The communication link is secured by Transport Layer Security (TLS) and requires a certificate that is related to the domino-iam-service certificate.

Prerequisites

Configure the credential store on the Domino server using this guide: Configuring the Domino Credential Store.

You will need the hostname of the domino-iam-service or proxy in front of the service.

Configuration Steps - Linux

1. Go to the IAM Management Dashboard, click Manage Applications and create a "Resource Provider". This identifies the Domino Server as a resource provider to the IAM service and provides credentials that allow the Domino server to introspect access tokens. After clicking "Create":

   1. Resource Provider Name: Name of the Domino server acting as the resource provider. This value is for display only.
   2. Resource Provider Description: Descriptive text for the server.
   3. Click Save. You are shown the Resource Provider ID and Resource Provider Secret. (You can come back to these if needed.)

2. Running as root, unzip the oauth-dsapi-<version>.tgz file to the Domino program directory and execute setup.sh.

   sudo sh -c '(cd /opt/ibm/domino/notes/latest/linux/; tar -xvf
   oauth-dsapi-<version>.tgz; sh -x setup_dsapi.sh)'
   

3. Add the credentials to the Domino credential store. See Credential Management.

4. Verify that a certificate or certificate chain is stored on the server. This is required for the Domino server to connect to the domino-iam-service using TLS. This should be a PEM formatted certificate or certificate chain that allows the Domino server to verify the authenticity of the domino-iam-service certificate. While this file can be anywhere on the server file system, the suggested location is the notes data directory or subdirectory.

5. Set the following value in notes.ini:

   OAUTH2_DSAPI_KEYRING=<path to certificate or certificate bundle>
   

6. Open the Domino directory for the server and locate the server document.

7. Select the "Internet Protocols" tab and click "Edit Server".

8. On the http tab, add oauth-dsapi to "DSAPI filter file names"

9. Save the server document.

10. Enable the Calendar and Freebusy rest API's.

1. On the Domino server console type restart task http.

2. You should see:

   HTTP Server: DSAPI OAuth DSAPI Filter version <version> Loaded successfully
   

Configuration Steps - Windows

1. Go to the IAM Management Dashboard, click Manage Applications and create a "Resource Provider". This identifies the Domino Server as a resource provider to the IAM service and provides credentials that allow the Domino server to introspect access tokens. After clicking "Create":

   1. Resource Provider Name: Name of the Domino server acting as the resource provider. This value is for display only.
   2. Resource Provider Description: Descriptive text for the server.
   3. Click Save. You are shown the Resource Provider ID and Resource Provider Secret. (You can come back to these if needed.)

2. Unzip the oauth-dsapi-<version>.zip file to the Domino program directory.

3. Add the credentials to the Domino credential store. See Credential Management.

4. Verify that a certificate or certificate chain is stored on the server. This is required for the Domino server to connect to the domino-iam-service using TLS. This should be a PEM formatted certificate or certificate chain that allows the Domino server to verify the authenticity of the domino-iam-service certificate. While this file can be anywhere on the server file system, the suggested location is the notes data directory or subdirectory.

5. Set the following value in notes.ini:

   OAUTH2_DSAPI_KEYRING=<path to certificate or certificate bundle>
   

6. Open the Domino directory for the server and locate the server document.

7. Select the "Internet Protocols" tab and click "Edit Server".

8. On the http tab, add oauth-dsapi to "DSAPI filter file names"

9. Save the server document.

10. Enable the Calendar and Freebusy rest API's.

1. On the Domino server console type restart task http.

2. You should see:

   HTTP Server: DSAPI OAuth DSAPI Filter version <version> Loaded successfully
   

Credential Management - Linux

Credentials for introspection are stored in the Domino server credential store. The oauthcfg tool provides the ability to add or delete credentials from the credential store. If using a credential store on a Domino cluster, changes only need to be made on one of the cluster members.

1. Adding credentials

   cd /local/notesdata
   /opt/ibm/domino/bin/tools/startup /opt/ibm/domino/notes/latest/linux/oauthcfg create <Resource Provider ID> <Resource Provider Secret> <https://<domino-iam-service host>/token/introspection>
   

2. Removing credentials

   cd /local/notesdata
   /opt/ibm/domino/bin/tools/startup /opt/ibm/domino/notes/latest/linux/oauthcfg delete
   

Credential Management - Windows

Credentials for introspection are stored in the Domino server credential store. The oauthcfg tool provides the ability to add or delete credentials from the credential store. If using a credential store on a Domino cluster, changes only need to be made on one of the cluster members.

1. Adding credentials

   cd <notes.ini-location>
   \<domino-program-directory>\oauthcfg create <Resource Provider ID> <Resource Provider Secret> <https://<domino-iam-service host>/token/introspection>
   

2. Removing credentials

   cd <notes.ini-location>
   \<domino-program-directory>\oauthcfg delete
   

Debug

• DEBUG_OAUTH_DSAPI=1 to enable DSAPI tracing.
• DEBUG_OAUTH2=1 to enable core OAuth tracing.