Domino AppDev Pack

1.0.17

OAuth DSAPI Extension

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

NOTE: As of version 1.0.2 of the Domino AppDev Pack, the OAuth DSAPI extension is an optional component. If your IAM service instance will never be used to introspect an access token for a Domino HTTP request, there is no need to configure the OAuth DSAPI extension.

Configuration Overview

The introspection requests from the Domino server are authenticated by the 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 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 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. Add the credentials to the Domino credential store.

    Note: Before Domino 11, the bin directory was in /opt/ibm/domino/

     cd /local/notesdata
 /opt/hcl/domino/bin/tools/startup /opt/hcl/domino/notes/latest/linux/oauthcfg create <name> <resource provider ID> <resource provider secret> <https://<domino-iam-service host>/token/introspection>

See Introspection Credentials for more details on managing introspection credentials.

  1. Verify that a certificate or certificate chain is stored on the server. This is required for the Domino server to connect to the 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 IAM service certificate. While this file can be anywhere on the server file system, the suggested location is the notes data directory or subdirectory.

  2. Set the following value in notes.ini:

    OAUTH2_DSAPI_KEYRING=<path to certificate or certificate bundle>

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

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

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

  6. Save the server document.

  7. Enable the Calendar and Freebusy rest APIs.

  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. Add the credentials to the Domino credential store.

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

See Introspection Credentials for more details on managing introspection credentials.

  1. Verify that a certificate or certificate chain is stored on the server. This is required for the Domino server to connect to the 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 IAM service certificate. While this file can be anywhere on the server file system, the suggested location is the notes data directory or subdirectory.

  2. Set the following value in notes.ini:

    OAUTH2_DSAPI_KEYRING=<path to certificate or certificate bundle>

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

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

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

  6. Save the server document.

  7. Enable the Calendar and Freebusy rest APIs.

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

  2. You should see:

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

Debug

  • DEBUG_OAUTH_DSAPI=1 to enable DSAPI tracing.
← Domino Resource Provider OverviewOAuth2 Support for Domino Web Applications →