Configuration reference

Configuration reference for nuxt-oidc-auth

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)

OptionTypeDefaultDescription
enabledbooleantrueEnables/disables the module
defaultProviderProviderKeysundefinedSets the default provider. Enables automatic registration of generic /auth/login and /auth/logout route rules
providersPartial<ProviderConfigs>{}Configuration entries for each configured provider. For provider specific config see Provider specific configurations
sessionOmit<AuthSessionConfig, 'singleSignOutIdField' | 'singleSignOut'>Global session configurationOptional global session configuration
middlewareMiddlewareConfigMiddleware configurationOptional middleware specific configuration
devModeDevModeConfigDev Mode configurationConfiguration for local dev mode
devtoolsbooleantrueEnables/disables Nuxt DevTools integration for this module
provideDefaultSecretsbooleantrueProvide defaults for NUXT_OIDC_SESSION_SECRET, NUXT_OIDC_TOKEN_KEY and NUXT_OIDC_AUTH_SESSION_SECRET using a Nitro plugin. Only a five-character prefix of generated values is logged; with dev mode on the dev server the full values are shown in Nuxt DevTools. Turning this off can lead to the app not working if no secrets are provided

Provider Configuration (provider)

<provider>

OptionTypeDefaultDescription
clientIdstring''Client ID
clientSecretstring''Client secret. Required for header and body authentication; omitted for none.
responseType'code' | 'code token' | 'code id_token' | 'id_token token' | 'code id_token token' (optional)codeResponse Type
authenticationScheme'header' | 'body' | 'none' (optional)headerToken endpoint client authentication scheme. Use none for public clients.
responseMode'query' | 'fragment' | 'form_post' | string (optional)-Response mode for authentication request
authorizationUrlstring (optional)''Authorization endpoint URL
tokenUrlstring (optional)''Token endpoint URL
userInfoUrlstring (optional)''Userinfo endpoint URL
redirectUristring (optional)''Redirect URI
grantType'authorization_code' | 'refresh_token' (optional)authorization_codeGrant Type
scopestring[] (optional)['openid']Scope
pkceboolean (optional)trueUse PKCE (Proof Key for Code Exchange). Individual provider presets may override this.
stateboolean (optional)trueUse state parameter with a random value. Nonce does not replace state, because it is only checked when the ID token is validated.
nonceboolean (optional)falseUse nonce parameter with a random value.
promptArray<'none'> | Array<'login' | 'consent' | 'select_account'> (optional)undefinedSpace-delimited prompt values added to the authorization request.
userNameClaimstring (optional)''User name claim that is used to get the user name from the access token as a fallback in case the userinfo endpoint is not provided or the userinfo request fails.
optionalClaimsstring[] (optional)[]Claims to be extracted from the id token
logoutUrlstring (optional)''Logout endpoint URL
logoutRedirectUristring (optional)undefinedRedirect URI appended to the logout endpoint if configured
scopeInTokenRequestboolean (optional)falseInclude scope in token request
excludeOfflineScopeFromTokenRequestboolean (optional)falseStrip the offline_access scope from token and refresh requests for providers that reject it.
tokenRequestType'form' | 'form-urlencoded' | 'json' (optional)'form'Token request type
audiencestring (optional)-Audience used for token validation (not included in requests by default, use additionalTokenParameters or additionalAuthParameters to add it)
requiredPropertiesstring[]['clientId', 'redirectUri', 'clientSecret', 'authorizationUrl', 'tokenUrl']Required properties validated after runtime resolution. clientSecret is ignored only when authenticationScheme is none.
filterUserInfostring[] (optional)undefinedFilter userinfo response to only include these properties.
skipAccessTokenParsingboolean (optional)falseSkip access token parsing (for providers that don't follow the OIDC spec/don't issue JWT access tokens).
logoutRedirectParameterNamestring (optional)''Query parameter name for logout redirect. Will be appended to the logoutUrl as a query parameter.
additionalAuthParametersRecord<string, string> (optional)undefinedAdditional parameters to be added to the authorization request. See Provider specific configurations for possible parameters.
additionalTokenParametersRecord<string, string> (optional)undefinedAdditional parameters to be added to the token request. See Provider specific configurations for possible parameters.
additionalLogoutParametersRecord<string, string> (optional)undefinedAdditional parameters to be added to the logout request. See Provider specific configurations for possible parameters.
baseUrlstring (optional)''Provider Only. Base URL for the provider, used when to dynamically create authorizationUrl, tokenUrl, userInfoUrl and logoutUrl if possible.
openIdConfigurationstring, Record<string, unknown>, or function (config) => Promise<Record<string, unknown>> (optional)undefinedOpenID Configuration URL, object, or function that resolves to an OpenID Configuration object. Used for token validation and, when authorizationUrl or tokenUrl is not configured, for endpoint discovery.
validateAccessTokenboolean (optional)trueValidate access token.
validateIdTokenboolean (optional)trueValidate id token.
tokenValidationMode beta.12+'legacy' | 'strict' (optional)'strict'strict validates every enabled JWT in callback and refresh token responses with token-specific audience, issuer, signature, and expiration checks. Strict access-token validation requires audience; any enabled strict validation requires OpenID discovery metadata with issuer and jwks_uri. legacy only verifies a token when its decoded (unverified) audience matches and otherwise trusts the decoded claims; use it only for backwards compatibility.
encodeRedirectUriboolean (optional)falseEncode redirect uri query parameter in authorization request. Only for compatibility with services that don't implement proper parsing of query parameters.
storeAccessToken beta.13+boolean (optional)falseStore encrypted tokens for server-side getAccessToken calls without exposing them to the browser. Sessions with a refresh token or exposed tokens already store them. Requires token encryption and session storage; see session management
exposeAccessTokenboolean (optional)falseExpose access token to the client within session object. Server handlers can use getAccessToken without exposing it
exposeIdTokenboolean (optional)falseExpose raw id token to the client within session object
callbackRedirectUrlstring (optional)/Set a custom redirect url after a successful callback. If explicitly configured, it takes precedence over middleware-provided callbackRedirectUrl values
allowedCallbackRedirectUrlsstring[] (optional)[]Allowlist (prefix-matched) for the redirectUri login query parameter. A matching value overrides the OAuth redirect_uri sent to the provider for that flow.
allowedClientAuthParametersstring[] (optional)[]Allowlist of client-supplied login query parameters forwarded to the authorization request. Reserved OAuth/OIDC parameters are dropped, except prompt, see client prompt.
proxystring (optional)undefinedProxy URL used for outbound requests to this provider. Requires the optional undici package
ignoreProxyCertificateErrorsboolean (optional)falseDisable proxy certificate validation (development only, insecure for production)
requestTimeout beta.13+number (optional)10000Milliseconds a request to this provider may take, including its response body. A token refresh that exceeds it counts as unanswered and pauses refreshes for this provider for 30 seconds
sessionConfigurationProviderSessionConfig (optional){}Session configuration overrides, see session

