Dev mode

Development mode for seamless local development

Dev mode

Since 0.10.0, there is a local dev mode available. It can only be enabled when NODE_ENV does not start with prod, case-insensitively, and dev mode is explicitly enabled in config. The dev mode is for local and offline development and returns a static user object that can be configured in config or by variables in .env.

The following fields in the returned user object can be configured:

claims: devMode.claims setting
userName: devMode.userName setting
userInfo: devMode.userInfo setting
idToken: devMode.idToken setting
accessToken: devMode.accessToken setting

Please refer to user object for required types.

Enabling

Enable dev mode in the oidc section of nuxt.config.ts:

nuxt.config.ts

export default defineNuxtConfig({
  oidc: {
    devMode: {
      enabled: true,
    },
  },
})

Dev sessions bypass provider token-expiration and persistent-token checks, so global session.expirationCheck can keep its default value.

Configuration Options

Option	Type	Default	Description
`enabled`	`boolean`	`false`	Enables/disables dev mode. Ignored when `NODE_ENV` starts with `prod`, case-insensitively.
`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.
`claims`	`Record<string, string>`	-	Sets the claims field on the user object and generated JWT token.
`idToken`	`string`	-	Sets the `idToken` field on the user object.
`accessToken`	`string`	-	Sets the `accessToken` field on the user object (overridden if `generateAccessToken` is `true`).
`generateAccessToken`	`boolean`	`false`	If set, generates a signed JWT token for the `accessToken` field.
`tokenAlgorithm`	`'symmetric' \| 'asymmetric'`	`'asymmetric'`	Algorithm for signing generated tokens. Asymmetric uses RS256, symmetric uses HS256.
`issuer`	`string`	`'nuxt:oidc:auth:issuer'`	Sets the `iss` claim on the generated JWT token.
`audience`	`string`	`'nuxt:oidc:auth:audience'`	Sets the `aud` claim on the generated JWT token.
`subject`	`string`	`'nuxt:oidc:auth:subject'`	Sets the `sub` claim on the generated JWT token.

Token Generation

If needed, the dev mode can generate a valid signed access token if the setting devMode -> generateAccessToken is set to true. This token will be exposed in the user.accessToken property.

The properties on the generated token are:

iat (issued at): current DateTime
iss (issuer): devMode.issuer setting, default nuxt:oidc:auth:issuer
aud (audience): devMode.audience setting, default nuxt:oidc:auth:audience
sub (subject): devMode.subject setting, default nuxt:oidc:auth:subject
exp (expiration): current DateTime + 24h
kid (key ID): included in JWT header when using asymmetric algorithm

Token Algorithm

The tokenAlgorithm option controls how tokens are signed:

asymmetric (default): Uses RS256 algorithm with an RSA key pair. The public key is exposed via the JWKS endpoint, allowing token verification.
symmetric: Uses HS256 algorithm with a random secret. The JWKS endpoint returns an empty keys array since symmetric secrets should not be exposed.

OIDC Discovery Endpoints

When dev mode is enabled with generateAccessToken: true and tokenAlgorithm: 'asymmetric' (the default), the module exposes OIDC-compliant discovery endpoints that allow token verification:

Discovery Endpoint

/auth/dev/.well-known/openid-configuration

Returns a JSON document containing:

{
  "issuer": "nuxt:oidc:auth:issuer",
  "jwks_uri": "http://localhost:3000/auth/dev/.well-known/jwks.json"
}

The issuer value matches your configured devMode.issuer setting.

JWKS Endpoint

/auth/dev/.well-known/jwks.json

Returns the public key in JWKS format for token verification:

{
  "keys": [
    {
      "kty": "RSA",
      "n": "...",
      "e": "AQAB",
      "kid": "dev-...",
      "alg": "RS256",
      "use": "sig"
    }
  ]
}

When tokenAlgorithm is set to symmetric, the endpoint returns { "keys": [] }.

Key Persistence

The RSA key pair used for signing tokens is:

Generated on first use and stored in .nuxt/oidc-dev
Persisted across hot module reloads (HMR)
Regenerated on cold server start (full restart)

This ensures tokens remain verifiable during a development session while preventing key reuse across server restarts.

Dev mode is intended for local development and testing only. The generated keys and tokens should not be considered secure for production use. Never configure dev mode on production systems.

Composable

Use the useOidcAuth composable to interact with authentication state

Single sign-out

Cross tab and browser sign out and server side session invalidation