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)

Option	Type	Default	Description
enabled	`boolean`	`true`	Enables/disables the module
defaultProvider	`string`	`undefined`	Sets the default provider. Enables automatic registration of generic `/auth/login` and `/auth/logout` route rules
providers	`<provider>`	`{}`	Configuration entries for each configured provider. For provider specific config see Provider specific configurations
session	`AuthSessionConfig`	Global session configuration	Optional session specific configuration
middleware	`MiddlewareConfig`	Middleware configuration	Optional middleware specific configuration
devMode	`DevModeConfig`	Dev Mode configuration	Configuration for local dev mode
provideDefaultSecrets	`boolean`	`true`	Provide defaults for NUXT_OIDC_SESSION_SECRET, NUXT_OIDC_TOKEN_KEY and NUXT_OIDC_AUTH_SESSION_SECRET using a Nitro plugin. Turning this off can lead to the app not working if no secrets are provided

Provider Configuration (provider)

<provider>

Option	Type	Default	Description
clientId	`string`	''	Client ID
clientSecret	`string`	''	Client Secret
responseType	`'code'` \| `'code token'` \| `'code id_token'` \| `'id_token token'` \| `'code id_token token'` (optional)	`code`	Response Type
authenticationScheme	`'header'` \| `'body'` (optional)	`header`	Authentication scheme
responseMode	`'query'` \| `'fragment'` \| `'form_post'` \| `string` (optional)	-	Response mode for authentication request
authorizationUrl	`string` (optional)	''	Authorization endpoint URL
tokenUrl	`string` (optional)	''	Token endpoint URL
userInfoUrl	`string` (optional)	''	Userinfo endpoint URL
redirectUri	`string` (optional)	''	Redirect URI
grantType	`'authorization_code'` \| 'refresh_token' (optional)	`authorization_code`	Grant Type
scope	`string[]` (optional)	`['openid']`	Scope
pkce	`boolean` (optional)	`false`	Use PKCE (Proof Key for Code Exchange)
state	`boolean` (optional)	`true`	Use state parameter with a random value. If state is not used, the nonce parameter is used to identify the flow.
nonce	`boolean` (optional)	false	Use nonce parameter with a random value.
userNameClaim	`string` (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.
optionalClaims	`string[]` (optional)	`undefined`	Claims to be extracted from the id token
logoutUrl	`string` (optional)	''	Logout endpoint URL
scopeInTokenRequest	`boolean` (optional)	false	Include scope in token request
tokenRequestType	`'form'` \| `'form-urlencoded'` \| `'json'` (optional)	`'form'`	Token request type
audience	`string` (optional)	-	Audience used for token validation (not included in requests by default, use additionalTokenParameters or additionalAuthParameters to add it)
requiredProperties	`string[]`	`['clientId', 'redirectUri', 'clientSecret', 'authorizationUrl', 'tokenUrl']`	Required properties of the configuration that will be validated at runtime.
filterUserInfo	`string[]`(optional)	`undefined`	Filter userinfo response to only include these properties.
skipAccessTokenParsing	`boolean` (optional)	`false`	Skip access token parsing (for providers that don't follow the OIDC spec/don't issue JWT access tokens).
logoutRedirectParameterName	`string` (optional)	''	Query parameter name for logout redirect. Will be appended to the logoutUrl as a query parameter.
additionalAuthParameters	`Record<string, string>` (optional)	`undefined`	Additional parameters to be added to the authorization request. See Provider specific configurations for possible parameters.
additionalTokenParameters	`Record<string, string>` (optional)	`undefined`	Additional parameters to be added to the token request. See Provider specific configurations for possible parameters.
baseUrl	`string` (optional)	''	Provider Only. Base URL for the provider, used when to dynamically create authorizationUrl, tokenUrl, userInfoUrl and logoutUrl if possible.
openIdConfiguration	`string` or `Record<string, unknown>` or `function (config) => Record<string, unknown>` (optional)	`undefined`	OpenID Configuration url, object or function promise that resolves to an OpenID Configuration object.
validateAccessToken	`boolean` (optional)	`true`	Validate access token.
validateIdToken	`boolean` (optional)	`true`	Validate id token.
encodeRedirectUri	`boolean` (optional)	`false`	Encode redirect uri query parameter in authorization request. Only for compatibility with services that don't implement proper parsing of query parameters.
exposeAccessToken	`boolean` (optional)	`false`	Expose access token to the client within session object
exposeIdToken	`boolean` (optional)	`false`	Expose raw id token to the client within session object
callbackRedirectUrl	`string` (optional)	`/`	Set a custom redirect url to redirect to after a successful callback
allowedClientAuthParameters	`string[]` (optional)	`[]`	List of allowed client-side user-added query parameters for the auth request
sessionConfiguration	`ProviderSessionConfig` (optional)	`{}`	Session configuration overrides, see session

Global session configuration (session)

The following options are available for the global session configuration.

Option	Type	Default	Description
automaticRefresh	`boolean`	`true`	Automatically refresh access token and session if refresh token is available (indicated by `canRefresh` property on user object)
expirationCheck	`boolean`	`true`	Check if session is expired based on access token exp
expirationThreshold	`number`	`0`	Amount of seconds before access token expiration to trigger automatic refresh
maxAge	`number`	`60 * 60 * 24` (1 day)	Maximum auth session duration in seconds
cookie	``	``	Additional cookie setting overrides for `sameSite` and `secure`

Provider session configuration

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

Option	Type	Default	Description
automaticRefresh	`boolean`	`true`	Check if session is expired based on access token exp
expirationCheck	`boolean`	`true`	Automatically refresh access token and session if refresh token is available (indicated by `canRefresh` property on user object)
expirationThreshold	`number`	`0`	Amount of seconds before access token expiration to trigger automatic refresh

Middleware configuration (middleware)

Option	Type	Default	Description
globalMiddlewareEnabled	`boolean`	-	Enables/disables the global middleware
customLoginPage	`boolean`	-	Enables/disables automatic registration of `/auth/login` and `/auth/logout` route rules

Dev Mode configuration (devMode)

For more details, please check the dev mode docs page

Option	Type	Default	Description
enabled	`boolean`	`false`	Enables/disables the dev mode. Dev mode can only be enabled when the app runs in a non production environment.
userName	`string`	'Nuxt OIDC Auth Dev'	Sets the `userName` field on the user object
userInfo	`Record<string, unknown>`	`{}`	Sets the `userInfo` field on the user object
tokenAlgorithm	'symmetric'	'asymmetric'	'symmetric'
idToken	`string`	``	Sets the `idToken` field on the user object
accessToken	`string`	``	Sets the `accessToken` field on the user object
claims	`Record<string, string>`	``	Sets the claims field on the user object and generated JWT token if `generateAccessToken` is set to `true`.
generateAccessToken	`string`	`false`	If set generates a JWT token for the access_token field based on the given user information
issuer	`boolean`	'nuxt:oidc:auth:issuer'	Only used with `generateAccessToken`. Sets the issuer field on the generated JWT token.
audience	`string`	'nuxt:oidc:auth:audience'	Only used with `generateAccessToken`. Sets the audience field on the generated JWT token.
subject	`string`	'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: '',
        exposeIdToken: true,
      },
      zitadel: {
        clientId: '',
        clientSecret: '', // Works with PKCE and Code flow, just leave empty for PKCE
        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', // Set this to 'header' if Code is used instead of PKCE
      },
    },
    session: {
      expirationCheck: true,
      automaticRefresh: true,
      expirationThreshold: 3600,
    },
    middleware: {
      globalMiddlewareEnabled: true,
      customLoginPage: true,
    },
    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',
    },
  },

Hooks

Nuxt hooks to interact with nuxt-oidc-auth

Contributing

How to contribute to nuxt-oidc-auth