Start/notes.ini Parameter/OIDC_LOGIN_CUSTOM_CLAIM_NAME

OIDC_LOGIN_CUSTOM_CLAIM_NAME

Steckbrief

Parameter
OIDC_LOGIN_CUSTOM_CLAIM_NAME
Kategorie
Security / TLS (OIDC / Web-SSO)
Komponente
Server (HTTP-Task)
Verfügbar seit
14.0
Unterstützte Versionen
14.0, 14.5, 14.5.1
GUI-Entsprechung
Nur notes.ini (keine GUI)
Mögliche Werte
String mit Claim-Namen aus dem id_token, z. B. sub, preferred_username, upn, oid
Leer/unkonfiguriert: Standard-Claim email (mit Fallback auf upn)

Beschreibung

Nach dem OIDC-Authorization-Code-Flow erhält Domino vom Provider ein id_token (signiertes JWT). Dieses Token enthält eine Reihe von Claims — Schlüssel/Wert-Paare wie sub (Subject Identifier), email, name, preferred_username, upn (User Principal Name), oid (Object ID, Azure-spezifisch), etc.
Standardmäßig liest Domino den email-Claim aus dem id_token, um den User mit einem Person-Dokument im Domino Directory zu mappen (über das MailAddress-Feld bzw. InternetAddress-Feld). Wenn der email-Claim fehlt, fallback auf den upn-Claim.
Probleme mit dem Default:
  • Manche B2B/B2C-Identity-Provider geben aus Datenschutz- oder Konfigurationsgründen keine Email-Adresse im id_token zurück.
  • In Azure AD ist das Mapping zwischen User und Email manchmal unzuverlässig — stattdessen ist upn oder oid der stabilere Identifier.
  • Bei Keycloak ist preferred_username oft der primäre Login-Name.
OIDC_LOGIN_CUSTOM_CLAIM_NAME erlaubt es, einen alternativen Claim als primären User-Identifier zu wählen. Dieser wird dann gegen das Domino Directory aufgelöst (per Lookup im primären Verzeichnis) — d. h. der Wert des Claims muss als Email-Adresse / Login-Name / Alternate-Address im Person-Dokument hinterlegt sein.
Wichtig zur Schreibweise: Die HCL-Doku erwähnt zwei ähnliche Schreibweisen — OIDC_LOGIN_CUSTOM_CLAIM_NAME und OIDC_LOGIN_CUSTOM_NAME_CLAIM. Korrekt ist offiziell OIDC_LOGIN_CUSTOM_CLAIM_NAME (in der Domino-14.5.1-Doku verwendet); die andere Schreibweise erscheint in einem Beispiel desselben Dokuments und dürfte ein Doku-Tippfehler sein. Im Zweifel beide Schreibweisen testen oder mit DEBUG_OIDCLogin=4 prüfen, welche akzeptiert wird.

Beispiel-Konfiguration

Azure AD — stabiler User-Identifier statt Email:
OIDC_LOGIN_CUSTOM_CLAIM_NAME=upn
Keycloak — Mapping über Username:
OIDC_LOGIN_CUSTOM_CLAIM_NAME=preferred_username
Wenn der Provider gar keine Identifier außer der Subject-ID liefert:
OIDC_LOGIN_CUSTOM_CLAIM_NAME=sub

Hinweise & Stolperfallen

  • Der Wert des konfigurierten Claims muss im Domino Directory auflösbar sein — entweder als primäre Email-Adresse, Alternate-Address oder über ein zusätzliches Feld, das in der Directory-Lookup-Konfiguration berücksichtigt wird.
  • Bei Verwendung von sub (= eindeutige, undurchsichtige String-ID des Providers): Diese ID muss als zusätzlicher Identifier im Person-Dokument hinterlegt werden, z. B. über ein eigenes Feld oder einen Eintrag in AltFullName / MailAddress.
  • Voraussetzung: HTTP Bearer Authentication und Web-Login mit OIDC sind im betreffenden Internet Site-Dokument aktiviert.
  • Symptome bei falschem Claim-Namen: Login schlägt mit „user not found" oder „unable to map identity" fehl, obwohl die Authentifizierung am Provider erfolgreich war.
  • Mit DEBUG_OIDCLogin=4 werden alle Claims des id_tokens auf der Server-Konsole ausgegeben — ideal, um den richtigen Claim-Namen zu identifizieren.
  • Änderung wirkt nach Neustart des HTTP-Tasks bzw. via set config OIDC_LOGIN_CUSTOM_CLAIM_NAME=….
  • Funktioniert nur auf Windows- und Linux-Servern.
  • Bei Fallback auf upn: Beachten, dass UPN in Azure AD nicht zwingend gleich der Mail-Adresse ist (z. B. user@tenant.onmicrosoft.com vs. user@example.com).

Quellen (HCL Product Documentation)