Authentication

Authentication and authorization are two security processes that manage access to your website or app. Authentication verifies a visitor’s identity, while authorization grants access to protected areas and resources.

Authentication allows you to customize areas of your site for logged-in individuals and provides the greatest protection for personal or private information. Authentication libraries (e.g. Lucia Auth, Auth.js, Clerk) provide utilities for multiple authentication methods such as email sign-in and OAuth providers.

Tip

There is no official authentication solution for Astro, but you can find community “auth” integrations in the integrations directory.

See how to add authentication with Supabase or add authentication with Firebase in our dedicated guides for these backend services.

Lucia

Section titled Lucia

Lucia is a framework-agnostic, session-based authentication library with great Astro support.

Installation

Section titled Installation

Install Lucia using the package manager of your choice.

npm

npm install lucia

pnpm

pnpm add lucia

Yarn

yarn add lucia

Configuration

Section titled Configuration

Use Lucia’s “Getting started in Astro” guide to initialize Lucia with an adapter and set up a database to store users and sessions.

Usage

Section titled Usage

Tip

Follow one of Lucia’s complete Astro tutorials to add username and password authentication or GitHub OAuth to your Astro project.

Next Steps

Section titled Next Steps

• Example Astro + Lucia OAuth project
• Example Astro + Lucia username and password project

Auth.js

Section titled Auth.js

Auth.js is a framework agnostic solution for authentication. A community framework adapter auth-astro is available for Astro.

Installation

Section titled Installation

Use the astro add command for your preferred package manager to add the auth-astro integration.

npm

npx astro add auth-astro

pnpm

pnpm astro add auth-astro

Yarn

yarn astro add auth-astro

Manual installation

Section titled Manual installation

To install auth-astro manually, install the required package for your package manager:

npm

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

pnpm

pnpm add auth-astro @auth/core@^0.18.6

Yarn

yarn add auth-astro @auth/core@^0.18.6

Then, apply the integration to your astro.config.* file using the integrations property:

astro.config.mjs

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

export default defineConfig({
  // ...
  integrations: [auth()],
});

Configuration

Section titled Configuration

Create an auth.config.mjs file in your project’s root directory. Add any auth providers or methods you wish to support, along with any environment variables they require.

auth.config.mjs

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,
    }),
  ],
});

Create a .env file in the root of your project if it does not already exist. Add the following two environment variables. AUTH_SECRET should be a private string with a minimum of 32 characters.

.env

AUTH_TRUST_HOST=true
AUTH_SECRET=<my-auth-secret>

Usage

Section titled Usage

You can add sign-in and sign-out buttons using the auth-astro/client module in a script tag or client-side framework component.

src/pages/index.astro

---
import Layout from 'src/layouts/Base.astro';
---
<Layout>
  <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>
</Layout>

You can fetch the user’s session using the getSession method.

src/pages/index.astro

---
import Layout from 'src/layouts/Base.astro';
import { getSession } from 'auth-astro/server';

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

Next Steps

Section titled Next Steps

• auth-astro on GitHub
• Auth.js documentation

Clerk

Section titled Clerk

Clerk is a complete suite of embeddable UIs, flexible APIs, and admin dashboards to authenticate and manage your users. An official Clerk SDK for Astro is available.

Installation

Section titled Installation

Install @clerk/astro using the package manager of your choice.

npm

npm install @clerk/astro

pnpm

pnpm add @clerk/astro

Yarn

yarn add @clerk/astro

Configuration

Section titled Configuration

Follow Clerk’s own Astro Quickstart guide to set up Clerk integration and middleware in your Astro project.

Usage

Section titled Usage

Clerk provides components that allow you to control the visibility of pages based on your user’s authentication state. Show logged out users a sign in button instead of the content available to users who are logged in:

src/pages/index.astro

---
import Layout from 'src/layouts/Base.astro';
import { SignedIn, SignedOut, UserButton, SignInButton } from '@clerk/astro/components';
---

<Layout>
    <SignedIn>
        <UserButton />
    </SignedIn>
    <SignedOut>
        <SignInButton />
    </SignedOut>
</Layout>

Clerk also allows you to protect routes on the server using middleware. Specify which routes are protected, and prompt unauthenticated users to sign in:

src/middleware.ts

import { clerkMiddleware, createRouteMatcher } from '@clerk/astro/server';

const isProtectedRoute = createRouteMatcher([
  '/dashboard(.*)',
  '/forum(.*)',
]);

export const onRequest = clerkMiddleware((auth, context) => {
  if (!auth().userId && isProtectedRoute(context.request)) {
    return auth().redirectToSignIn();
  }
});

Next Steps

Section titled Next Steps

• Read the official @clerk/astro documentation
• Start from a template with the Clerk + Astro Quickstart project

Community Resources

Section titled Community Resources

• Using Microsoft Entra Id EasyAuth with Astro and Azure Static Web App