Module (nuxt.config.ts)
Use the auth
-key inside the nuxt.config.ts
to configure the nuxt-auth
module itself. The module config has a root-config and then sub-properties for different aspects of the module:
/** * Configuration for the whole module. */interface ModuleOptions { /** * Whether the module is enabled at all */ isEnabled?: boolean /** * Full url at which the app will run combined with the path to authentication. You can set this differently depending on your selected authentication-provider: * - `authjs`: You must set the full URL, with origin and path in production. You can leave this empty in development * - `local`: You can set a full URL, but can also leave this empty to fallback to the default value of `/api/auth` or set only the path. * * ### `authjs` * * `baseURL` can be `undefined` during development but _must_ be set to the combination of origin + path that points to your `NuxtAuthHandler` for production. The origin consists out of: * - `scheme`: http / https * - `host`: e.g., localhost, example.org, google.com * - `port`: _empty_ (implies `:80` for http and `:443` for https), :3000, :8888 * * The path then is a string like `/path/to/auth/api/endpoint/root`. * * ### `local` * * Defaults to `/api/auth` for both development and production. Setting this is optional, if you set it you can set it to either: * - just a path: Will lead to `nuxt-auth` using `baseURL` as a relative path appended to the origin you deploy to. Example: `/backend/auth` * - an origin and a path: Will leav to `nuxt-auth` using `baseURL` as an absolute request path to perform requests to. Example: `https://example.com/auth` * * Note: If you point to a different origin than the one you deploy to you likely have to take care of CORS: Allowing cross origin requests. * * @example undefined * @example http://localhost:3000 * @example https://example.org/_auth * @example https://my-cool-site.com/api/authentication * @default http://localhost:3000/api/auth Default for `authjs` provider in development * @default undefined Default for `authjs` in production, will result in an error * @default /api/auth Default for `local` for both production and development */ baseURL?: string /** * Configuration of the authentication provider. Different providers are supported: * - auth.js: OAuth focused provider for non-static Nuxt 3 applications * - local: Provider for credentials & token based backends, e.g., written by yourself or provided by something like Laraval * * Find more about supported providers here: https://sidebase.io/nuxt-auth/v0.6/getting-started * */ provider?: AuthProviders /** * Configuration of the application-side session. */ session?: SessionConfig /** * Whether to add a global authentication middleware that protects all pages. Can be either `false` to disable, `true` to enabled * or an object to enable and apply extended configuration. * * If you enable this, everything is going to be protected and you can selectively disable protection for some pages by specifying `definePageMeta({ auth: false })` * If you disable this, everything is going to be public and you can selectively enable protection for some pages by specifying `definePageMeta({ auth: true })` * * Read more on this topic [in the page protection docs](https://sidebase.io/nuxt-auth/v0.6/application-side/protecting-pages#global-middleware). * * @example true * @example { allow404WithoutAuth: true } * @default false */ globalAppMiddleware?: GlobalMiddlewareOptions | boolean}
Additional Information
Provider authjs
- baseURL
You must set the baseURL
in production for this provider! You have two options to set it:
- Set the
AUTH_ORIGIN
environment variable at runtime - Set the
baseURL
baseURL-config key inside thenuxt.config.ts
(see an example above) at build-time- Note: Setting this at build time will result in this being hard-backed on the application side if you do not use server-side-rendering
- Note: It's called
baseURL
because it must contain bothorigin
andpath
that point to the auth handler, see the long docstring above
It is advised to use the AUTH_ORIGIN
environment variable if possible. The AUTH_ORIGIN
environment variable takes precendence over the baseURL
configuration key, so you can always overwrite the origin at deploy-time.
The baseURL
must be set so that nuxt-auth
can ensure that callbacks for authentication are correct. Examples of a baseURL
with both origin and path are:
https://example.org/api/auth
http://localhost:2345/_auth
https://app.company.com/api/auth
Explanation: What is an origin?
The origin
consists out of (up to) 3 parts:
- scheme:
http
orhttps
- host: e.g.,
localhost
,example.org
,www.sidebase.io
- port: e.g.,
:3000
,:4444
; leave empty to implicitly set:80
for http, and:443
for https (this is an internet convention, don't ask)
For the demo-app at https://nuxt-auth-example.sidebase.io we set the origin
to https://nuxt-auth-example.sidebase.io
. If for some reason required, you can explicitly set the origin
to http://localhost:3000
to stop nuxt-auth
from aborting npm run build
when the origin is unset.
Explanation: What is the path?
This is what tells the module where you added the authentication endpoints. By default this documentation recommends to use /api/auth
, so that means that the module expects that all requests to /api/auth/*
will be handled by the NuxtAuthHandler
.
To statify this, you need to create a catch-all server-route at that location by creating a file ~/server/api/auth/[...].ts
that exports the NuxtAuthHandler
, see more on this in the Quick Start or in the NuxtAuthHandler
documentation
If you want to have the authentication at another location, you should change the path, e.g., when setting the path-part of the baseURL
to:
path: "/api/_auth"
-> you need to add the authentication catch-all endpoints into~/server/api/_auth/[...].ts
and this is wherenuxt-auth
will lookpath: "/_auth"
-> you need to add the authentication catch-all endpoints into~/server/routes/_auth/[...].ts
and this is wherenuxt-auth
will look
See Nuxt server-routes docs on catch-all routes for a further explanation.