Nuxt OIDC Auth

Welcome to Nuxt OIDC Auth, a Nuxt module focusing on native OIDC (OpenID Connect) based authentication for Nuxt with a high level of customizability and security for SSR applications. This module doesn't use any external dependencies outside of the unjs ecosystem except for token validation (the well known and tested jose library for JWT interactions). This module's session implementation is based on nuxt-auth-utils.

• Nuxt OIDC Auth
  • Features
    • Recent breaking changes
    • Security information
  • Installation
    • Add nuxt-oidc-auth dependency to your project
    • Set secrets
  • Authentication Provider Presets
    • Provider specific configurations
    • Auth0
    • AWS Cognito
    • Entra ID/Microsoft
    • GitHub
    • Keycloak
    • Zitadel
  • Vue Composable
    • loggedIn => boolean
    • loginprovider?: ProviderKeys | 'dev', params?: Record<string, string> => Promise
    • user => object
    • currentProvider => string
    • fetch => void
    • refresh => void
    • logoutprovider: string => Promise
    • User object
  • Server Utils
    • Middleware
    • Session expiration and refresh
    • OIDC Event Handlers
    • Using the session in server side code
    • Hooks
      • Example
  • Configuration reference
    • oidc
      • providers
      • session
      • middleware
  • Dev mode
    • Enabling
    • Token generation
  • Contributing
  • ⚠️ Disclaimer

Features

🔒  Secured & sealed cookies sessions
📝  Generic spec compliant OpenID connect provider with fully configurable OIDC flow (state, nonce, PKCE, token request, ...)
⚙️  Presets for popular OIDC providers
🗂️  Multi provider support with auto registered routes (/auth/<provider>/login, /auth/<provider>/logout, /auth/<provider>/callback)
👤  useOidcAuth composable for getting the user information, logging in and out, refetching the current session and triggering a token refresh
💾  Encrypted server side refresh/access token storage powered by unstorage
📤  Optional global middleware with automatic redirection to default provider or a custom login page (see playground)
🔑  Optional token validation
🕙  Optional session expiration check based on token expiration
↩️  Optional automatic session renewal when token is expired

If you are looking for a module that supports local authentication (and more) provided by your Nuxt server, check out the nuxt-auth module from sidebase (powered by authjs and NextAuth) ➡️ nuxt-auth

Recent breaking changes

⚠️ Since 0.16.0, the data from the providers userInfo endpoint is written into userInfo on the user object instead of providerInfo. Please adjust your nuxt.config.ts and .env/environment files and configurations accordingly. If you are using the user object from the useOidcAuth composable change the access to providerInfo to userInfo.

Security information

This module only implements the Authorization Code Flow and optionally the Hybrid Flow in a confidential client scenario as detailed in the OpenID Connect specification. We will not support the Implicit Flow in the future, as it should not be used anymore and was practically superseded by the Authorization Code Flow. We will also not support the Client Credential Flow, as it is not part of OIDC, but of OAuth2 and is correctly named Client Credentials Grant. It is basically just an exchange of credentials for a token, is not meant for user authentication and can easily be implemented using a simple fetch request.

This module only works with SSR (server-side rendering) enabled as it uses server API routes. You cannot use this module with nuxt generate.

Installation

Add nuxt-oidc-auth dependency to your project

With nuxi

pnpm dlx nuxi@latest module add nuxt-oidc-auth

or manually

pnpm add -D nuxt-oidc-auth

Add nuxt-oidc-auth to the modules section of nuxt.config.ts

export default defineNuxtConfig({
  modules: [
    'nuxt-oidc-auth'
  ]
})

Set secrets

Nuxt OIDC Auth uses three different secrets to encrypt the user session, the individual auth sessions and the persistent server side token store. You can set them using environment variables or in the .env file. All of the secrets are auto generated if not set, but should be set manually in production. This is especially important for the session storage, as it won't be accessible anymore if the secret changes, for example, after a server restart.

