By default, it uses the JWT session strategy so it does not require a database to be configured.
For consistency, we recommend prefixing all Auth.js environment variables with
AUTH_. This way we can autodetect them, and it's they can also be distinguished from other environment variables.
Auth.js libraries require you to set an
AUTH_SECRET environment variable. This is used to encrypt cookies and tokens. It should be a random string of at least 32 characters. On Linux systems, you can generate a suitable string using the command
openssl rand -base64 32. You can also use a tool like generate-secret.vercel.app to generate a random value.
If you are using an OAuth Provider, your provider will have a
clientSecret that you will need to set as environment variables as well. In the case of OIDC, a third
issuer option is required.
Some Auth.js libraries can infer environment variables without passing them explicitly. For example, the Next.js library can infer the
AUTH_GITHUB_SECRET environment variables as the
clientSecret options for the GitHub provider. See the API reference for your framework to learn more about this feature.
Hosting services like Vercel and Netlify are great for deploying Auth.js apps. The following steps should help you get started:
- Create the required environment variables for the desired deploy environments.
- In the case of an OAuth provider, set the callback URL for the provider to
yourdomain.comwith your domain and
providerwith the provider name, eg.:
Auth.js can also be deployed anywhere you can deploy the framework of your choice. Check out the framework's documentation on self-hosting.
Securing a preview deployment
Most OAuth providers cannot be configured with multiple callback URLs or using a wildcard.
However, Auth.js supports Preview deployments, even with OAuth providers:
- Determine a stable deployment URL. Eg.: A deployment whose URL does not change between builds, for example.
auth.yourdomain.com(using a subdomain is not a requirement, this can be the main site's URL too, for example.)
AUTH_REDIRECT_PROXY_URLto that stable deployment URL, including the path from where Auth.js handles the routes. Eg.: (
- For your OAuth provider, set the callback URL using the stable deployment URL. Eg.: For GitHub
To support preview deployments, the
AUTH_SECRET value needs to be the same for the stable deployment and deployments that will need OAuth support.
If you are storing users in a database, we recommend using a different OAuth app for development/production so that you don't mix your test and production user base.
How does this work?
To support preview deployments, Auth.js uses the stable deployment URL as a redirect proxy server.
It will redirect the OAuth callback request to the preview deployment URL, but only when the
AUTH_REDIRECT_PROXY_URL environment variable is set. The stable deployment can still act as a regular app.
When a user initiates an OAuth sign-in flow on a preview deployment, we save its URL in the
state query parameter but set the
redirect_uri to the stable deployment.
Then, the OAuth provider will redirect the user to the stable deployment, which will verify the
state parameter and redirect the user to the preview deployment URL if the
state is valid. This is secured by relying on the same server-side
AUTH_SECRET for the stable deployment and the preview deployment.