Client prompt

beta.13+

Listing prompt in allowedClientAuthParameters lets each login request choose its own prompt, for example to switch accounts or to start sign-up. The client value must be one of none, create, or a space-separated combination of login, consent and select_account. Values are case-sensitive and none and create must stand alone. Unlike the static prompt option, the client value also accepts create; whether the provider shows a sign-up page depends on its support.

A valid client value replaces prompt and additionalAuthParameters.prompt for that request. Invalid, empty or repeated values are dropped and the configured prompt applies, if any. Without prompt in the allowlist, clients can't set or change it.

nuxt.config.ts
oidc: {
  providers: {
    entra: {
      allowedClientAuthParameters: ['prompt'],
    },
  },
}
const { login } = useOidcAuth()
login('entra', { prompt: 'select_account' })

Runtime environment overrides

beta.12+

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

beta.12+

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.

beta.13+ When openIdConfiguration is set and authorizationUrl or tokenUrl is not configured, each flow loads the OpenID configuration once and fills the endpoints you did not configure from authorization_endpoint, token_endpoint, userinfo_endpoint and end_session_endpoint. Explicit endpoints and explicit empty userInfoUrl and logoutUrl values still take precedence. A discovery URL must end in /.well-known/openid-configuration, and the returned issuer must equal the URL without that suffix, allowing one trailing slash on the issuer. HTTPS discovery requires HTTPS discovered endpoints, including jwks_uri. Preset metadata functions remain limited to token validation. See Generic OIDC for an example.

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

beta.12+

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 server-only helper returns EffectiveProviderConfig synchronously. It resolves configured values and provider presets without fetching discovery metadata. Authentication flows load discovered endpoints when needed. 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. The default secure-cookie flag is resolved from this classification at runtime, so a production deployment gets Secure cookies even when the build did not run with a production NODE_ENV (an explicit cookie.secure value still takes precedence). It is also used as a secondary guard for the dev-mode endpoints. Values such as production, prod, and PROD-preview are production; an unset value is non-production. Dev mode itself is gated on the dev server and stripped from production builds regardless of NODE_ENV (see Dev mode).

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.

