Configuration reference

Configuration reference

The configuration for this module can be defined in your nuxt.config.ts file:

export default defineNuxtConfig({
  oidc: {
    defaultProvider: '<provider>',
    providers: {
      <provider>: {
        clientId: '...',
        clientSecret: '...'
      }
    },
    middleware: {
      globalMiddlewareEnabled: true,
      customLoginPage: false
    }
  }
})

Global configuration (oidc)

Provider Configuration (provider)

<provider>

Runtime environment overrides

Every serializable provider option can be supplied through Nuxt runtime environment variables, including options omitted from nuxt.config.ts. Nested provider session fields and provider-declared additional parameters follow Nuxt's uppercase underscore naming; record and list values can also use JSON:

NUXT_OIDC_PROVIDERS_KEYCLOAK_CLIENT_ID=web-client
NUXT_OIDC_PROVIDERS_KEYCLOAK_SESSION_CONFIGURATION_MAX_AUTH_SESSION_AGE=180
NUXT_OIDC_PROVIDERS_KEYCLOAK_OPEN_ID_CONFIGURATION=https://id.example.com/realms/app/.well-known/openid-configuration
NUXT_OIDC_PROVIDERS_OIDC_ADDITIONAL_AUTH_PARAMETERS={"prompt":"consent"}

Runtime environment values take precedence over values from nuxt.config.ts and provider defaults. Functions are not serializable runtime inputs; configure openIdConfiguration as a URL when it must be changed at deployment time.

Endpoint resolution and validation

An explicitly configured endpoint takes precedence over the provider preset and baseUrl. Absolute http or https endpoints are used unchanged. Relative explicit or preset endpoints are resolved against baseUrl; a flow that needs a relative endpoint fails configuration validation when baseUrl is absent. Explicit empty userInfoUrl and logoutUrl values disable those optional endpoints.

Validation is flow-specific. Login requires its authorization inputs, callback and refresh require their token and enabled validation inputs, and logout validates only configured logout behavior. This allows configurations that provide complete absolute endpoints to omit a provider baseUrl.

Reading effective provider configuration on the server

Use useOidcProviderConfig in server routes and utilities to read resolved provider defaults, runtime environment overrides, endpoint URLs, and provider placeholders:

export default defineEventHandler((event) => {
  const github = useOidcProviderConfig(event, 'github')
  return { authorizationUrl: github.authorizationUrl }
})

This helper is server-only and returns EffectiveProviderConfig for the selected provider. Values stored directly in useRuntimeConfig(event).oidc.providers use ProviderRuntimeConfig, the raw override shape. Do not treat that raw storage as resolved configuration or expose it to client code.

NODE_ENV is classified as production when its value starts with prod, case-insensitively. This classification controls the default secure-cookie flag and disables dev mode. Values such as production, prod, and PROD-preview are production; an unset value is non-production.

Global session configuration (session)

The following options are available for the global session configuration.

Note that singleSignOut and singleSignOutIdField are provider specific options and can only be configured in providers.<provider>.sessionConfiguration.

Provider session configuration

The following options are available on every provider as overrides for the global session configuration.

Middleware configuration (middleware)

Dev Mode configuration (devMode)

For more details, please check the dev mode docs page

Example configuration

  oidc: {
    defaultProvider: 'github',
    providers: {
      github: {
        redirectUri: 'http://localhost:3000/auth/github/callback',
        clientId: '',
        clientSecret: '',
        filterUserInfo: ['login', 'id', 'avatar_url', 'name', 'email'],
      },
      keycloak: {
        audience: 'account',
        baseUrl: '',
        clientId: '',
        clientSecret: '',
        redirectUri: 'http://localhost:3000/auth/keycloak/callback',
        userNameClaim: 'preferred_username',
      },
      cognito: {
        clientId: '',
        redirectUri: 'http://localhost:3000/auth/cognito/callback',
        clientSecret: '',
        scope: ['openid', 'email', 'profile'],
        logoutRedirectUri: 'https://google.com',
        baseUrl: '',
        exposeIdToken: true,
      },
      zitadel: {
        clientId: '',
        redirectUri: 'http://localhost:3000/auth/zitadel/callback',
        baseUrl: '',
        audience: '', // Specify for id token validation, normally same as clientId
        logoutRedirectUri: 'https://google.com', // Needs to be registered in Zitadel portal
        authenticationScheme: 'none',
      },
    },
    session: {
      expirationCheck: true,
      automaticRefresh: true,
      expirationThreshold: 3600,
      missingPersistentSession: 'clear',
    },
    middleware: {
      globalMiddlewareEnabled: true,
      customLoginPage: true,
      customLogoutPage: false,
    },
    devMode: {
      enabled: false,
      generateAccessToken: true,
      userName: 'Test User',
      userInfo: { providerName: 'test' },
      claims: { customclaim01: 'foo', customclaim02: 'bar' },
      issuer: 'dev-issuer',
      audience: 'dev-app',
      subject: 'dev-user',
    },
  },