Product: HCL Domino REST API (DRAPI)
Component: Built-in OAuth/OIDC Identity Provider and Admin UI
Operating System: Windows Server 2025
DRAPI Version: 1.1.8
Domino version: 14.5.1 FP1
Request Type: Feature Enhancement (Bug Report - if url paramether is optional?)
1. Summary
I would like to request an enhancement to the built-in OAuth/OIDC provider in HCL Domino REST API to support multiple hostnames for the same DRAPI server, ideally through automatic URL detection when the oauth.url configuration parameter is omitted.
During testing, I discovered that omitting oauth.url appears to be accepted by DRAPI and the server correctly detects the hostname used to access the Admin UI. Unfortunately, the Admin UI then constructs an invalid OIDC discovery URL containing -build in-, making authentication impossible.
Additionally, the OIDC discovery endpoint returns endpoint URLs containing http://localhost:8880 instead of adapting them to the hostname and protocol used by the client.
I believe these issues should be addressed together.
2. Environment and Use Case
I have a single Domino REST API installation running on Windows Server 2025.
The same DRAPI server is accessible through two different addresses:
URL 1 – HTTPS through a reverse proxy / access manager:
URL 2 – Direct access to the DRAPI server:
These are two access paths to the same DRAPI installation, not two separate DRAPI servers.
Both access methods work correctly when configured individually.
3. Current Behavior with a Configured oauth.url
My oauth.json contains:
{
"oauth": {
"active": true,
"database": "oauth.nsf",
"url": "https://restapi.example.com",
"authCodeExpiresIn": 120,
"accessTokenExpiresIn": 3600,
"refreshTokenExpiresIn": 525600
}
}
When accessing the Admin UI through https://restapi.example.com/admin/ui and selecting Log in with OIDC → DRAPI, authentication works.
If I change only the url parameter to:
"url": "http://domino01.example.net:8880"
and access the Admin UI through http://domino01.example.net:8880/admin/ui, authentication also works.
Therefore, both hostnames and access methods are functional. The problem is that DRAPI can only be configured with one fixed OAuth URL at a time.
When accessing the Admin UI through the other hostname, the browser still tries to retrieve the OIDC configuration from the configured hostname, which may cause cross-origin errors.
I would like the built-in DRAPI Identity Provider to support both access methods simultaneously.
4. Behavior When oauth.url Is Omitted
According to the HCL documentation, active is explicitly marked as required, whereas url is described only as "Server URL".
Documentation:
https://opensource.hcltechsw.com/Domino-rest-api/howto/IdP/configuredrapiIdP.html
Additionally, the DRAPI v1.1.4 release notes describe automatically adding the oauth.url value to the allowed CORS URLs "if defined":
https://opensource.hcltechsw.com/Domino-rest-api/whatsnew/v1.1.4.html
Based on this documentation and the observed behavior, I tested the following configuration without the url property:
{
"oauth": {
"active": true,
"database": "oauth.nsf",
"authCodeExpiresIn": 120,
"accessTokenExpiresIn": 3600,
"refreshTokenExpiresIn": 525600
}
}
Interestingly, DRAPI appears to determine the hostname correctly.
However, after opening the Admin UI, selecting Log in with OIDC, and choosing DRAPI, the browser requests the following incorrect URLs.
Through the HTTPS reverse proxy:
https://restapi.example.com/admin/-build%20in-/.well-known/openid-configuration
Through the direct HTTP connection:
http://domino01.example.net:8880/admin/-build%20in-/.well-known/openid-configuration
The hostname and protocol are correct, but the additional path segment /admin/-build%20in-/ is incorrect.
The correct discovery URLs should be:
https://restapi.example.com/.well-known/openid-configuration
and:
http://domino01.example.net:8880/.well-known/openid-configuration
Both of these correct URLs are accessible and return OIDC discovery JSON documents.
This suggests that the built-in OAuth provider is running and the problem may be related to how the Admin UI generates or resolves its discovery URL when oauth.url is not configured.
5. Additional Problem: Incorrect Endpoint Hostnames in Discovery JSON
Although both correct /.well-known/openid-configuration URLs return JSON successfully, the returned metadata contains endpoint URLs using:
http://localhost:8880
For example, endpoint values for the authorization and token endpoints refer to the localhost address.
This is not suitable when the discovery document is requested remotely through either of the two hostnames.
Ideally, the returned endpoint URLs should be generated according to the public origin used for the request, provided this origin is trusted and configured.
For example, when requesting:
https://restapi.example.com/.well-known/openid-configuration
the discovery document should contain externally accessible HTTPS endpoint URLs.
When requesting:
http://domino01.example.net:8880/.well-known/openid-configuration
the endpoint URLs should match the directly accessible server address.
The issuer identifier and issued tokens must also remain consistent with OIDC requirements.
6. Reproduction on localhost
The same problem can be reproduced directly on the Windows Server 2025 machine hosting Domino REST API, without using any reverse proxy or external hostname.
Steps:
Remove the url property from oauth.json.
Restart Domino REST API.
Open a browser locally on the server.
Navigate to http://localhost:8880/admin/ui.
Select Log in with OIDC.
Select the built-in DRAPI provider.
The login process attempts to use a discovery URL containing:
http://localhost:8880/admin/-build%20in-/.well-known/openid-configuration
The request fails with HTTP 404:
{
"status": 404,
"message": "This is not the URL you seek!",
"errorId": 0
}
However, the following URL returns the OIDC discovery JSON successfully:
http://localhost:8880/.well-known/openid-configuration
This demonstrates that the malformed discovery URL problem is reproducible even without a reverse proxy or external access manager.
Supporting local login through localhost would also be useful for administration, testing, troubleshooting, and recovery scenarios.
7. Expected Behavior
When the oauth.url property is omitted, I would expect Domino REST API to:
Determine the public origin used to access the Admin UI, including the hostname, protocol, and port.
Construct the correct built-in OIDC discovery URL at the root-level /.well-known/openid-configuration path.
Generate appropriate externally accessible endpoint URLs in the discovery metadata.
Support authentication through any explicitly permitted hostname of the same DRAPI installation.
Respect trusted reverse-proxy headers where applicable.
Ensure consistent issuer identifiers, token claims, and endpoint validation according to OIDC security requirements.
Support local administration via localhost in environments where such access is enabled.
8. Suggested Enhancement Options
I see several possible approaches.
Option A – Automatic URL Detection (Preferred)
Allow oauth.url to be omitted, or introduce an explicit automatic mode:
"url": "auto"
The application would dynamically determine the appropriate URL based on the incoming request and trusted reverse-proxy information.
It should use an explicit list of permitted hostnames to prevent Host header injection or similar security issues.
Option B – Support Multiple Explicit URLs
Alternatively, allow an array of configured URLs:
"url": [
"https://restapi.example.com",
"http://domino01.example.net:8880"
]
DRAPI would select the appropriate configured URL based on the hostname through which the Admin UI was accessed.
This would provide administrators with explicit control over supported hostnames while avoiding unrestricted dynamic URL generation.
If necessary for OIDC compliance, each configured public URL could be treated as a distinct issuer configuration backed by the same DRAPI installation.
Option C – Separate Issuer URL and Administrative Access URLs
Another possibility would be to retain a single canonical OAuth issuer but introduce configuration options for additional Admin UI access hostnames.
This would allow administrators to access the same DRAPI installation through internal and external addresses without requiring changes to the canonical issuer configuration.
The implementation would need to ensure that OIDC discovery, cross-origin requests, redirects, and issuer validation remain consistent.
9. Requested Fix and Enhancement
I would appreciate clarification and consideration of the following:
Is omitting oauth.url intended to be supported?
If yes, could the incorrect /admin/-build%20in-/ discovery path be fixed?
Could DRAPI generate discovery endpoint URLs using the correctly determined public origin instead of defaulting to localhost:8880?
Could DRAPI support multiple permitted public hostnames for the same built-in OAuth/OIDC provider, either through automatic detection or an explicit list?
Could this also support local Admin UI authentication through localhost for maintenance and troubleshooting?
10. Why This Enhancement Would Be Useful
This functionality would be valuable in enterprise environments where the same Domino REST API server is accessible through different network paths.
Typical use cases include:
External access through a reverse proxy, load balancer, or enterprise access manager.
Direct internal access for administrators.
Local access on the Domino server for troubleshooting and maintenance.
Environments with separate internal and external DNS names.
Situations where external access infrastructure is temporarily unavailable but local administration is still necessary.
Currently, changing the fixed oauth.url value allows each access method to work individually, but there is no apparent way to support both simultaneously with the built-in DRAPI identity provider.
In my opinion, the existing behavior without oauth.url already demonstrates part of the desired functionality: the requested hostname is recognized correctly. Resolving the -build in- path issue and generating appropriate discovery metadata could provide the foundation for a more flexible solution.
