Lucia

Lucia is less an auth library than it is a framework for building your own auth system. It takes considerably more effort to set-up, but gives you more control over how your auth works.

Why use Lucia for CLIs?

Doing OAuth for CLIs is more complex than for web apps. This is because CLIs are run in a terminal, and therefore cannot write to the browser (e.g. cookies) to store session data.

Due to this, Lucia is a good choice for CLIs because of the additional control that is necessary to handle the differences between web apps and CLIs.

Setup

If you're using the Cloudflare Monorepo or CLI Monorepo template, the @workspace-apps/web app is setup with Lucia out of the box.

To get the auth setup working, you will need to create a new OAuth app in your GitHub account, and then update the environment variables in the @workspace-apps/web app with the necessary client ID and secret.

Creating a new GitHub OAuth app

To create a new OAuth app in your GitHub account, you will need to visit the GitHub Developer Settings page. From there, you will need to click the "New OAuth App" button. Fill out the form with the following information:

• Application name: The name of your application.
• Homepage URL: The URL of your application's homepage.
• Authorization callback URL: The URL of your application's authorization callback.
  • On local development, this will be http://localhost:3000/api/auth/callback/github.
  • On production, this will be the same as the callback URL for local development, but the domain will be your production domain.

After creating the OAuth app, you will be given a Client ID and Client Secret. You will need to update the GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET environment variables in /apps/web with the values you were given.

• For the Cloudflare Monorepo, this will be in the /apps/web/.dev.vars file.

  GITHUB_CLIENT_ID="your-github-client-id"
  GITHUB_CLIENT_SECRET="your-github-client-secret"

• For the CLI Monorepo, this will be in the /apps/web/.env file.

  GITHUB_CLIENT_ID="your-github-client-id"
  GITHUB_CLIENT_SECRET="your-github-client-secret"

Using other OAuth providers

If you want to use different/additional OAuth providers (e.g. Google OAuth), you will need to make updates to the following files within @workspace-apps/web:

• /src/server/auth/getAuth.ts

  • Update the providers object to include the new provider(s).

  import { GitHub, Google } from "arctic";
  
  // ...
  export const getAuth = (params: GetAuthParams) => {
      // ...
      return {
          // ...
          providers: {
              get github() {
                  return new GitHub(env.GITHUB_CLIENT_ID, env.GITHUB_CLIENT_SECRET);
              },
              // Add your other providers here...
              get google() {
                  return new Google(env.GOOGLE_CLIENT_ID, env.GOOGLE_CLIENT_SECRET);
              },
          },
      };
  };

• /src/server/router/auth/router.ts

  • Add a new GET endpoint for the new provider(s).
    • e.g. GET /api/auth/google
    • Simply copy the existing GET endpoint for GitHub, and update the provider that is used to the new provider.
  • Add a new GET endpoint for the callback URL of the new provider(s).
    • e.g. GET /api/auth/google/callback
    • You can start with a copy of the existing callback endpoint for GitHub. But the new OAuth provider may return different user profile data than GitHub. This will require that you map the properties of that provider's profile data to the columns of the User table in your database.
      • If you wish to track different fields for each provider, you will need to add new columns to the User table in your database.

• /src/app/(general)/login/page.tsx

  • Add a new login button for the new provider(s).

• /src/app/(general)/signup/page.tsx

  • Add a new signup button for the new provider(s).