OAuth2 Support for Domino Web Applications

OAuth2 Support for Domino Web Applications allows administrators to configure token-based access to Domino-hosted ReST API's. A general familiarity with OAuth2 is recommended before attempting to set up applications to use this feature.

Overview

Version 1.0.8 of the AppDev Pack provides the ability to access any Domino-hosted ReST API using Oauth2 Access Tokens without requiring changes to the underlying application code. By providing the URI associated with an application and some basic access rules, applications can participate in OAuth2 flows that streamline system integration.

Prerequisites

1. The IAM service setup steps are required. The Oauth DSAPI Extension section of the IAM service setup steps are required.
2. Enable IAM service access to adpconfig.nsf
   1. Open adpconfig.nsf with the Notes client.
   2. From the File->Application menu, select Access Control.
   3. Click 'Add' and add the functional ID created in this step.
   4. Select User type as Unspecified and Access as Reader.
   5. Uncheck "Write public documents" and "Replicate or copy documents".
   6. The following image shows the required changes:.
   7. Click OK to save the ACL change.
   8. When these changes are successful, the message [13:52:19][info][adpConfig][master]: ADPConfig polling enabled at interval 5 minutes is logged to the IAM service log (iam-<date>.log)

Resource Configurations

A resource configuration is defined in adpconfig.nsf and associates an application with a set of rules governing the HTTP methods permitted on that application. Each rule consists of a mapping from one or more HTTP methods to an OAuth scope. In order for an HTTP method to be permitted on a resource, the OAuth access token passed with a request must contain the scope defined in the resource definition. The OAuth scope can be any text string that conforms to the OAuth Access Token Scope specification. Descriptive text accompanies each rule that explains to the resource owner the implications of granting access to the resource. Resource configurations appear as Resource Providers in the IAM service administration application.

Enabling an Application to Use OAuth2 Access Tokens

The high-level steps for this task are as follows:

1. Create a resource configuration that describes your application.
2. Create a corresponding introspection credential using parameters from the auto-generated resource provider definition in the IAM service.
3. Modify your resource configuration as needed to adjust access based on Oauth2 scopes.

Creating Resource Configurations

1. Using the Notes client or Domino Administrator, open adpconfig.nsf and select OAuth2 in the navigator pane.
2. Click the "Add Resource Configuration" button.
3. Enter the name of the server hosting the application. Multiple server names can be specified here to allow multiple servers to share the same resource configuration.
4. Enter a description of the application.
5. Enter the path used to access the application.
6. If your application needs to support database path prefixes, check the "Global" checkbox. If in doubt, leave it un-checked as it can be changed at any time. See Global Applications below for more explanation.
7. Define one or more scopes
   1. Click Add Scope...
   2. Provide a succinct, descriptive scope name, i.e. api.myapp.read and click OK.
   3. Decide which HTTP methods should be allowed when the api.myapp.read scope is presented by an access token.
   4. Enter a label that briefly describes the scope.
   5. Enter a description that explains what granting access to the scope does.

The form should appear as follows: Click Save and Exit to finish creating the resource definition.

Guidelines for Resource Configurations

1. Scopes must be unique with respect to all resource configurations.
2. When creating scopes, select a name that reflects an association with the API the scope is used with. For example, if defining a scope to be used with the GET method on /api/sample, a good scope name is api.sample.read or api.sample.get. This prevents confusion and potentially unexpected access if scopes are used, removed, and then re-added.
3. Paths are matched with the assumption that / characters serve as delimiters. The implications of this are that a resource definition with a path value of /api/test matches /api/test, /api/test/sample and /api/test/sample/more but does not match /api/test1.
4. Paths can not be defined that are related to existing paths except as siblings. For example, if /api/sample is defined, then a new resource definition with the path /api/sample/test cannot be created. Likewise, if a resource definition with /api/sample/test exists, a new resource definition with the path /api/sample cannot be created. However, two resource definitions with paths /api/sample/test and /api/sample/test2 can be created.

OAuth-DSAPI Filter Auto-Update

Changes to the resource definitions in adpconfig.nsf will be detected and processed by the oauth-dsapi filter every minute. If there is some reason an immediate change is necessary, the http server should be restarted using restart task http on the Domino server console.

Auto-Generated IAM Service Resource Providers

A resource definition created in adpconfig.nsf will cause a resource provider to be generated by the IAM service. This resource provider is read-only in the IAM service and can only be modified or deleted by changing the associated resource description in adpconfig.nsf. Using the sample resource configuration created above, one can view the generated resource provider in the "Resource Providers" list as shown here: Clicking the Show action reveals the resource provider details:

Domino Resource Provider name

This value uniquely identifies the resource provider and is derived from the Path item on the adpconfig.nsf resource configuration document.

Domino Resource Provider description

This value is the derived from Description item on the adpconfig.nsf resource configuration document.

Domino Resource Provider id

This value is generated by the IAM service and will be used to create introspection credentials in the credential store.

Domino Resource Provider secret

This value is generated by the IAM service and will be used to create introspection credentials in the credential store.

Scopes List

The list of scope names, descriptions and their programmatic values are shown at the bottom of the form. These values are referenced from the adpconfig.nsf resource configuration document. Note that the Scope value is prefixed with adpconfig.. OAuth2 client should use the fully-qualified scope name that includes the adpconfig. prefix when requesting scopes from the IAM Service.

