About the document "Configure Domino REST API to use Domino 14.5 as OIDC provider"

HCL Domino Domino Forum
1

Domino/Notes Version: 1.4.5
Add-on Product (if appropriate, e.g. Verse / Traveler / Nomad / Domino REST API): REST API 1.1.6
Its Version:
Operating System:linux
Client (Notes, Nomad Web, Nomad Mobile, Android/iOS, browser version):

Problem/Query:Hi everybody,

I sure misunderstand something.
In the document Configure Domino REST API to use Domino 14.5 as OIDC provider ( Configure Domino REST API to use Domino 14.5 as OIDC provider - HCL Domino REST API Documentation ) there are three points I’m missing.

In the Registered OAuth Client section there is a hint:
"For Redirect URI(s), you can set them to your actual login flow destination. "

I don’t undertand what does it mean.

at the end:

“After completing the configuration, you can obtain a token from the Domino OIDC provider”

How? Is possible to build a postman configuration sample to do that? is there a conventional path to do that?

In the Trusted OIDC Provider settings client-id and secret must match those in OAuth Client i guess.
In that section is missing the connection with ID Vault [Field Bearer token (JWT) approved OIDC provider configurations: in ID Vault configuration] that is described here “ HCL Software 404 Page . Is it not needed?

thanks

tommaso

2

Hi @tommaso,

Good day!

Regarding the three concerns you’ve mentioned, below is a brief information for your review.

1.) Redirect URI(s) in Registered OAuth Client
The Redirect URI is the callback URL where Domino sends the user after successful login along with the authorization code.

In practice, this means:

If you are building a custom app (UI, SPA, portal) that will consume the token, use your app’s callback endpoint — e.g., https://yourapp.company.com/auth/callback

If you are only testing or using Domino REST API directly and not feeding the token into another app, you can use a simple path in the Domino server that handles the login flow (e.g., the /auth/protocol/oidc endpoint itself).

Note: The Redirect URI must match one of the URIs you list here when registering the OAuth client, otherwise the provider (Domino) will reject the authorization response.

2.) Obtaining a Token from Domino OIDC Provider
You can obtain a token using the standard Authorization Code flow with PKCE.
Postman setup:

Grant Type: Authorization Code (With PKCE)
Callback URL: https://oauth.pstmn.io/v1/callback
Auth URL: https:///auth/protocol/oidc/auth
Token URL: https:///auth/protocol/oidc/token
Client ID/Secret: from your Domino OAuth Client
Scope: openid profile email (add keep-api for REST API access)

Click Get New Access Token in Postman, log in via the browser, and Postman will capture the token.

I found this documentation about Authenticate with OAuth 2.0 authentication in Postman.

3.) Trusted OIDC Provider and ID Vault Connection

The Client ID and Secret in the Trusted OIDC Provider must match your OAuth Client.

ID Vault configuration is optional:

  • Not required for general REST API access (Views, Documents, etc.)

  • Required if the REST API needs to sign/encrypt emails or for Nomad/Verse Federated Login

To connect ID Vault:

  • Add a virtual hostname (e.g., bearer.vault.yourserver.com) in the IdP Catalog

  • Use the same hostname in the ID Vault field: “Bearer token (JWT) approved OIDC provider configurations”

In the event that you are (still) having an issue or need clarifications on configuring this, you can create a case to HCL Domino Support Portal for a deep dive investigation.

Hope the above information helps. Thank you.

3

Hi @epagtabunan,

thanks a lot for your explanation, it helps.
I still have some doubts:

  1. Redirect URI(s) in Registered OAuth Client

You wrote: “Note: The Redirect URI must match one of the URIs you list here when registering the OAuth client”

What is the first “Redirect URI” you are talking about? Is it the Callback URL I use in the postman test?

  1. Obtaining a Token from Domino OIDC Provider (i.e. Postman test)

You wrote: “Auth URL: https:///auth/protocol/oidc/auth”

Are you assuming that I am using postman on the same computer where the OIDC Domino server is installed? It is not my case.

I used:
https://oidc.mydomain.it/auth/protocol/oidc/auth and it worked
(oidc.mydomain.it is the host mapped in the internet sites as OIDC provider)

same for Access Token URL.

As a second thing i noticed that in this example I have to share the clientID and the Secret with the mobile app the end user will use to connect to the Domino server. Is it right?

In the presentation here Webinar - HCL Domino - Domino as an OIDC Provider - Customer Support (AttachedPDF page 11) seems that the Secret could be shared between the Domino-app and Domino-OIDC only, without leaving the Domino server.

  1. Application Management

We didn’t mention the Application Management in the REST Admin UI, where there are an applicationID, an applicationSecret and some Callback URLs as well. Do some of what we mentioned have something to do with this?

thanks again a lot

tommaso

4

The Application Management section in the DRAPI AdminUI is for configuration of DRAPI’s own IdP capabilities (Since R12). I is of no use when you use any other IdP like AD, Okta, Keycloak or Domino’s 14.5 IdP configuration.

Btw. it also features the field for Callback URLs. They are native to OICD.

In OICD what is the purpose and use of the CallbackURL?

OIDC = OpenID Connect (a protocol for user login/authentication)

What is it?

The CallbackURL (also called “Redirect URI”) is a URL in your application where the authentication server sends the user back after they log in.

How it works:

  1. User clicks “Login” in your app

  2. Your app redirects them to the login provider (like Google, Microsoft)

  3. User enters credentials there

  4. Login provider redirects user back to your CallbackURL

  5. The URL includes an authorization code

  6. Your app exchanges this code for user tokens

Example:

CallbackURL: https://yourapp.com/auth/callback

After login, user returns to:

https://yourapp.com/auth/callback?code=ABC123&state=xyz

Key points:

  • Must be registered with the authentication provider beforehand

  • Must match exactly - including http/https, port, path

  • Security measure - prevents attackers from stealing login codes

  • Can have multiple callbacks (for dev, staging, production environments)

Common mistake:

Using http://localhost:3000/callback in development but forgetting to register https://yourapp.com/callback for production.