OptionTypeDefaultDescription
cookieNamestring'nuxt-oidc-auth'Cookie name used for the user session
automaticRefreshbooleantrueAutomatically refresh access token and session if refresh token is available (indicated by canRefresh property on user object)
expirationCheckbooleantrueCheck if session is expired based on access token exp
expirationThresholdnumber0 or the provider preset valueAmount of seconds before access token expiration to trigger automatic refresh. Set it in nuxt.config to override it with NUXT_OIDC_SESSION_EXPIRATION_THRESHOLD, since runtime config only applies environment variables to keys it already has
missingPersistentSession'clear' | 'warn' | 'silent''clear'Behavior when a refreshable cookie session exists but the persistent session entry is missing. clear removes stale session and requires re-login, warn keeps session and logs a warning, silent keeps session without warning
maxAgenumber60 * 60 * 24 (1 day)Maximum user session duration in seconds
maxAuthSessionAgenumber300 (5 minutes)Maximum OAuth flow/auth session duration in seconds
cookie{ sameSite?: true | false | 'lax' | 'strict' | 'none'; secure?: boolean }{ sameSite: 'lax', secure: true in production }Additional cookie setting overrides for sameSite and secure. secure is resolved at runtime from NODE_ENV unless set explicitly. The temporary auth session cookie is __Host-oidc with Secure and SameSite=None; an explicit secure: false makes it oidc without both. sameSite applies only to the user session cookie.

Provider session configuration

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

beta.13+ An option a provider does not set uses the global value. Where neither sets it, the provider preset applies, for example the expirationThreshold of 240 seconds for Keycloak and Cognito or 1800 seconds for Entra ID, Microsoft and Zitadel.

OptionTypeDefaultDescription
cookieNamestring'nuxt-oidc-auth'Cookie name used for the user session for this provider
automaticRefreshbooleanInherits global valueAutomatically refresh access token and session if refresh token is available (indicated by canRefresh property on user object)
expirationCheckbooleanInherits global valueCheck if session is expired based on access token exp
expirationThresholdnumberInherits global valueAmount of seconds before access token expiration to trigger automatic refresh
missingPersistentSession'clear' | 'warn' | 'silent''clear'Overrides global behavior for missing persistent session entries
maxAuthSessionAgenumberInherits global valueMaximum OAuth flow/auth session duration in seconds for this provider
singleSignOutbooleanfalseEnable cross-tab/browser single sign-out support
singleSignOutIdField'sub' | 'aud''sub'Token field used to derive the single sign-out session id

Middleware configuration (middleware)

OptionTypeDefaultDescription
globalMiddlewareEnabledbooleantrueRuns the auth middleware on every page. Set to false to protect selected pages with definePageMeta({ middleware: 'oidc-auth' })
redirectbooleantrueEnables/disables automatic redirect to login when user is unauthenticated. Runtime override: NUXT_OIDC_MIDDLEWARE_REDIRECT
customLoginPagebooleanfalseEnables/disables automatic registration of /auth/login route rule
customLogoutPagebooleanfalseEnables/disables automatic registration of /auth/logout route rule

Dev Mode configuration (devMode)

For more details, please check the dev mode docs page

OptionTypeDefaultDescription
enabledbooleanfalseEnables/disables the dev mode. Dev mode is only available when running the dev server and is stripped from production builds.
userNamestring'Nuxt OIDC Auth Dev'Sets the userName field on the user object
userInfoRecord<string, unknown>undefinedSets the userInfo field on the user object
tokenAlgorithm'symmetric' | 'asymmetric''asymmetric'Sets the key algorithm for signing generated JWT tokens
idTokenstringundefinedSets the idToken field on the user object
accessTokenstringundefinedSets the accessToken field on the user object
claimsRecord<string, string>undefinedSets the claims field on the user object and generated JWT token if generateAccessToken is set to true
generateAccessTokenbooleanfalseIf set, generates a JWT token for the accessToken field based on the given user information
issuerstring'nuxt:oidc:auth:issuer'Only used with generateAccessToken. Sets the issuer field on the generated JWT token
audiencestring'nuxt:oidc:auth:audience'Only used with generateAccessToken. Sets the audience field on the generated JWT token
subjectstring'nuxt:oidc:auth:subject'Only used with generateAccessToken. Sets the subject field on the generated JWT token

Example configuration

nuxt.config.ts
  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: '',
      },
      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',
    },
  },