If you need a reference how you could generate random secrets or keys, we created an example as a starting point: Secrets generation example

• NUXT_OIDC_TOKEN_KEY (random key): This needs to be a random cryptographic AES key in base64. Used to encrypt the server side token store. You can generate a key in JS with await subtle.exportKey('raw', await subtle.generateKey({ name: 'AES-GCM', length: 256, }, true, ['encrypt', 'decrypt'])). You just have to encode it to base64 afterwards.
• NUXT_OIDC_SESSION_SECRET (random string): This should be a at least 48 characters random string. It is used to encrypt the user session.
• NUXT_OIDC_AUTH_SESSION_SECRET (random string): This should be a at least 48 characters random string. It is used to encrypt the individual sessions during OAuth flows.

Add a NUXT_OIDC_SESSION_SECRET env variable with at least 48 characters in the .env file.

# .env
NUXT_OIDC_TOKEN_KEY=base64_encoded_key
NUXT_OIDC_SESSION_SECRET=48_characters_random_string
NUXT_OIDC_AUTH_SESSION_SECRET=48_characters_random_string

✨ That's it! You can now add authentication with a predifined provider or a custom OIDC provider to your Nuxt app ✨

Authentication Provider Presets

Nuxt OIDC Auth includes presets for the following providers with tested default values:

• Auth0
• AWS Cognito
• Entra ID/Microsoft
• GitHub
• Keycloak
• Zitadel
• Generic OIDC

Provider specific configurations

Some providers have specific additional fields that can be used to extend the authorization, logout or token request. These fields are available via. additionalAuthParameters, additionalLogoutParameters or additionalTokenParameters in the provider configuration.

⚠️ Tokens will only be validated if the clientId or the optional audience field is part of the access_tokens (or id_token if existent) audiences. Even if validateAccessToken or validateIdToken is set, if the audience doesn't match, the token should not and will not be validated. Some providers like Entra or Zitadel don't or just in certain cases provide a parsable JWT access token. Validation will fail for these and should be disable, even if the audience is set.

The redirectUri property is always required and should always point to the callback uri of the specific provider. For Auth0 it should look like this https://YOURDOMAIN/auth/auth0/callback. The playgrounds nuxt.config.ts has examples for multiple providers.

If there is no preset for your provider, you can add a generic OpenID Connect provider by using the oidc provider key in the configuration. Remember to set the required fields and expect your provider to behave slightly different than defined in the OAuth and OIDC specifications. For security reasons, you should avoid writing the client secret directly in the nuxt.config.ts file. You can use environment variables to inject settings into the runtime config. Check the .env.example file in the playground folder for reference.

Also consider creating an issue to request additional providers being added.

# OIDC MODULE CONFIG
NUXT_OIDC_TOKEN_KEY=
NUXT_OIDC_SESSION_SECRET=
NUXT_OIDC_AUTH_SESSION_SECRET=
# AUTH0 PROVIDER CONFIG
NUXT_OIDC_PROVIDERS_AUTH0_CLIENT_SECRET=
NUXT_OIDC_PROVIDERS_AUTH0_CLIENT_ID=
NUXT_OIDC_PROVIDERS_AUTH0_BASE_URL=
# KEYCLOAK PROVIDER CONFIG
NUXT_OIDC_PROVIDERS_KEYCLOAK_CLIENT_SECRET=
NUXT_OIDC_PROVIDERS_KEYCLOAK_CLIENT_ID=
NUXT_OIDC_PROVIDERS_KEYCLOAK_BASE_URL=
...

Auth0

Provider support:

✅  PKCE
❌  Nonce
✅  State
✅  Access Token validation
❌  ID Token validation

Instructions

Additional parameters to be used in additionalAuthParameters, additionalTokenParameters or additionalLogoutParameters:

