Introduction

nuxt-auth is an open source Nuxt module that provides authentication for Nuxt 3 applications.

nuxt-auth supports the following:

• useAuth composable to perform authentication-related actions from the application
• global- and local-application middleware to protect application-pages
• guest-mode to only allows guest to see certain pages (e.g.: the login page)
• authentication-backend setup for the authjs-auth-provider
• static Nuxt 3 apps with the local-auth-provider
• documentation, recipes and example code to get you started

nuxt-auth employs 2 providers to facilitate the act of authenticating a user:

• local: Username and password authentication. local expects the endpoint to return a token that can be used to authenticate subsequent requests
• authjs: A authjs (next-auth) based provider that supports most OAuth- and Magic-URL sign-ins (think Slack or Notion). This provider also supports username and password based sign-in, but discourages from using it

Other libraries / modules would call these authentication-schemes, backends or maybe even strategys.

Which Provider should I pick?

To pick a provider you will first have to take into consideration the requirements of your use-case. Below is a small table to help you pick:

In general one can say that picking:

• authjs is best suited for plug-and-play OAuth for established oauth-providers or magic-url based sign-ins
• local is best when you already have a backend that accepts username + password as a login or want to build a static application

authjs Remarks

The authjs provider is able to provide all of its features by wrapping Auth.js / NextAuth.js under the hood. This gives the reliability & convenience of a >12.000 github star library to the Nuxt 3 ecosystem with a native nuxt developer experience (DX). Wrapping Auth.js / NextAuth.js has the second advantage that many OAuth providers, database adapters, callbacks and more are supported out-of-the-box. This also means that you can use all NextAuth.js and Auth.js guides and documentation to achieve things with the authjs provider of nuxt-auth.

nuxt-auth also provides Nuxt 3 specific features like a convenient application-side composable to login, logout, access user-authentication data or an authentication middleware and plugin that take care of managing the user authentication lifecycle by fetching authentication data on initial load, refreshing the user authentication on re-focusing the tab and more.

In the future a separate OAuth provider for static apps may be added, read the next section for more on this.

Auth.js vs next-auth

We use authjs everywhere to mean authjs and next-auth interchangably as next-auth is currently transitioning to become authjs (branded name: Auth.js), see the announcement here.

We are following this transition and are changing code related to this as it becomes stable enough to use it. You can follow our implementation of this transition in this issue. If you are googling anything related to this provider, we recommend that you still use the term next-auth as this is still the mainly used library and the stable one we mostly use under the hood. New features that are Auth.js only are not guaranteed to work at the moment, as we still mostly rely on next-auth as a stable foundation.

local Remarks

The local provider is based on the local schema of the Nuxt 2 nuxt-auth module. It was added in v0.6.0 of nuxt-auth and serves as a starting point to add further static providers like cookie based authentication, support for refresh tokens and static OAuth support.

The local provider works by receiving an authentication token from the backend it send a username and password to. This could for example be a JWT token. The local provider then stores this token and makes it accessible to you for use. The local provider will also fetch user / session information from the backend once it has successfully logged in.

Any help with this effort is very welcome! Feel free to open an issue or a PR to add support for further providers 💘.

Starting with sidebase

The easiest way to get started with nuxt-auth is using the sidebase Merino stack:

npm create sidebase@latest

pnpm create sidebase@latest

# Note: Due to a known problem with `yarn`, it is not possible to force yarn to always use `@latest`: https://github.com/yarnpkg/yarn/issues/6587yarn create sidebase

This will create a Nuxt 3 project with nuxt-auth already setup & working.

Feature Collection

Authentication providers

• OAuth (e.g., Github, Google, Twitter, Azure, ...)
• Custom OAuth (write it yourself)
• Credentials (password + username)
• Email Magic URLs

Application Side Session Management

• composable const { signIn, signOut, status, data, lastRefreshedAt, ... } = useAuth()
• Auto-refresh the session periodically
• Auto-refresh the session on tab-refocus
• Efficient session fetching: One time on page load, afterwards for specific actions (e.g., on navigation)
• Full typescript support for all methods and properties
• Guest-Mode

Application Protection

• Application-side middleware protection either for the full application or specific pages
• Server-side middleware and endpoint protection

REST API (authjs only)

• GET /signin,
• POST /signin/:provider,
• GET/POST /callback/:provider,
• GET /signout,
• POST /signout,
• GET /session,
• GET /csrf,
• GET /providers