Domino AppDev Pack

1.0.0

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 will be authenticated by domino-iam-service and will therefore require credentials authenticating the Domino server. The communication link is secured by Transport Layer Security (TLS) and will require a certificate that is 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

  1. Go to the IAM Management Dashboard, click Manage Applications and create a "Registered Application". This will be the credentials the Domino uses to connect to the domino-iam-service.
    1. Application Type: Server Side Application
    2. Application Name: <Value that indicates this is for Domino introspection>
    3. Application Homepage: <Not used, enter something like https://test>. This will be removed in a future release.
    4. Authorization callback URL: <Not used, enter https://test/cb>. This will be removed in a future release.
    5. Application description:
    6. Click Save and you will be presented with Application ID and Application 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)'
  1. Add the credentials to the Domino credential store. See Credential Management
  2. A certificate or certificate chain is needed by 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.
  3. Set the following value in notes.ini: OAUTH2_DSAPI_KEYRING=<path to certificate or certificate bundle>
  4. Open the Domino Name and address book associated with the server and locate the server document.
  5. Select the "Internet Protocols" tab and click "Edit Server".
  6. On the http tab, add oauth-dsapi to "DSAPI filter file names"
  7. Save the server document.
  8. Enable the Calendar and Freebusy rest API's.
1. On the Domino server console type restart task http 1. You should see "HTTP Server: `DSAPI OAuth DSAPI Filter version Loaded successfully`

Credential Management

Credentials for introspection are stored in the Domino server credential store. The oauthcred 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
    1. cd /local/notesdata
    2. run /opt/ibm/domino/bin/tools/startup /opt/ibm/domino/notes/latest/linux/oauthcfg create <ApplicationID> <Application Secret> <https://<domino-iam-service host>/token/introspection>
  1. Removing credentials
    1. cd /local/notesdata
    2. run /opt/ibm/domino/bin/tools/startup /opt/ibm/domino/notes/latest/linux/oauthcfg delete

Debug

  • DEBUG_OAUTH_DSAPI=1 to enable DSAPI tracing.
  • DEBUG_OAUTH2=1 to enable core OAuth tracing.
← IAM ConfigurationIAM Management →