Configuring HTTP Bearer authentication using an OIDC provider

Client applications such as native apps, mobile apps, Progressive Web Apps (PWAs), and Single Page Apps (SPAs) can use HTTP bearer authentication with signed JWT access tokens acquired from an OIDC provider to authenticate to Domino servers.

Why a Bearer token?

Client applications that might be incapable of easily performing SAML-based SSO can instead authenticate end users using an OpenID Connect (OIDC) provider. In OAuth 2.0 and OIDC terminology, the Domino server is acting as a relying party, not an OAuth client, and is consuming an access token. HTTP Bearer authentication functions at the HTTP level, similar to but more securely than HTTP basic authentication, but may only be used over HTTPS.

In Domino 12.0.2, you can configure trusted OIDC providers in the IdP Catalog (idpcat.nsf) database. Each Internet Site can be configured with a different OIDC provider. Only one SAML IdP or OIDC provider can be configured for an individual Internet Site.

Each OIDC provider needs to expose a well-known/openid-configuration endpoint and a jwks_uri endpoint according to OpenID.Core and OpenID.Discovery, so that Domino can dynamically acquire the public keys used to cryptographically validate the JWTs issued by that OIDC provider.

Requirements for JWT access tokens used for HTTP Bearer authentication

  • This functionality uses the "Authorization: Bearer <token>" flow defined by RFC 6750.
  • JWTs must be generated by an OIDC provider that exposes .well-known/openid-configuration and jwks_uri endpoints per OpenID.Core and OpenID.Discovery.
  • This functionality is only available over TLS connections for security reasons per OpenID.Core.
  • JWTs must be signed with RS256, RS384, RS512, ES256, ES384, ES512, or EdDSA with Ed25519 or Ed448. "None" and HS256 are highly insecure and not supported for HTTP Bearer authentication per RFC 8725.
  • JWTs must contain a form of the end user's name or email address that Domino can find uniquely in the Domino directory. If the OIDC_CUSTOM_EMAIL_CLAIM_NAME notes.ini variable is set, Domino will check first for a claim with that specified name. If that custom claim name is not configured or the claim is not found, Domino will check for the standard "email" claim next, and will finally check for the "upn" claim.
  • JWTs must contain a "iss" (issuer) claim matching the "issuer" returned from the OIDC provider's .well-known/openid-configuration endpoint.
  • JWTs must contain a "kid" (keyID) header claim matching one of the JWKs returned from the OIDC provider's jwks_uri endpoint.
  • JWTs must contain a "scope" claim that includes "Domino.user.all".
  • One of the JWT's "aud" (audience) claims must match the Domino Internet Site's host name, such as https://ultraviolet.example.com
  • The JWT must contain "iat" (issued at) and "exp" (expiration) claims stating that the token was issued in the past and expires in the future.
  • If you want to allow only JWTs that were issued to a limited set of trusted applications (by client_id), you can configure the HTTP_BEARER_ALLOWED_ID_COUNT notes.ini to contain the number of permitted client_ids, and then configure HTTP_BEARER_ALLOWED_CLIENT_ID_1=<first client_id>, HTTP_BEARER_ALLOWED_CLIENT_ID_2=<second client_id>, and so on. If a nonzero set of allowed client_ids was configured, one of those client_ids must be found in the "azp" claim for the JWT to be valid.

Limitations

  • The OIDC provider document's "Logging level" field is ignored.
  • The only supported scope is "Domino.user.all" which grants full access as the authenticated end user.
  • Encrypted JWTs are not supported.
  • HTTP Bearer authentication is supported only on Windows and Linux servers.