Set up an external IdP for the Office Round Trip Experience

About this task

This task explains how to configure an external identity provider (IdP) for login to the Office Round Trip Experience.

Cliend Ids

When configuring an external identity provider using OpenID Connect (OIDC) or OIDC-idpcat with HCL Domino and the Domino REST API, you must specify a client ID. The default recommendation is to use Domino as the client ID for the Domino REST API server. However, your identity provider administrator might require a different value depending on your organization’s configuration.

A separate client ID is required to support Office Forms Based Authentication. To do this, you need to configure a separate client in your external IdP. You may specify the value of the client ID, or it might depend on your organization’s IdP configuration.

Before you begin

If you plan to use Microsoft Entra ID as the external identity provider (IdP), ensure you have registered an application in the Azure portal for use by the Domino REST API server. For instructions, see Configure Microsoft Entra ID as IdP.

Set up an external IdP

Configure an external IdP of your choice. For more information, see configuring external IdP.

Important

When configuring your external IdP, make sure to set {{ origin }}/api/webdav-v1/login/callback as one of your redirect URIs.

Setup Microsoft Entra ID as external IdP for Office Forms Based Authentication

Note

When configuring Microsoft Entra ID as your external identity provider (IdP), you must specify a client ID. This value must match the application (client) ID of the client application you configure in Microsoft Entra ID.

The client ID described here applies only to the Office Forms Based Authentication. A separate client ID (application registration) is required to support the Domino REST API server. For more information, see Configure Microsoft Entra ID as IdP.

Register an application.

Go to the Azure portal and sign in.

Tip

Make sure you’re in the correct directory. Select your profile icon in the upper-right corner of the Azure portal, then select Switch directory. Use an account in the same directory where you plan to register the application.
In Microsoft Entra ID, select App registrations, then select New registration.

On the App registrations page, enter the application registration details described in the following table.

Form input name	Description
Name	Enter a descriptive name for the application.
Supported account types	Choose who can sign in.
Redirect URI	Specify where authentication responses should be sent. Select Single-page application (SPA) as the platform and use `{{ origin }}/api/webdav-v1/login/callback` as the Redirect URI. where: `{{ origin }}` is a template placeholder for the base URL where the Domino REST API server is hosted.

Azure app registration

Click Register.

After the registration, you will see the Overview page. Take note of the value of the Application (client) ID.

Add client credentials.
1. Under Manage, select Certificates & secrets → Client secrets → New client secret.
2. Add a description for your client secret, and select an expiration for the secret or specify a custom lifetime.
3. Click Add.
4. Record the client secret Value. This secret value is never displayed again after you leave the page.
Add the Application ID URI.
1. Under Manage, select Expose an API.
2. At the top of the page, select Add next to Application ID URI.
  
  This defaults to api://<application-client-id>. Take note of this value as it is needed in the configuration in the Domino REST API.
3. Click Save.
Configure API permissions.
1. Under Manage, select API permissions. The API permissions page opens with the User.Read permission already configured.
2. Click Add a permission. The Request API permissions pane opens.
3. Select the APIs my organization uses tab, and then select the application you configured for use by the Domino REST API server from the list. See the Before you begin section for details.
  
  In the example image, it shows the selection of the DRAPI-API application, which is the application used by the Domino REST API server as stated in the Before you begin section.
4. Under Select permissions, select the required scopes and click Add permissions.
  
  After adding permissions, you should see the selected permissions under Configured permissions on the API permissions page.
5. Click Grant admin consent for {your tenant} to grant admin consent to the permissions configured for the application.
6. In the Grant admin consent confirmation dialog, click Yes. After granting consent, the permissions that required admin consent are shown as having consent granted.
Assign an owner.
1. Under Manage, select Owners, and then select Add owners. The Owners pane opens.
2. Search for and select the user account that you want to be an owner of the application.
3. Click Select to add the user account that you chose as an owner of the application.
Check authentication.
1. Under Manage, select Authentication.
2. On the Redirect URI configuration tab, make sure that the selected and entered values are correct.
3. On the Supported accounts tab, make sure the correct supported account type is selected.
4. On the Settings tab, make sure Access token is selected.
5. Click Save if you made any changes.
Adjust app manifest.
1. Under Manage, select Manifest. A web-based manifest editor opens, allowing you to edit the manifest.
2. Change the value of accessTokenAcceptedVersion from null to 2.
  
  Before changingAfter changing
3. Click Save.
Check application endpoints.
1. Under Manage, select Overview.
2. Select Endpoints in the top menu to open the Endpoints page, which shows the authentication endpoints for the application. Take note of the following endpoints:
  - OpenID Connect metadata document
  - OAuth 2.0 authorization endpoint (v2)
  - OAuth 2.0 token endpoint (v2)

Set up OFBA configuration in Domino REST API

To use the configured external IdP for Office Round Trip Experience login, you need to include the ofba property in the configuration file of external IdP saved in keepconfig.d. For more information about the ofba property, see JWT parameters.

Set up OFBA configuration to use Microsoft Entra ID as external IdP

Open the JSON file you used in configuring Domino REST API to use Microsoft Entra ID as an external IdP that is saved in the [notesdata]/keepconfig.d directory.

Add the following JSON object to the Microsoft Entra ID configuration in the JSON file.

    "ofba": {
        "active": true,
        "client_id": "[value of Application (client) ID]",
        "application_id_uri": "[value of the Application ID URI]"
  }

where:

The client_id parameter should have the value of the Application (client) ID of the registered application in Azure portal.
The application_id_uri parameter should have the value of the Application ID URI of the registered application in Azure portal. It should end with /.

Check the Overview page of the application in the Azure portal. Refer to the following example image:

Azure app registration

After adding the JSON object, the configuration should be similar to the following:

{
      "jwt": {
            "AzureIdP": {
                  "active": true,
                  "providerUrl": "[value of the OpenID Connect metadata document endpoint of the app used by the Domino REST API server]",
                  "aud": "[value of the Application (client) ID of the app used by the Domino REST API server]",
                  "iss": "[issuer value]",
                  "algorithm": "RS256",
                  "adminui": {
                        "active": true,
                        "client_id": "[value of Application (client) ID]",
                        "application_id_uri": "[value of the Application ID URI]"
                  }
            }
      }
}

For more information on the definitions and values of the providerUrl, aud, and iss keys, see Configuration in Domino REST API for details of the Microsoft Entra ID configuration.

Save the changes and restart Domino REST API.

Additional information

OFBA log in

Once configured, the login UI for OFBA should look like the following example image. In the example image, Keycloak is used as the external IdP.

OFBA external IdP login UI

Clicking Sign in with {external_idp_name} commences the authorization code flow.

Example OFBA configuration to use Keycloak as external IdP

The following is an example configuration for Keycloak IdP:

{
  "jwt": {
    "KeycloakIdP": {
      "active": true,
      "providerUrl": "https://{keycloak_host}/realms/{realm_name}",
      "ofba": {
        "active": true,
        "client_id": "{client_id}"
      }
    }
  }
}