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)
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',
},
},