Start/notes.ini Parameters/DEBUG_HTTP_BEARER_AUTH

DEBUG_HTTP_BEARER_AUTH

Parameter: DEBUG_HTTP_BEARER_AUTH
Short description: Enables debug tracing for HTTP Bearer token authentication in Domino. Helps analyze failed OIDC bearer logins (e.g. invalid aud claims, expired tokens, missing scopes) on the server console.

Profile

Parameter
DEBUG_HTTP_BEARER_AUTH
Category
Logging / Debug
Component
Server (HTTP task)
Available since
Domino 12.0.2
Supported versions
12.0.2, 14.0, 14.5, 14.5.1
GUI equivalent
notes.ini only (no GUI)
Possible values
0, 1, 2, 3, 4 — default 0 (off)

Description

DEBUG_HTTP_BEARER_AUTH controls the level of detail of the HTTP task's trace output when validating incoming JWT bearer tokens. With Bearer Authentication enabled (Bearer Token = Yes in the Server or Internet Site document), Domino processes the Authorization: Bearer … header, validates the token against the OIDC provider configured in the IdP catalog (idpcat.nsf), and maps it to a Domino user.
Validations include:
  • Issuer (iss) — must match the configured provider
  • Signature — against the JWK delivered by the provider
  • Audience (aud) or Authorized Party (azp) — must match the Internet Site or the „Allowed Client IDs“ list
  • Lifetime (iat/exp) — token must not have been issued in the future and must not have expired
  • Scope — must contain Domino.user.all
  • E-mail claim — typically email, alternatively via Custom Email Claim Name in idpcat
With increasing level (0 → 4), more steps, header and payload contents are logged in console.log and — if set — in DEBUG_OUTFILE. Level 4 also writes sensitive token contents to the log and should only be enabled briefly for fault analysis.
The parameter was introduced with Domino 12.0.2 along with the HTTP Bearer Auth feature and remained unchanged in 14.0/14.5/14.5.1, while other Bearer Auth notes.ini variables (HTTP_BEARER_ALLOWED_ID_COUNT, HTTP_CUSTOM_EMAIL_CLAIM_NAME, HTTP_BEARER_ENABLE_MS_WORKAROUNDS) moved to idpcat.nsf from 14.0 onward.

Example configuration

DEBUG_HTTP_BEARER_AUTH=2
DEBUG_OUTFILE=C:\Domino\IBM_TECHNICAL_SUPPORT\bearer_debug.txt
Dynamically on the server console:
set config DEBUG_HTTP_BEARER_AUTH=2
To turn off:
set config DEBUG_HTTP_BEARER_AUTH=0

Notes & pitfalls

  • Only takes effect when Bearer Authentication is enabled in the Server or Internet Site document and an OIDC provider has been configured in idpcat.nsf.
  • Effect is dynamic: no HTTP or server restart needed — set config … is sufficient.
  • Level 4 logs full bearer tokens (sensitive!). After analysis, reset to 0 and dispose of the logs securely.
  • For connection or certificate errors to the OIDC provider, DEBUG_OIDC_CURL_APIS provides additional details.
  • For cache/JWK issues, from 14.0 onward enable DEBUG_OIDC_CACHE (replaces the old DEBUG_JWK_CACHE/DEBUG_JWK_CACHE_MGR).
  • Writes only to the server console / outfile — no separate log file.

Sources (HCL Product Documentation)