Domino AppDev Pack

1.0.8

Configure the Domino web server as a resource provider

This section describes how to configure the Domino web engine so that it can accept and process an OAUTH2 Bearer Token. When the Domino web server receives a request which includes a OAUTH2 Bearer Token makes an introspection call to the IAM service to verify the access token and to obtain the user information associated with it.

Verify the connection to the IAM introspection endpoint

The Domino web server, using the oauth2 DSAPI filter, makes the introspection call to the IAM service over HTTPS. Use the following from the Domino server to verify that the Domino server can connect to the IAM service endpoint and to inspect the certificates for the connection

C:\temp>echo "badreq" | openssl  s_client -connect auth.jumbocloudservices.com:7443 --quiet --CAfile c:\letsencrypt-certs\rootchain.crt
depth=2 O = Digital Signature Trust Co., CN = DST Root CA X3
verify return:1
depth=1 C = US, O = Let's Encrypt, CN = Let's Encrypt Authority X3
verify return:1
depth=0 CN = auth.jumbocloudservices.com
verify return:1
HTTP/1.1 400 Bad Request
Connection: close

read:errno=0

The Bad Request text in the output is expected. You can ignore it.

HTTP/1.1 400 Bad Request
Connection: close

The command above reports the certificates used by the IAM service that it connects to. Verify that your output does not have the self signed certificate in certificate chain error. This error indicates that the certificates in the --CAfile parameter are not enough to trust the connection to the IAM service.

Configure the resource provider

Use the IAM Admin (e.g. https://auth.jumbocloudservices.com:8443) to create the resource provider for the Domino web server. In this step you provide:

  1. The Domino Resource Provider name, which is a unique name in IAM Admin.
  2. The Domino Resource Provider description, which is a free-form description field.

The IAM Admin generates the following data:

  1. Domino Resource Provider id
  2. Domino Resource Provider secret

The id and secret are the introspection credentials.

setup-guide-aau-rp

Configure the introspection credentials

This step adds the introspection configuration into the credential store. The introspection configuration includes:

  1. The configuration name. This name must be default for the Domino web server.
  2. The introspection credentials as generated above.
  3. The introspection URI. This is the URL to IAM service endpoint as verified above.

Use the oauthcfg tool to manage the introspection configuration for the Domino server. Run the tool from the command line, not the Domino server console. This is some basic help from the tool:

C:\>oauthcfg
Usage: oauthcfg [--version] 

Supported commands:
   create      
   delete   Delete introspection configuration
   list  List introspection configurations matching name. Blank name lists all.

Use the following command to create a new introspection configuration entry with the name default.

C:\>oauthcfg create default 2a80f2be-11b5-4346-974d-3909f8567341 pFN5k/jvpQVvuKZqHrPnCYtu188yShpqOQukBLEUmGMDDeFF5JPvewoU4TOeySHO https://auth.jumbocloudservices.com:7443/token/introspection
Credentials created successfully

Use the list option to view the list of introspection configurations:

C:\>oauthcfg list
name:default      id:2a80f2be-11b5-4346-974d-3909f8567341 URI:https://auth.jumbocloudservices.com:7443/token/introspection
name:proton-addin id:34378bf4-777c-4a7b-9eaa-9e8b630b38c9 URI:https://auth.jumbocloudservices.com:7443/token/introspection

Configure the Domino web server

Configure the Domino web server with the oauth-dsapi plugin and enable the Domino Access Services feature.

Load the oauth-dsapi filter

A DSAPI filter is an optional shared library that ships with the Domino AppDev Pack. The Domino web server loads DSAPI filters as configured in the Domino server document.

Using the HCL Domino Administrator client, open the Domino Server document and:

  1. Click on the Internet Protocols tab.
  2. Click on the Edit Server button.
  3. Click on the HTTP tab.
  4. Edit the DSAPI filter file names field, add oauth-dsapi.
  5. Click on the Save & Close button.

setup-guide-aau-dsapi

Enable Calendar services

Note: On this Domino server Internet Sites are not enabled. If you have Internet Sites enabled, then Domino Access Services must be enabled in the Internet Site document.

Using the HCL Domino Administrator client, open the Domino server document and:

  1. Click on the Internet Protocols tab.
  2. Click on the Edit Server button.
  3. Click on the Domino Web Engine tab
  4. Edit the Enabled services field, add Calendar and optionally add Data.
  5. Click on the Save & Close button.

setup-guide-webconfig1

setup-guide-webconfig2

Configure the trust store for DSAPI filter introspection calls

The DSAPI filter makes introspection calls over HTTPS and therefore we must provide the root certificate(s) that ensures the validity of the IAM server. The IAM server uses a Let's Encrypt certificate which provides its root certificates here.

Use the following command to copy the rootchain.crt file into the Domino data directory:

C:\>copy c:\letsencrypt-certs\rootchain.crt "c:\Program Files\HCL\Domino\Data\rootchain.crt"

Use the following Domino server console to configure the notes.ini variable for the oauth-dsapi filter to identify the trust store for the introspection calls.

> set config OAUTH2_DSAPI_KEYRING=rootchain.crt

Restart the Domino web server

Use the restart task http Domino server console command to restart the web server. Note that the OAuth DSAPI filter generates a message to identify that was loaded.

> restart task http
[0DE4:0002-16C0] 12/12/2019 12:55:16 PM  XSP Command Manager terminated
[0DE4:0002-16C0] 12/12/2019 12:55:17 PM  HTTP Server: Shutdown
[0A10:0002-1778] 12/12/2019 12:55:18 PM  HTTP Server: Using Web Configuration View
[0A10:0002-1778] 12/12/2019 12:55:20 PM  JVM: Java Virtual Machine initialized.
[0A10:0002-1778] 12/12/2019 12:55:20 PM  HTTP Server: Java Virtual Machine loaded
[0A10:0002-1778] 12/12/2019 12:55:20 PM  HTTP Server: DSAPI OAuth DSAPI Filter version 0.5.0   Loaded successfully
[0A10:0002-1778] 12/12/2019 12:55:20.28 PM CSRF Init: iNotes_WA_Security_ReturnUrlCheck> c_CSRFReturnUrlCheck: 1
[0A10:0002-1778] 12/12/2019 12:55:30 PM  XSP Command Manager initialized
[0A10:0002-1778] 12/12/2019 12:55:31 PM  HTTP Server: Started
← Configure Proton as a resource providerConfiguration test overview →