Dev mode

Dev mode

Since 0.10.0, there is a local dev mode available. It can only be enabled when running the Nuxt dev server (nuxt dev) and dev mode is explicitly enabled in config. Production builds (nuxi build/generate) never include the dev auth endpoints, regardless of NODE_ENV; a NODE_ENV starting with prod additionally disables them as defense in depth. 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:

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.

Generated secrets

If NUXT_OIDC_SESSION_SECRET, NUXT_OIDC_TOKEN_KEY or NUXT_OIDC_AUTH_SESSION_SECRET is not set, the module generates a random value (see provideDefaultSecrets in the configuration). The console reports which value was generated and prints only its first five characters to help you recognise it, for example NUXT_OIDC_TOKEN_KEY=AbC12[redacted], in development and production alike.

With dev mode enabled on the dev server (nuxt dev), you can read the generated values in Nuxt DevTools:

1. Open Nuxt DevTools in the browser (Shift + Alt + D) and select the Nuxt OIDC Auth tab.
2. If the tab reports that the DevTools session is not authorized, authorize it with the link or token Nuxt DevTools prints in the terminal.
3. Expand the Secrets section.

The values come from the authenticated Nuxt DevTools RPC. It only answers on the dev server when devMode.enabled is set in config and not turned off at runtime, for example with NUXT_OIDC_DEV_MODE_ENABLED=false. It also refuses to answer while Nuxt DevTools authorization is disabled (devtools.disableAuthorization, the DevTools default on StackBlitz and CodeSandbox). Production builds never include it, even if runtime config sets devMode.enabled: true. Generated values survive server reloads but change when the dev server process restarts, so copy them into .env if you need sessions to survive restarts.

Configuration Options

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.