Domino OIDC provider HTTP endpoints

The endpoints supported by the Domino OIDC provider are listed and described in the following sections.

/auth/protocol/oidc/.well-known/openid-configuration

This endpoint is defined by OpenID.Core and OpenID.Discovery and responds to a GET request from an OIDC Relying Party with the location of the other endpoints as well as some related metadata.

/auth/protocol/oidc/keys

This endpoint responds to a GET request with the OIDC provider's public signing keys in the standard jwks_uri format. OIDC Relying Parties can use these keys to verify signatures on the signed JWT access tokens and ID tokens.

This same endpoint is also used to return the public keys used for private_key_jwt authentication by Domino's Web Login with OIDC functionality starting in 14.0 GA.

If both Domino Web Login with OIDC and the Domino OIDC provider are enabled for a single Internet Site, both sets of public keys will be returned.

/auth/protocol/oidc/auth

The authorization endpoint as defined by OpenID.Core and the OAuth 2.0 RFCs only accepts GET requests.

Table 1. Parameters for the /auth/protocol/oidc/auth endpoint
Parameter Name Required? Description
response_type Required Must be "code" for the Authorization Code flow with PKCE
client_id Required Must match the client_id value for a registered client
redirect_uri Required Must correspond to a configured redirect_uri value for this registered client
scope Required Must be a subset of the configured scopes for this registered client
state Recommended This value will be returned in the response from this endpoint
code_challenge_method Recommended Unless the client is configured with optional PKCE, this must be "S256"
code_challenge Recommended PKCE code_challenge value
nonce Optional If present, this value will be in the Nonce claim of the resulting id_token
resource Optional If present, must match a configured audience for this registered client
Things to know:
  • An id_token will be returned from the token endpoint only if the "openid" scope is present.
  • If the resource parameter is not present, the first configured audience for this registered client will be used.
  • Current security best practices strongly recommend against generating access tokens with multiple audiences. Accordingly, in 14.5, the Domino OIDC provider will generate only single-audience access tokens.

/auth/protocol/oidc/token

The token endpoint as defined by OpenID.Core and the OAuth 2.0 RFCs only accepts POST requests. The "bearer token" JSON response will include an id_token if and only if the "openid" scope was both configured for the authenticated client and was included in the requested scopes sent to the authorization endpoint.

The Authorization Code grant type takes an authorization code acquired from the authorization endpoint and returns a bearer token JSON response. Note that authorization codes are single-use only.

Table 2. Parameters for the authorization_grant flow at the /auth/protocol/oidc/token endpoint
Parameter Name Required? Description
grant_type Required Must be "authorization_code"
code Required The "code" value returned from the authorization endpoint
redirect_uri Required Must match the redirect_uri provided to the authorization endpoint
client_id Optional Optional for client_secret_basic auth; if present must match Authorization: Basic header
code_verifier Recommended PKCE code_verifier value

The Refresh Token grant type takes the most recent refresh token acquired from the token endpoint and returns a bearer token JSON response. Note that refresh tokens are single-use only, and that new refresh tokens will be issued by every successful request to the token endpoint.

Table 3. Parameters for the refresh_token flow at the /auth/protocol/oidc/token endpoint
Parameter Name Required? Description
grant_type Required Must be "refresh_token"
refresh_token Required Required refresh_token value received from a previous call to the token endpoint
client_id Optional Optional for client_secret_basic auth; if present must match Authorization: Basic header

Note that some OAuth Authorization Servers require an "offline_access" scope to return a refresh token. Domino 14.5 will always return a refresh token.

/auth/protocol/oidc/revoke

The OAuth revocation endpoint as defined by RFC 7009 only accepts POST requests. Can only be used to revoke refresh tokens; per current security best practices we recommend using very short lived access tokens; the default access token lifetime is 300 seconds. The "token" parameter must contain the refresh token to be revoked. This endpoint requires client authorization, so public clients cannot access this endpoint.

Successful revocation requests will revoke all of the refresh tokens derived from this token's authorization grant and also send a back-channel logout request if the registered client is configured for back-channel logout.

/auth/protocol/oidc/introspect

The OAuth Introspection endpoint as defined by RFC 7662 only accepts POST requests. This endpoint was designed for use by consumers that do not directly support OIDC or validating signed JWT access tokens, such as the nginx web proxy. This endpoint will only return either {"active":true} or {"active":false} when called correctly; relying parties who need access to the contents of the access token should just parse the signed JWT access token directly. This endpoint requires authentication per RFC 7662, so public clients cannot access this endpoint. The access token to be validated must be passed via the "token" POST parameter. Clients that are configured as "Introspection Only" can only access this endpoint and cannot acquire tokens of their own; this setting is intended for use by authenticating proxies and similar applications.

/auth/protocol/oidc/logout

The OIDC logout endpoint as defined by OpenID.RPInitiated accepts both GET and POST requests. Note that the logout endpoint cannot be used if the Domino OIDC provider site is configured for Multi-Server SSO (LTPA).

Table 4. Parameters for /auth/protocol/oidc/logout
Parameter Name Required? Description
id_token_hint Recommended. Required if no session cookie was sent Contains an id_token that was sent to this client to authenticate this end user.
logout_hint No
client_id Optional Used to identify the OAuth client if no id_token_hint was provided.
post_logout_redirect_uri Optional Must match a registered post_logout_redirect_uri for this client. If no client was identified via client_id or id_token_hint then the post_logout_redirect_uri must not be provided.
state Optional ?state=<state> will be appended to the post_logout_redirect_uri if used.

/auth/protocol/oidc/userinfo

This endpoint is defined by OIDC.Core and responds to both GET and POST requests. A JWT access token issued by this provider may be sent in an Authorization: Bearer <token> header or the access_token POST payload parameter to this endpoint and if the token is valid, the JSON payload of the token will be returned. This endpoint is only useful for Relying Parties that are capable of parsing a JSON payload and not capable of parsing a JSON Web Token (JWT).