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
defaultProviderstringundefinedSets 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
sessionAuthSessionConfigGlobal session configurationOptional session specific configuration
middlewareMiddlewareConfigMiddleware configurationOptional middleware specific configuration
devModeDevModeConfigDev Mode configurationConfiguration for local dev mode
provideDefaultSecretsbooleantrueProvide 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>

OptionTypeDefaultDescription
clientIdstring''Client ID
clientSecretstring''Client Secret
responseType'code' | 'code token' | 'code id_token' | 'id_token token' | 'code id_token token' (optional)codeResponse Type
authenticationScheme'header' | 'body' (optional)headerAuthentication scheme
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)falseUse PKCE (Proof Key for Code Exchange)
stateboolean (optional)trueUse state parameter with a random value. If state is not used, the nonce parameter is used to identify the flow.
nonceboolean (optional)falseUse nonce parameter with a random value.
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)undefinedClaims to be extracted from the id token
logoutUrlstring (optional)''Logout endpoint URL
scopeInTokenRequestboolean (optional)falseInclude scope in token request
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 of the configuration that will be validated at runtime.
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.
baseUrlstring (optional)''Provider Only. Base URL for the provider, used when to dynamically create authorizationUrl, tokenUrl, userInfoUrl and logoutUrl if possible.
openIdConfigurationstring or Record<string, unknown> or function (config) => Record<string, unknown> (optional)undefinedOpenID Configuration url, object or function promise that resolves to an OpenID Configuration object.
validateAccessTokenboolean (optional)trueValidate access token.
validateIdTokenboolean (optional)trueValidate id token.
encodeRedirectUriboolean (optional)falseEncode redirect uri query parameter in authorization request. Only for compatibility with services that don't implement proper parsing of query parameters.
exposeAccessTokenboolean (optional)falseExpose access token to the client within session object
exposeIdTokenboolean (optional)falseExpose raw id token to the client within session object
callbackRedirectUrlstring (optional)/Set a custom redirect url to redirect to after a successful callback
allowedClientAuthParametersstring[] (optional)[]List of allowed client-side user-added query parameters for the auth request
sessionConfigurationProviderSessionConfig (optional){}Session configuration overrides, see session

Global session configuration (session)

The following options are available for the global session configuration.

OptionTypeDefaultDescription
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
expirationThresholdnumber0Amount of seconds before access token expiration to trigger automatic refresh
maxAgenumber60 * 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.

OptionTypeDefaultDescription
automaticRefreshbooleantrueCheck if session is expired based on access token exp
expirationCheckbooleantrueAutomatically refresh access token and session if refresh token is available (indicated by canRefresh property on user object)
expirationThresholdnumber0Amount of seconds before access token expiration to trigger automatic refresh

Middleware configuration (middleware)

OptionTypeDefaultDescription
globalMiddlewareEnabledboolean-Enables/disables the global middleware
customLoginPageboolean-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

OptionTypeDefaultDescription
enabledbooleanfalseEnables/disables the dev mode. Dev mode can only be enabled when the app runs in a non production environment.
userNamestring'Nuxt OIDC Auth Dev'Sets the userName field on the user object
userInfoRecord<string, unknown>{}Sets the userInfo field on the user object
tokenAlgorithm'symmetric''asymmetric''symmetric'
idTokenstring``Sets the idToken field on the user object
accessTokenstring``Sets the accessToken field on the user object
claimsRecord<string, string>``Sets the claims field on the user object and generated JWT token if generateAccessToken is set to true.
generateAccessTokenstringfalseIf set generates a JWT token for the access_token field based on the given user information
issuerboolean'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: '',
        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',
    },
  },

Copyright © 2024