Depending on the settings of your apps Credentials tab, set authenticationScheme to body for 'Client Secret (Post)', set to header for 'Client Secret (Basic)', set to '' for 'None'

AWS Cognito

Provider support:

✅  PKCE
✅  Nonce
✅  State
❌  Access Token validation
❌  ID Token validation

AWS Congito doesn't correctly implement the OAuth 2 standard and doesn't provide a aud field for the audience. Therefore it is not possible to verify the access or id token.

Instructions

For AWS Cognito you have to provide at least the baseUrl, clientId, clientSecret and logoutRedirectUri properties. The baseUrl is used to dynamically create the authorizationUrl, tokenUrl, logoutUrl and userInfoUrl. The only supported OAuth grant type is Authorization code grant. The final url should look something like this https://cognito-idp.eu-north-1.amazonaws.com/eu-north-1_SOMEID/.well-known/openid-configuration. You will also encounter an error, if you have not correctly registered the redirectUri under "Allowed callback URLs" or the logoutRedirectUri under "Allowed sign-out URLs". If you need additional scopes, specify them in the scope property in you nuxt config like scope: ['openid', 'email', 'profile'],.

Entra ID/Microsoft

Provider support:

✅  PKCE
✅  Nonce
✅  State
⚠️  Access Token validation (Supported, but disabled as only possible for custom audience tokens)
✅  ID Token validation

Instructions

Additional parameters to be used in additionalAuthParameters, additionalTokenParameters or additionalLogoutParameters:

If you want to validate access tokens from Microsoft Entra ID (previously Azure AD), you need to make sure that the scope includes your own API. You have to register an API first and expose some scopes to your App Registration that you want to request. If you only have GraphAPI entries like openid, mail GraphAPI specific ones in your scope, the returned access token cannot and should not be verified. If the scope is set correctly, you can set validateAccessToken option to true.

If you use this module with Entra External ID (previously Entra ID for Customers) make sure you have set the audience config field to your application id, otherwise it will not be possible to get a valid OpenID Connect well-known configuration and thereby verify the JWT token.

GitHub

Provider support:

❌  PKCE
❌  Nonce
✅  State
❌  Access Token validation
❌  ID Token validation

Instructions

GitHub is not strictly an OIDC provider, but it can be used as one. Make sure that validation is disabled and that you keep the skipAccessTokenParsing option to true.

Try to use a GitHub App, not the legacy OAuth app. They don't provide the same level of security, have no granular permissions, don't provide refresh tokens and are not tested.

Make sure to set the callback URL in your OAuth app settings as <your-domain>/auth/github.

Keycloak

Provider support:

✅  PKCE
✅  Nonce
❌  State
✅  Access Token validation
❌  ID Token validation

Instructions

Additional parameters to be used in additionalAuthParameters, additionalTokenParameters or additionalLogoutParameters:

For more information on these parameters, check the KeyCloak documentation.

