Package Exports

auth-astro
auth-astro/client
auth-astro/components
auth-astro/server

Readme

Auth Astro

Auth Astro is the Auth.js implementation for Astro by Astro´s community.

It wraps the core Auth.js library for Astro, exposing helper methods and components to make it easy to add authentication to your app.

Installation

Install the core Auth.js package as well as the auth-astro wrapper.

:::info The auth-astro wrapper will not work independently, it relies on @auth/core as a dependency. :::

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

Usage

Requirements

Node version >= 17.4
Astro config set to output mode server

Enable SSR in Your AstroJS Project

Initialize a new Astro project and enable server-side rendering.

Enabling server-side rendering within an Astro project requires a deployment adapter to be configured.

These settings can be configured within the astro.config.mjs file, located in the root of your project directory.

:::info The example below use the Node adapter :::

import { defineConfig } from 'astro/config';
import node from '@astrojs/node';

export default defineConfig({
  output: 'server',
  adapter: node({
    mode: 'standalone | middleware'
  }),
});

Resources:

Setup Environment Variables

Generate an auth secret by running openssl rand -hex 32 in a local terminal or by visiting generate-secret.vercel.app, copy the string, then set it as the AUTH_SECRET environment variable describe below.

Deploying to Vercel?

AUTH_TRUST_HOST can be set to false.

Deploying to another provider not named Vercel?

Set the AUTH_TRUST_HOST environment variable to true for hosting providers like Cloudflare Pages or Netlify.

AUTH_SECRET=<auth-secret>
AUTH_TRUST_HOST=true

Create an AstroAuth Endpoint

No matter which provider(s) you use, you need to create one Astro endpoint that handles requests.

Depending on the provider(s) you select, you will have to provide additional app credentials as environment variables within your .env file.

App Credentials should be set as environment variables, and imported using import.meta.env.

AUTH_SECRET=<auth-secret>
AUTH_TRUST_HOST=<true | false>
...
GITHUB_ID=<github-oauth-clientID>
GITHUB_SECRET=<github-oauth-clientSecret>

import { AstroAuth, type AstroAuthConfig } from "auth-astro"
import GitHub from "@auth/core/providers/github"

export const authOpts: AstroAuthConfig = {
  providers: [
    GitHub({
      clientId: import.meta.env.GITHUB_ID,
      clientSecret: import.meta.env.GITHUB_SECRET,
    }),
  ]
}

export const { get, post } = AstroAuth(authOpts)

Some OAuth Providers request a callback URL be submitted alongside requesting a Client ID, and Client Secret. The callback URL used by the providers must be set to the following, unless you override the prefix field in authOpts:

[origin]/api/auth/callback/[provider]

// example
// http://localhost:3000/api/auth/callback/github

Astro Auth exposes two ways to sign in and out. Inline scripts and Astro Components.

With Inline script tags

The signIn and signOut methods can be imported dynamically in an inline script.

---
---
<html>
<body>
  <button id="login">Login</button>
  <button id="logout">Logout</button>

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

With @auth/astro's Components

Alternatively, you can use the SignIn and SignOut button components provided by @auth/astro/components importing them into your Astro component's script

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

Fetching the session

You can fetch the session in one of two ways. The getSession method can be used in the component script section to fetch the session.

Within the component script section

---
import { getSession } from 'auth-astro';
import { authOpts } from './api/auth/[...astroauth]';

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

Within the Auth component

Alternatively, you can use the Auth component to fetch the session using a render prop.

---
import type { Session } from '@auth/core/types';
import { Auth, Signin, Signout } from 'auth-astro/components';
import { authOpts } from './api/auth/[...astroAuth]'
---
<Auth authOpts={authOpts}>
  {(session: Session) => 
    {session ? 
      <Signin provider="github">Login</Signin>
    :
      <Signout>Logout</Signout>
    }

    <p>
      {session ? `Logged in as ${session.user?.name}` : 'Not logged in'}
    </p>
  }
</Auth>

State of Project

We currently are waiting for the PR in the offical next-auth repository to be merged. Once this happened this package will be deprecated.

Contribution

Us waiting means on the PR to be merged means, we can still add new features to the PR, so, if you miss anything feel free to open a PR or issue in this repo and we will try to add it to the official package to come.

auth-astro