Setting up Auth on Astro using auth-astro

Published: at 07:27 PM

I recently moved this blog over to Astro and I wanted to add authentication to it. I decided to use auth-astro to handle the authentication. I also wanted to use GitHub OAuth as my authentication provider. I had a few issues getting it set up, so I wanted to document how I got it working.

First, things first, auth-astro requires that you be using Astro in SSR mode. This is because it uses the server to handle the authentication. I was already using SSR mode, so I didn’t have to change anything there. But if you aren’t using SSR mode, you will need to change your astro.config.mjs file to use SSR mode. Install auth-astro by running npm install auth-astro or yarn add auth-astro. The install script will automatically install the needed Astro integrations. After auth-astro is installed, you will need to change your config file to use SSR mode. I’m using Vercel to deploy my site, so I also needed to install the Vercel serverless adapter. Astro has many adapters and they can be found here.

import { defineConfig } from "astro/config";
import vercelServerless from "@astrojs/vercel/serverless";

export default defineConfig({
  // your configuration options here...
  output: server,
  adapter: vercelServerless(),
  // more configuration options here...
});

One other note, changing your site to SSR may have other reprercussions, so make sure you test your site after making the change. In my case many of my static pages were broken because I was using getStaticPaths() which is not supported in SSR mode. I had to make the necessary changes to get those pages working again.

After I had that part settled, I needed to set up GitHub OAuth. One of the major oversights of the auth-astro documentations is not mentioning what it’s config file needs to be called or where it needs to be located. I found the answer in one of the issues on their repo. It needs to be in a file called auth.config.ts (I’m using TypeScript). And it needs to be in the root of your project. Here is what my basic auth.config.ts file looks like:

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

You can find the instructions for setting up your GitHub OAuth application here. For the required callback url, you will use something like http://localhost:3000/api/auth/callback/github for testing. I added one OAuth app for testing using this callback url and another for production using the callback url using the pattern [origin]/api/auth/callback/[provider].

You will need to add the GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET to your .env file. You can find more information about using environment variables in Astro here. Don’t forget that you’ll also need to add these environment variables to your hosting provider, in my case Vercel.

You will need to add another environment variable called AUTH_SECRET. You can generate the secret value by running openssl rand -hex 32. If you’re running on Vercel, that is all, but if not you’ll also need to add AUTH_TRUST_HOST=true.

GITHUB_CLIENT_ID=your_client_id
GITHUB_CLIENT_SECRET=your_client_secret
AUTH_SECRET=your_auth_secret
AUTH_TRUST_HOST=true

Now that all the setup is done, you can add a simple login page to test it out. Add an a login.astro page to your pages folder. Here is what my login page looks like:

---
import { SignIn, SignOut } from "auth-astro/components";
---

<html>
  <body>
    <SignIn provider="github" />
    <SignOut />
  </body>
</html>

Once that’s done, you can create another page, called protected.astro and add the following code to it:

---
import { getSession } from "auth-astro/server";
let session = await getSession(Astro.request);
if (!session) ___astro_return;
throw Astro.redirect("/");
---

<html>
  <body>
    <h1>Protected Page</h1>
    <p>Hello, {session?.user?.name}!</p>
  </body>
</html>

If you visit this page while not signed in, it should redirect you to the home page. If you visit it while signed in, it should display your name.

I love Astro so far. The ability to add components written in different UI frameworks is amazing. I’m using React and Astro for my components and it’s working great so far.

That’s my crash course. Hopefully I haven’t missed anything. If you have any questions, feel free to reach out to me on Mastodon @rhymeswithjazz.