For Keycloak you have to provide at least the baseUrl, clientId and clientSecret properties. The baseUrl is used to dynamically create the authorizationUrl, tokenUrl, logoutUrl and userInfoUrl. Please include the realm you want to use in the baseUrl (e.g. https://<keycloak-url>/realms/<realm>). If you don't want to use the post logout redirect feature of key cloak, set logoutUrl to undefined or ''. Also remember to enable Client authentication to be able to get a client secret.

Zitadel

Provider support:

✅  PKCE
✅  Nonce
❌  State
✅  Access Token validation
❌  ID Token validation

Instructions

For Zitadel you have to provide at least the baseUrl, clientId and clientSecret properties. The baseUrl is used to dynamically create the authorizationUrl, tokenUrl, logoutUrl and userInfoUrl. The provider supports PKCE and Code authentication schemes. For PKCE just leave the clientSecret set to an empty string ('').

Example configuration

zitadel: {
  clientId: '',
  clientSecret: '', // Works with PKCE and Code flow, just leave empty for PKCE
  redirectUri: 'http://localhost:3000/auth/zitadel/callback', // Replace with your domain
  baseUrl: '', // For example https://PROJECT.REGION.zitadel.cloud
  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
},

Vue Composable

Nuxt OIDC Auth automatically adds some API routes to interact with the current user session and adds the useOidcAuth composable, which provides the following refs and methods to access the session from your Vue components:

• loggedIn
• user
• currentProvider
• fetch
• refresh
• login
• logout

loggedIn => (boolean)

Indicates whether the user is currently logged in.

Example usage:

const { loggedIn } = useOidcAuth()

if (loggedIn.value) {
  console.log('User is logged in')
}
else {
  console.log('User is not logged in')
}

login(provider?: ProviderKeys | 'dev', params?: Record<string, string>) => (Promise)

Initiates the login process.

Parameters

Example usage:

<script setup>
const { loggedIn, user, login, logout } = useOidcAuth()
</script>

<template>
  <div v-if="loggedIn">
    <h1>Welcome {{ user.userName }}!</h1>
    <p>Logged in since {{ user.loggedInAt }}</p>
    <button @click="logout()">
      Logout
    </button>
  </div>
  <div v-else>
    <h1>Not logged in</h1>
    <a href="/auth/github/login">Login with GitHub</a>
    <button @click="login()">
      Login with default provider
    </button>
  </div>
</template>

user => (object)

The current user object.

currentProvider => (string)

The name of the currently logged in provider.

fetch() => (void)

Fetches/updates the current user session.

refresh() => (void)

Refreshes the current user session against the used provider to get a new access token. Only available if the current provider issued a refresh token (indicated by canRefresh property in the user object).

logout(provider: string) => (Promise)

Handles the logout process. Always provide the optional provider parameter if you haven't set a default provider. You can get the current provider from the currentProvider property.

Example usage:

<script setup>
const { logout } = useOidcAuth()
</script>

<template>
  <button @click="logout()">
    Logout
  </button>
</template>

Example usage with no default provider configured or middleware customLoginPage set to true:

<script setup>
const { logout, currentProvider } = useOidcAuth()
</script>

<template>
  <button @click="logout(currentProvider)">
    Logout
  </button>
</template>

User object

The user object provided by useOidcAuth contains the following properties:

You can extend the type for your provider info by creating a type declaration file (for example, auth.d.ts) in your project:

declare module '#oidc-auth' {
  interface UserInfo {
    // define the type here e.g.,
    providerName: string
  }
}

Server Utils

The following helpers are auto-imported in your server/ directory.

Middleware

This module can automatically add a global middleware to your Nuxt server. You can enable it by setting globalMiddlewareEnabled under the middleware section of the config. The middleware automatically redirects all requests to /auth/login if the user is not logged in. You can disable this behavior by setting redirect to false in the middleware configuration. The /auth/login route is only configured if you have defined a default provider. If you want to use a custom login page and keep your default provider or don't want to set a default provider at all, you can set customLoginPage to true in the middleware configuration.

If you set customLoginPage to true, you have to manually add a login page to your Nuxt app under /auth/login. You can use the login method from the useOidcAuth composable to redirect the user to the respective provider login page. Setting customLoginPage to true will also disable the /auth/logout route. You have to manually add a logout page to your Nuxt app under /auth/logout and use the logout method from the useOidcAuth composable to logout the user or make sure that you always provide the optional provider parameter to the logout method.

<script setup>
const { logout, currentProvider } = useOidcAuth()
</script>

<template>
  <button @click="logout(currentProvider)">
    Logout
  </button>
</template>

⚠️ Everything under the /auth path is not protected by the global middleware. Make sure to not use this path for any other purpose than authentication.

Session expiration and refresh

Nuxt OIDC Auth automatically checks if the session is expired and refreshes it if necessary. You can disable this behavior by setting expirationCheck and automaticRefresh to false in the session configuration. The session is automatically refreshed when the session object is accessed. You can also manually refresh the session using refresh from useOidcAuth on the client or on the server side by calling refreshUserSession(event).

Session expiration and refresh is handled completely server side, the exposed properties in the user session are automatically updated. You can theoretically register a hook that overwrites session fields like loggedInAt, but this is not recommended and will be overwritten with each refresh.

OIDC Event Handlers

All configured providers automatically register the following server routes.

• /auth/<provider>/callback
• /auth/<provider>/login
• /auth/<provider>/logout

In addition, if defaultProvider is set, the following route rules are registered as forwards to the default provider.

• /auth/login
• /auth/logout

Using the session in server side code

You can access the user session in your server side code by using the getUserSession function from the @nuxtjs/oidc-auth module.

import { getUserSession } from "nuxt-oidc-auth/runtime/server/utils/session.mjs"

export default eventHandler(async (event) => {
  const session = await getUserSession(event)
  return session.userName
})

Be careful to not expose any sensitive information from the handler code.

Hooks

The following hooks are available to extend the default behavior of the OIDC module:

• fetch (Called when a user session is fetched)
• clear (Called before a user session is cleared)
• refresh (Called before a user session is refreshed)

⚠️ Remember to also update the refresh hook if you modify the session, as claims and other fields would otherwise be wiped.

Example

export default defineNitroPlugin(() => {
  sessionHooks.hook('fetch', async (session) => {
    // Extend User Session
    // Or throw createError({ ... }) if session is invalid
    // session.extended = {
    //   fromHooks: true
    // }
    console.log('Injecting "status" claim as test')
    if (!(Object.keys(session).length === 0)) {
      const claimToAdd = { status: 'Fetch' }
      session.claims = { ...session.claims, ...claimToAdd }
    }
  })

  sessionHooks.hook('refresh', async (session) => {
    console.log('Injecting "status" claim as test on refresh')
    if (!(Object.keys(session).length === 0)) {
      const claimToAdd = { status: 'Refresh' }
      session.claims = { ...session.claims, ...claimToAdd }
    }
  })

  sessionHooks.hook('clear', async (session) => {
    // Log that user logged out
    console.log('User logged out')
  })
})

You can theoretically register a hook that overwrites internal session fields like loggedInAt, but this is not recommended as it has an impact on the loggedIn state of your session. It will not impact the server side refresh and expiration logic, but will be overwritten with each refresh.

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

oidc

providers

<provider>

session

The following options are available for the global session configuration.

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

middleware

Dev mode

Since 0.10.0, there is a local dev mode available. It can only be enabled if the NODE_ENV environment variable is not set to prod/production AND dev mode is explicitly enabled in the config. The dev mode is for local and offline development and returns a static user object that can be configured in the config or by variables in .env. The following fields in the returned user object can be configured:

• claims: devMode.claims setting
• provider: devMode.provider 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

To enable the dev mode, you have to make sure at least the following settings are set:

• session -> expirationCheck needs to be turned off (false)
• devMode -> enabled set to true in the oidc part of your nuxt.config.ts

Token generation

If needed, the dev mode can generate a valid signed access token if the settting 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: devMode.audience setting, default nuxt:oidc:auth:audience
• sub: devMode.subject setting, default nuxt:oidc:auth:subject
• exp: current DateTime + 24h

⚠️ The access token will be generated with a fixed local secret and can in no way be considered secure. Dev mode can only be enabled in local development and should exclusively be used there for testing purposes. Never set any environment variables on your production systems that could put any component into development mode.

Contributing

# Install dependencies
pnpm install

# Generate type stubs
pnpm run dev:prepare

# Develop with the playground
pnpm run dev

# Build the playground
pnpm run dev:build

# Run ESLint
pnpm run lint

⚠️ Disclaimer

This module is still in development, feedback and contributions are welcome! Use at your own risk.