Add Authentication to Nuxt applications with secured & sealed cookies sessions.
- Hybrid Rendering support (SSR / CSR / SWR / Prerendering)
- 15+ OAuth Providers
- Vue composable
- Server utils
<AuthState>
component- Extendable with hooks
It has few dependencies (only from UnJS), run on multiple JS environments (Node, Deno, Workers) and is fully typed with TypeScript.
This module only works with a Nuxt server running as it uses server API routes (nuxt build
).
This means that you cannot use this module with nuxt generate
.
You can anyway use Hybrid Rendering to pre-render pages of your application or disable server-side rendering completely.
- Add
nuxt-auth-utils
in your Nuxt project
npx nuxi@latest module add auth-utils
- Add a
NUXT_SESSION_PASSWORD
env variable with at least 32 characters in the.env
.
# .env
NUXT_SESSION_PASSWORD=password-with-at-least-32-characters
Nuxt Auth Utils generates one for you when running Nuxt in development the first time if no NUXT_SESSION_PASSWORD
is set.
- That's it! You can now add authentication to your Nuxt app โจ
Nuxt Auth Utils automatically adds some plugins to fetch the current user session to let you access it from your Vue components.
<script setup>
const { loggedIn, user, session, fetch, clear } = useUserSession()
</script>
<template>
<div v-if="loggedIn">
<h1>Welcome {{ user.login }}!</h1>
<p>Logged in since {{ session.loggedInAt }}</p>
<button @click="clear">Logout</button>
</div>
<div v-else>
<h1>Not logged in</h1>
<a href="/auth/github">Login with GitHub</a>
</div>
</template>
TypeScript Signature:
interface UserSessionComposable {
/**
* Computed indicating if the auth session is ready
*/
ready: ComputedRef<boolean>
/**
* Computed indicating if the user is logged in.
*/
loggedIn: ComputedRef<boolean>
/**
* The user object if logged in, null otherwise.
*/
user: ComputedRef<User | null>
/**
* The session object.
*/
session: Ref<UserSession>
/**
* Fetch the user session from the server.
*/
fetch: () => Promise<void>
/**
* Clear the user session and remove the session cookie.
*/
clear: () => Promise<void>
}
The following helpers are auto-imported in your server/
directory.
// Set a user session, note that this data is encrypted in the cookie but can be decrypted with an API call
// Only store the data that allow you to recognize a user, but do not store sensitive data
// Merges new data with existing data using defu()
await setUserSession(event, {
user: {
// ... user data
},
loggedInAt: new Date()
// Any extra fields
})
// Replace a user session. Same behaviour as setUserSession, except it does not merge data with existing data
await replaceUserSession(event, data)
// Get the current user session
const session = await getUserSession(event)
// Clear the current user session
await clearUserSession(event)
// Require a user session (send back 401 if no `user` key in session)
const session = await requireUserSession(event)
You can define the type for your user session by creating a type declaration file (for example, auth.d.ts
) in your project to augment the UserSession
type:
// auth.d.ts
declare module '#auth-utils' {
interface User {
// Add your own fields
}
interface UserSession {
// Add your own fields
}
}
export {}
All handlers can be auto-imported and used in your server routes or API routes.
The pattern is oauth<Provider>EventHandler({ onSuccess, config?, onError? })
, example: oauthGitHubEventHandler
.
The helper returns an event handler that automatically redirects to the provider authorization page and then calls onSuccess
or onError
depending on the result.
The config
can be defined directly from the runtimeConfig
in your nuxt.config.ts
:
export default defineNuxtConfig({
runtimeConfig: {
oauth: {
// provider in lowercase (github, google, etc.)
<provider>: {
clientId: '...',
clientSecret: '...'
}
}
}
})
It can also be set using environment variables:
NUXT_OAUTH_<PROVIDER>_CLIENT_ID
NUXT_OAUTH_<PROVIDER>_CLIENT_SECRET
Provider is in uppercase (GITHUB, GOOGLE, etc.)
- Auth0
- AWS Cognito
- Battle.net
- Discord
- GitHub
- Keycloak
- Microsoft
- PayPal
- Spotify
- Steam
- Twitch
- X (Twitter)
- XSUAA
- Yandex
You can add your favorite provider by creating a new file in src/runtime/server/lib/oauth/.
Example: ~/server/routes/auth/github.get.ts
export default oauthGitHubEventHandler({
config: {
emailRequired: true
},
async onSuccess(event, { user, tokens }) {
await setUserSession(event, {
user: {
githubId: user.id
}
})
return sendRedirect(event, '/')
},
// Optional, will return a json error and 401 status code by default
onError(event, error) {
console.error('GitHub OAuth error:', error)
return sendRedirect(event, '/')
},
})
Make sure to set the callback URL in your OAuth app settings as <your-domain>/auth/github
.
We leverage hooks to let you extend the session data with your own data or log when the user clears the session.
// server/plugins/session.ts
export default defineNitroPlugin(() => {
// Called when the session is fetched during SSR for the Vue composable (/api/_auth/session)
// Or when we call useUserSession().fetch()
sessionHooks.hook('fetch', async (session, event) => {
// extend User Session by calling your database
// or
// throw createError({ ... }) if session is invalid for example
})
// Called when we call useServerSession().clear() or clearUserSession(event)
sessionHooks.hook('clear', async (session, event) => {
// Log that user logged out
})
})
You can make authenticated requests both from the client and the server. However, you must use useRequestFetch()
to make authenticated requests during SSR if you are not using useFetch()
<script setup lang="ts">
// When using useAsyncData
const { data } = await useAsyncData('team', () => useRequestFetch()('/api/protected-endpoint'))
// useFetch will automatically use useRequestFetch during SSR
const { data } = await useFetch('/api/protected-endpoint')
</script>
There's an open issue to include credentials in
$fetch
in Nuxt.
When using Nuxt routeRules
to prerender or cache your pages, Nuxt Auth Utils will not fetch the user session during prerendering but instead fetch it on the client-side (after hydration).
This is because the user session is stored in a secure cookie and cannot be accessed during prerendering.
This means that you should not rely on the user session during prerendering.
You can use the <AuthState>
component to safely display auth-related data in your components without worrying about the rendering mode.
One common use case if the Login button in the header:
<template>
<header>
<AuthState v-slot="{ loggedIn, clear }">
<button v-if="loggedIn" @click="clear">Logout</button>
<NuxtLink v-else to="/login">Login</NuxtLink>
</AuthState>
</header>
</template>
If the page is cached or prerendered, nothing will be rendered until the user session is fetched on the client-side.
You can use the placeholder
slot to show a placeholder on server-side and while the user session is being fetched on client-side for the prerendered pages:
<template>
<header>
<AuthState>
<template #default="{ loggedIn, clear }">
<button v-if="loggedIn" @click="clear">Logout</button>
<NuxtLink v-else to="/login">Login</NuxtLink>
</template>
<template #placeholder>
<button disabled>Loading...</button>
</template>
</AuthState>
</header>
</template>
If you are caching your routes with routeRules
, please make sure to use Nitro >= 2.9.7
to support the client-side fetching of the user session.
We leverage runtimeConfig.session
to give the defaults option to h3 useSession
.
You can overwrite the options in your nuxt.config.ts
:
export default defineNuxtConfig({
modules: ['nuxt-auth-utils'],
runtimeConfig: {
session: {
maxAge: 60 * 60 * 24 * 7 // 1 week
}
}
})
Our defaults are:
{
name: 'nuxt-session',
password: process.env.NUXT_SESSION_PASSWORD || '',
cookie: {
sameSite: 'lax'
}
}
Checkout the SessionConfig
for all options.
- nuxt-authorization: Authorization module for managing permissions inside a Nuxt app, compatible with
nuxt-auth-utils
# Install dependencies
npm install
# Generate type stubs
npm run dev:prepare
# Develop with the playground
npm run dev
# Build the playground
npm run dev:build
# Run ESLint
npm run lint
# Run Vitest
npm run test
npm run test:watch
# Release new version
npm run release