AuthJS Quickstart

This guide is for setting up @sidebase/nuxt-auth with the AuthJS Provider, which is best suited for plug-and-play OAuth for established oauth-providers or magic-url based sign-ins.

Installation

If you want to use the AuthJS provider, you have to install next-auth. With all package managers except npm you must manually install the peer dependency alongside nuxt-auth:

pnpm

pnpm i next-auth@4.21.1

yarn

yarn add next-auth@4.21.1

WARNING

Due to a breaking change in NextAuth, nuxt-auth is only compatible with NextAuth versions under v4.23.0. We recommend pinning the version to 4.21.1. Read more here.

Configuration

After installing @sidebase/nuxt-auth and next-auth, you can now configure NuxtAuth to use the AuthJS provider. Inside your nuxt.config.ts add the following configuration:

export default defineNuxtConfig({
  modules: ['@sidebase/nuxt-auth'],
  auth: {
    provider: {
      type: 'authjs',
      trustHost: false,
      defaultProvider: 'github',
      addDefaultCallbackUrl: true
    }
  }
})

You can also configure AuthJS specific options inside the nuxt.config.ts, in addition to the main module configurations.

trustHost

• Type: boolean
• Default: false

If set to true, authjs will use either the x-forwarded-host or host headers instead of auth.baseURL. Make sure that reading x-forwarded-host on your hosting platform can be trusted.

WARNING

This is an advanced option. Advanced options are passed the same way as basic options, but may have complex implications or side effects. You should try to avoid using advanced options unless you are very comfortable using them.

defaultProvider

• Type: SupportedProviders
• Default: undefined

Select the default-provider to use when signIn is called. Setting this here will also affect the global middleware behavior. For instance, when you set it to github and the user is unauthorized, they will be directly forwarded to the Github OAuth page instead of seeing the app-login page.

addDefaultCallbackUrl

• Type: boolean | string
• Default: true

Whether to add a callbackUrl to sign in requests. Setting this to a string-value will result in that being used as the callbackUrl path. Setting this to true will result in the blocked original target path being chosen (if it can be determined).

NuxtAuthHandler

As a next step, create your NuxtAuthHandler under ~/server/api/auth/[...].ts. Inside it you can configure the authentication provider you want to use, how the JWT Token is created and managed as well as how your sessions will be composed. The NuxtAuthHander will automatically create all required API endpoints to handle authentication inside your application.

The NuxtAuthHandler is an adaptation of the NextAuthHandler built into AuthJS. Inside the NuxtAuthHandler you can configure:

• OAuth providers: How can users login to your application?
• Adapters: How are sessions saved? (e.g. JWT Token, Database etc.)
• JWT Encryption: How is the JWT Token encrypted and read?
• Callbacks: Hook into the authentication lifecycle hooks.

Begin by creating a new server route file in ~/server/api/auth/[...].ts. You can then begin adding your NuxtAuthHandler. The filename must be [...].ts - this is a so-called "catch-all" route, read more in the Nuxt catch-all docs.

import { NuxtAuthHandler } from '#auth'

export default NuxtAuthHandler({
  // your authentication configuration here!
})

Adding a provider

After creating your NuxtAuthHandler, you can begin by adding a provider. You can find an overview of all the avalible providers here. For this example we will add the GitHub provider.

import GithubProvider from 'next-auth/providers/github'
import { NuxtAuthHandler } from '#auth'

export default NuxtAuthHandler({
  // A secret string you define, to ensure correct encryption
  secret: 'your-secret-here',
  providers: [
    // @ts-expect-error Use .default here for it to work during SSR.
    GithubProvider.default({
      clientId: 'your-client-id',
      clientSecret: 'your-client-secret'
    })
  ]
})

WARNING

After importing your provider from next-auth/providers/[PROVIDER], call it using .default() inside of the providers array configuration. This is required for SSR to properly function.

The NuxtAuthHandler accepts all options that NextAuth.js accepts for its API initialization. Use this place to configure authentication providers (OAuth, credential flow, ...), your secret, add callbacks for authentication events, configure a custom logger and more. Read the NextAuth.js docs to see all possible options.

Setting a secret

In addition to setting a provider, you also need to set a secret which is used to encrypt the JWT Tokens. To avoid hard-coding of the secret you can make it configurable at runtime by using an environment variable and exporting it at runtime or by using the Nuxt useRuntimeConfig (and then also setting the correct environment at runtime):

import { NuxtAuthHandler } from '#auth'

export default NuxtAuthHandler({
  // A secret string you define, to ensure correct encryption - NUXT_AUTH_SECRET required in production
  secret: useRuntimeConfig().authSecret

  // rest of your authentication configuration here!
})

Full code

// file: ~/server/api/auth/[...].ts
import GithubProvider from 'next-auth/providers/github'
import { NuxtAuthHandler } from '#auth'

export default NuxtAuthHandler({
  secret: useRuntimeConfig().authSecret,
  providers: [
    // @ts-expect-error Use .default here for it to work during SSR.
    GithubProvider.default({
      clientId: 'your-client-id',
      clientSecret: 'your-client-secret'
    })
  ]
})

Next Steps

Congrats! You have now configured your first authentication provider and can login to the application! We recommend the following next steps to continue configuring your application:

• Define custom Session Data
• Add more providers in your NuxtAuthHandler
• Customize your Auth pages