OIDC

The OIDC Connector provides a way for Maverics to interact with any OIDC provider. The Connector automatically fetches the information from oidcWellKnownURL and uses the provided API endpoints to authenticate users and perform session validation.

By default, the OIDC connector follows the Authorization Code Flow with Proof Key for Code Exchange (PKCE). If the OIDC provider does not support PKCE, set the disablePKCE option to true.

Configuration options

The following values can be provided to the OIDC Connector via the Maverics configuration file.

OAuth Client ID

oauthClientID is the client ID of the Maverics application registered in the OIDC provider organization.

OAuth Client Secret

oauthClientSecret is the client secret used to register the Maverics application with the OIDC provider.

OAuth Redirect URL

oauthRedirectURL the Maverics OIDC callback handler is served on this URL.

It defines the URL that the OIDC provider will use to redirect the client back to after authentication. It must be an absolute URL and match exactly with one of the registered URLs on the provider.

The oauthRedirectURL path should not conflict with the path of any application resources. The path can be arbitrary (e.g. /maverics-oidc or /oidc-handler).

To support multiple hosts using a single connector, enable dynamic redirects by using the special sequence {{ http.request.host }}. This will use the host header from the incoming request. For example, when defining an oauthRedirectURL of https://{{ http.request.host }}/oidc and a request is made to https://app.example.com/protected, the redirect URL will be set to https://app.example.com/oidc.

OIDC Well-known URL

oidcWellKnownURL is the URL that returns OpenID Connect metadata about the OIDC provider authorization server.

OIDC Logout Callback URL

oidcLogoutCallbackURL the Maverics OIDC logout callback handler is served on this URL.

It defines the URL that the OIDC provider will use to redirect the client back to the application after logging out the user.

The oidcLogoutCallbackURL path should not conflict with the path of any application resources. The path can be arbitrary (e.g. /oidc-logout or /oidc/logout) and must typically be configured in the OIDC provider.

To support multiple hosts using a single connector, enable dynamic redirects by using the special sequence {{ http.request.host }}. This will use the host header from the incoming request. For example when defining an oidcLogoutCallbackURL of https://{{ http.request.host }}/oidc/logout and a logout request is made to https://app.example.com/slo, the redirect URL will be set to https://app.example.com/oidc/logout.

Disable PKCE

disablePKCE disables the Proof Key for Code Exchange (PKCE) extension (enabled by default).

Scopes

scopes is the scopes requested as part of the OIDC authentication flows. If not defined, it defaults to openid profile email.

Health Check

healthCheck defines an optional health check for the connector. This option is required when using the connector in an IDP-continuity scenario. For more info on how to define the health check, please see the docs.

Examples

OIDC Connector Configuration

connectors:
  - name: mavericsOIDC
    type: oidc
    oidcWellKnownURL: https://example.com/.well-known/openid-configuration
    oidcLogoutCallbackURL: https://example.com/oidc/logout
    oauthClientID: exampleID
    oauthClientSecret: exampleSecret
    oauthRedirectURL: https://example.com/oidc
    disablePKCE: false
    scopes: openid profile email custom-scope