auth-astro

You can install auth-astro using the Astro CLI, which automatically handles package installation and integration configuration, or manually.

Using Astro CLI (Recommended)

npm run astro add auth-astro

Manual Installation

Install the core packages:

npm install auth-astro@latest @auth/core@^0.18.6

Note for pnpm users: You must also install the cookie package:

pnpm i cookie

After manual installation, you must add the integration to your astro.config.mjs by importing it and adding it to the integrations array.

To secure your authentication, you must set the following environment variables:

1. AUTH_SECRET: A random 32-character hex string. You can generate one using openssl rand -hex 32.
2. AUTH_TRUST_HOST: Set this to true if you are hosting on providers like Cloudflare Pages or Netlify.

Note: If you are deploying to Vercel, you do not need to set AUTH_TRUST_HOST as the package detects the Vercel environment automatically.

AUTH_SECRET=<auth-secret>
AUTH_TRUST_HOST=true

Create an auth.config.ts file in your project root to define your authentication providers using the defineConfig helper.

import GitHub from '@auth/core/providers/github'
import { defineConfig } from 'auth-astro'

export default defineConfig({
	providers: [
		GitHub({
			clientId: import.meta.env.GITHUB_CLIENT_ID,
			clientSecret: import.meta.env.GITHUB_CLIENT_SECRET,
		}),
	],
})

Callback URLs

OAuth providers require a callback URL. By default, this is: [origin]/api/auth/callback/[provider]

Example for GitHub: http://localhost:4321/api/auth/callback/github

To use auth-astro in your Astro project, import the default integration export and add it to your astro.config.mjs file. You can also use the defineConfig helper exported from the package to ensure type safety for your Astro configuration.

import { defineConfig } from 'astro/config';
import authAstro from 'auth-astro';

export default defineConfig({
  integrations: [authAstro()],
});

import authAstro from 'auth-astro';

// In your astro.config.mjs
export default {
  integrations: [authAstro()],
};

To enable authentication endpoints (like sign-in, sign-out, and callback handling) in your Astro project, you must create an API route handler using AstroAuth().

This file should be placed at src/api/[...auth].ts (or .js). You must set export const prerender = false; to ensure the route is handled dynamically at runtime rather than being generated at build time. The AstroAuth() function returns the required GET and POST handlers for the Auth.js protocol.

import { AstroAuth } from '../../server'

export const prerender = false

export const { GET, POST } = AstroAuth()

For client-side interactivity (e.g., inside a <script> tag), you can dynamically import signIn and signOut from auth-astro/client.

<button id="login">Login</button>
<button id="logout">Logout</button>

<script>
  const { signIn, signOut } = await import("auth-astro/client")
  document.querySelector("#login").onclick = () => signIn("github")
  document.querySelector("#logout").onclick = () => signOut()
</script>

Use the pre-built SignIn and SignOut components from auth-astro/components within your Astro component scripts.

---
import { SignIn, SignOut } from 'auth-astro/components'
---
<SignIn provider="github" />
<SignOut />

If you need to access your authentication configuration within your application, you can import it using the virtual module auth:config.

import authConfig from 'auth:config'

To retrieve the current user's session within an Astro component's frontmatter (server-side), use the getSession method from auth-astro/server and pass the Astro.request object.

---
import { getSession } from 'auth-astro/server';

const session = await getSession(Astro.request)
---
{session ? (
  <p>Welcome {session.user?.name}</p>
) : (
  <p>Not logged in</p>
)}

The Auth component allows you to fetch the session and render UI based on the session state using a render prop. This is useful for conditional rendering of login/logout buttons.

---
import type { Session } from '@auth/core/types';
import { Auth, SignIn, SignOut } from 'auth-astro/components';
---
<Auth>
  {(session: Session) => 
    {
      return (
        <>
          {session ? <SignOut>Logout</SignOut> : <SignIn provider="github">Login</SignIn>}
          <p>
            {session ? `Logged in as ${session.user?.name}` : 'Not logged in'}
          </p>
        </>
      )
    }
  }
</Auth>

Ensure your environment meets these requirements:

• Node.js: version >= 17.4
• Astro Output Mode: Must be set to server
• SSR: Server-Side Rendering must be enabled in your Astro project.

The auth-astro package exports defineConfig which can be used to provide type safety when defining your Astro configuration. This is typically used in conjunction with the auth-astro integration to ensure all configuration properties are correctly typed.

import { defineConfig } from 'astro/config';
import authAstro from 'auth-astro';

export default defineConfig({
  integrations: [authAstro()],
});