Introspection Credentials

OAuth2 Introspection Credentials are required for each auto-generated resource provider in order to allow the oauth-dsapi filter to decode the access token associated with the corresponding application. The values needed to create the introspection credentials are found on the IAM Service Resource Provider form. The Domino Resource Provider Name, Domino Resource Provider Id, and Domino Resource Provider secret should be used as the name, resource provider ID and resource provider secret values passed to the oauthcfg create command. For example, given the resource provider sample above, the command to create the corresponding introspection credentials on the Domino Server hosting the credential store are:

Windows

cd <notes.ini-location>
\<domino-program-directory>\oauthcfg create /api/sample GNFbDZD7gnvDi-YPWqEND unjqNfG8knym8Sdr93tkSWkJsikv4uwSqmJlo9qzJz6QXLOlxvu95W10KVEPhNpNzXq2oHlybEp4d2pN8oes9g <https://<domino-iam-service host>/token/introspection>

Linux

cd /local/notesdata
/opt/hcl/domino/bin/tools/startup /opt/hcl/domino/notes/latest/linux/oauthcfg create /api/sample GNFbDZD7gnvDi-YPWqEND unjqNfG8knym8Sdr93tkSWkJsikv4uwSqmJlo9qzJz6QXLOlxvu95W10KVEPhNpNzXq2oHlybEp4d2pN8oes9g <https://<domino-iam-service host>/token/introspection>

Global Applications

Domino applications can exist either inside or outside of a Notes database. For example it is possible to define an HTTP servlet inside of a database and then access that servlet using the path /mydatabase.nsf/xsp/myservlet. For applications defined inside of a Domino database, do not check the "Global" checkbox but specify the complete path including the database name /mydatabase.nsf/xsp/myservlet. For applications defined outside of a database, for example a DAS extension, it is possible to provide a database context to the application by prefixing the application path with a database path. Given a DAS extension service with the path /api/sample, the path /mydatabase.nsf/api/sample on a request would set the current database to mydatabase.nsf while the path /another.nsf/api/sample would set the current database to another.nsf. For these types of applications, check the Global checkbox to allow matching against any database. The .nsf extension is the only supported database name extension used to identify database path prefixes.

Using Scopes in Applications

Very Important - The scopes defined in adpconfig.nsf must be referred to with an adpconfig. prefix when used in an OAuth2 client application. Using the sample from above, an application that requires a token with the scope api.sample.read needs to request the scope as adpconfig.api.sample.read.

Modifying Resource Definitions

Resource definitions can be modified after they are created. Modifications are made using the OAuth2 Configuration form and view provided in adpconfig.nsf. Modifications are detected by the IAM service whenever Resource Provider or Application definitions are accessed. The IAM service also polls adpconfig.nsf every five minutes for changes so that resource provider configuration remains consistent without requiring an explicit user action in the IAM service administration application. Note that if you change the path of a resource definition, you must delete and re-add a corresponding set of introspection credentials using the oauthcfg tool as described here.

Removing OAuth2 Access Token Support for a Domino Application

The high level steps are

1. Remove the application's resource definition from adpconfig.nsf.
2. Remove the application's introspection credentials from the the credential store.

Removing Resource Definitions

1. Using the Notes client or Domino Administrator, open adpconfig.nsf and select OAuth2 in the navigator pane.
2. Delete the resource definition from the OAuth2 view.

Removing Introspection Credentials

Use the oauthcfg tool to delete the credentials that match the name of the deleted application. See OAuth2 Introspection Credentials for details on performing that operation.

Additional Configuration

Additional configuration is available in the <IAMService root>/config/local.properties file of the IAM service. The value commonConfig.ADP_CONFIG_POLL_MINUTES can be used to control the frequency at which the IAM service checks for changes in adpconfig.nsf. The default value is 5 minutes. Setting commonConfig.ADP_CONFIG_POLL_MINUTES to 0 disables the IAM Service from accessing adpconfig.nsf.

Troubleshooting

There are two components involved with the OAuth-related functionality, the IAM Service and the oauth-dsapi filter hosted by the Domino HTTP server. When troubleshooting, it is useful to enable verbose logging on both of these components.

• Instructions for enabling verbose logging on the IAM service can be found here.

• Instructions for enabling verbose logging on the oauth-dsapi filter can be found here

Common issues you may encounter

Incorrect Access Control on adpconfig.nsf

The IAM Server may log the message [error][adpConfig][master]: IAM Server does not have access to adpconfig.nsf. Polling disabled. This indicates that the steps indicated in the prerequisites section have not been performed or have not been performed correctly.

Missing Introspection Credentials for an Application

Every application needs an entry in the credential store with a name that matches the application path. If credentials are missing for an application, HTTP requests to that application receive a 500 return code from the Domino HTTP server. Logging on the Domino server console will indicate an error following the message Retrieving credentials:

[4D74:000E-3E58] 03/16/2021 11:33:53.73 AM IAMClient::introspectAccessToken with credentials> Retrieving credentials named /api/dastest
[4D74:000E-3E58] 03/16/2021 11:33:53.73 AM oauth-dsapi::OAuth2Authenticate> Default exception decoding access token for URI
[4D74:000E-3E58] 03/16/2021 11:33:53.73 AM oauth-dsapi::SendErrorResponse> response code 500

Refer to the Introspection Credentials section for details on resolving this issue.