Start/notes.ini Parameters/OIDC_LOGIN_CUSTOM_CLAIM_NAME

OIDC_LOGIN_CUSTOM_CLAIM_NAME

Profile

Parameter
OIDC_LOGIN_CUSTOM_CLAIM_NAME
Category
Security / TLS (OIDC / Web SSO)
Component
Server (HTTP task)
Available since
14.0
Supported versions
14.0, 14.5, 14.5.1
GUI equivalent
notes.ini only (no GUI)
Possible values
String with claim name from the id_token, e.g. sub, preferred_username, upn, oid
Empty/unconfigured: standard claim email (with fallback to upn)

Description

After the OIDC authorization code flow, Domino receives an id_token (signed JWT) from the provider. This token contains a number of claims — key/value pairs such as sub (subject identifier), email, name, preferred_username, upn (user principal name), oid (object ID, Azure-specific), etc.
By default, Domino reads the email claim from the id_token to map the user to a person document in the Domino Directory (via the MailAddress or InternetAddress field). If the email claim is missing, fallback to the upn claim.
Problems with the default:
  • Some B2B/B2C identity providers do not return an email address in the id_token for privacy or configuration reasons.
  • In Azure AD, the mapping between user and email is sometimes unreliable — instead, upn or oid is the more stable identifier.
  • With Keycloak, preferred_username is often the primary login name.
OIDC_LOGIN_CUSTOM_CLAIM_NAME allows choosing an alternative claim as the primary user identifier. This is then resolved against the Domino Directory (via Lookup in the primary directory) — i.e., the value of the claim must be stored as email address / login name / alternate address in the person document.
Important regarding spelling: the HCL docs mention two similar spellings — OIDC_LOGIN_CUSTOM_CLAIM_NAME and OIDC_LOGIN_CUSTOM_NAME_CLAIM. Officially correct is OIDC_LOGIN_CUSTOM_CLAIM_NAME (used in the Domino 14.5.1 docs); the other spelling appears in an example in the same document and is likely a doc typo. When in doubt, test both spellings or check with DEBUG_OIDCLogin=4 which is accepted.

Example configuration

Azure AD — stable user identifier instead of email:
OIDC_LOGIN_CUSTOM_CLAIM_NAME=upn
Keycloak — mapping via username:
OIDC_LOGIN_CUSTOM_CLAIM_NAME=preferred_username
If the provider supplies no identifier other than the subject ID:
OIDC_LOGIN_CUSTOM_CLAIM_NAME=sub

Notes & pitfalls

  • The value of the configured claim must be resolvable in the Domino Directory — either as primary email address, alternate address, or via an additional field that is taken into account in the directory lookup configuration.
  • When using sub (= unique, opaque string ID of the provider): this ID must be stored as an additional identifier in the person document, e.g. via a custom field or an entry in AltFullName / MailAddress.
  • Prerequisite: HTTP Bearer Authentication and web login with OIDC are activated in the relevant internet site document.
  • Symptoms with a wrong claim name: login fails with "user not found" or "unable to map identity", although authentication at the provider was successful.
  • With DEBUG_OIDCLogin=4, all claims of the id_token are output on the server console — ideal for identifying the right claim name.
  • Change takes effect after HTTP task restart or via set config OIDC_LOGIN_CUSTOM_CLAIM_NAME=….
  • Works only on Windows and Linux servers.
  • When falling back to upn: note that UPN in Azure AD is not necessarily equal to the mail address (e.g. user@tenant.onmicrosoft.com vs. user@example.com).

Sources (HCL Product Documentation)