Generic OIDC (advanced)

Introduction

This is a generic OIDC provider without provider-specific defaults. If your provider is not listed, you should be able to configure it with this provider. Configure the endpoints explicitly, or let the module discover them from the provider's OpenID configuration.

This is the generic providers default configuration:

const defaults: Partial<OidcProviderConfig> = {
  clientId: '',
  redirectUri: '',
  clientSecret: '',
  authorizationUrl: '',
  tokenUrl: '',
  responseType: 'code',
  authenticationScheme: 'header',
  grantType: 'authorization_code',
  pkce: true,
  state: true,
  nonce: false,
  scope: ['openid'],
  scopeInTokenRequest: false,
  tokenRequestType: 'form',
  requiredProperties: ['clientId', 'redirectUri', 'clientSecret', 'authorizationUrl', 'tokenUrl'],
  validateAccessToken: true,
  validateIdToken: true,
  tokenValidationMode: 'strict',
  skipAccessTokenParsing: false,
  storeAccessToken: false,
  exposeAccessToken: false,
  exposeIdToken: false,
  callbackRedirectUrl: '/',
  allowedClientAuthParameters: undefined,
  logoutUrl: '',
  sessionConfiguration: {
    automaticRefresh: true,
    expirationThreshold: 0,
    expirationCheck: true,
    singleSignOut: false,
    singleSignOutIdField: 'sub',
    maxAuthSessionAge: undefined,
  },
  additionalAuthParameters: undefined,
  additionalTokenParameters: undefined,
  additionalLogoutParameters: undefined,
  excludeOfflineScopeFromTokenRequest: false,
}

Example Configuration

Endpoint discovery

Set openIdConfiguration to the provider's discovery URL to skip the endpoint settings. Remove any trailing slash from the issuer before appending /.well-known/openid-configuration.

oidc: {
  providers: {
    oidc: {
      clientId: '',
      clientSecret: '',
      redirectUri: 'https://app.example.com/auth/oidc/callback',
      openIdConfiguration: 'https://id.example.com/realms/app/.well-known/openid-configuration',
      tokenRequestType: 'form-urlencoded',
      // Opaque access tokens cannot be validated as JWTs. The ID token is still validated.
      validateAccessToken: false,
      skipAccessTokenParsing: true,
    },
  },
},

When authorizationUrl or tokenUrl is not configured, every flow (login, callback, refresh and logout) loads the metadata once and uses authorization_endpoint, token_endpoint, userinfo_endpoint and end_session_endpoint for endpoints you did not configure. Token validation in the same flow reuses the loaded issuer and jwks_uri.

• An explicitly configured endpoint always takes precedence over the discovered one.
• Set userInfoUrl: '' or logoutUrl: '' to keep the module from calling the discovered userinfo or end session endpoint.
• The issuer in the metadata must equal the discovery URL without /.well-known/openid-configuration, allowing one trailing slash on the issuer, as required by OpenID Connect Discovery 1.0. Discovered endpoints must be absolute HTTP or HTTPS URLs; HTTPS discovery requires HTTPS endpoints, including jwks_uri. Invalid or unavailable metadata prevents login and callback, and clears the session during refresh. Logout clears the local session and skips provider logout when discovery fails.
• Requests go through the configured proxy.
• To return from provider logout to your app, configure logoutRedirectParameterName as required by your provider, commonly post_logout_redirect_uri, and set logoutRedirectUri. Providers that need an ID token hint also require additionalLogoutParameters: { idTokenHint: '' } and a stored or exposed ID token.

The default strict validation also validates the access token, which only works when the provider issues JWT access tokens for a known API. Either disable access token validation as shown above, or keep it and set audience to the API audience your provider puts in the access token's aud claim. The module does not use the client ID as the access token audience.

Explicit endpoints

oidc: {
  providers: {
    oidc: {
      clientId: '',
      clientSecret: '',
      redirectUri: 'https://app.example.com/auth/oidc/callback',
      openIdConfiguration: 'https://id.example.com/realms/app/.well-known/openid-configuration',
      authorizationUrl: 'https://id.example.com/realms/app/authorize',
      tokenUrl: 'https://id.example.com/realms/app/token',
      userInfoUrl: 'https://id.example.com/realms/app/userinfo',
      tokenRequestType: 'form-urlencoded',
      validateAccessToken: false,
      skipAccessTokenParsing: true,
    },
  },
},

Environment variables

Dotenv files are only for (local) development. Use a proper configuration management or injection system in production.

Any provider option can be supplied as an environment variable using the NUXT_OIDC_PROVIDERS_OIDC_<OPTION> prefix (screaming snake case). A typical minimal set with endpoint discovery:

NUXT_OIDC_PROVIDERS_OIDC_CLIENT_ID=CLIENT_ID
NUXT_OIDC_PROVIDERS_OIDC_CLIENT_SECRET=CLIENT_SECRET
NUXT_OIDC_PROVIDERS_OIDC_OPEN_ID_CONFIGURATION=https://issuer.example.com/.well-known/openid-configuration
NUXT_OIDC_PROVIDERS_OIDC_REDIRECT_URI=http://localhost:3000/auth/oidc/callback

With explicit endpoints, add these settings. Keep openIdConfiguration for token validation:

NUXT_OIDC_PROVIDERS_OIDC_AUTHORIZATION_URL=https://issuer.example.com/authorize
NUXT_OIDC_PROVIDERS_OIDC_TOKEN_URL=https://issuer.example.com/token
NUXT_OIDC_PROVIDERS_OIDC_USER_INFO_URL=https://issuer.example.com/userinfo