Authentication

When people save private data, your application needs to know who is making each request. CloudConfig manages users and sessions, then passes the signed-in user to your access rules.

This guide adds GitHub sign-in to a project from the Quickstart. You need a GitHub account and a running local app at http://localhost:3000.

1. Register Your GitHub App

From the project directory, run:

pnpm exec cloudconfig auth add github

The command enables GitHub in cloud.config.ts and prints its callback URL:

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

Keep the command open. Create a GitHub OAuth app with these values:

• Application name: a recognizable name, such as Blog Dashboard.
• Homepage URL: http://localhost:3000.
• Authorization callback URL: the URL printed by the command.

Copy the Client ID, then select Generate a new client secret. Return to the terminal and paste both values when prompted.

If your server uses another port, start setup with cloudconfig auth add github --url http://localhost:4000 instead. The callback must match the origin your browser uses.

2. Create the Sign-In Tables

Generate and apply the migration:

pnpm db:generate
pnpm db:migrate

This creates the users, sessions, accounts, and verification tables. CloudConfig mounts sign-in routes at /api/auth by default. Restart the development server to load the new environment settings.

Check for missing settings:

pnpm exec cloudconfig auth status

3. Sign In from Your App

The Nuxt dashboard template includes a GitHub sign-in button. If you used that template, open the app, sign in, and return to it from GitHub. Your access rules now receive the authenticated user.

For a custom sign-in page, create an auth client and start the redirect:

import { createAuthClient } from 'better-auth/client'

const authClient = createAuthClient()

await authClient.signIn.social({
  provider: 'github',
  callbackURL: '/',
})

The example assumes your page and API share an origin. GitHub redirects back to CloudConfig, which creates a user and a session.

Keep Credentials Out of Git

Setup writes GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET, and BETTER_AUTH_SECRET to the ignored .env file. It refuses to write secrets to a tracked file. Use .env.example for variable names with placeholders.

If you supply credentials manually, use those same names. Generate a session signing secret with pnpm exec cloudconfig auth secret.

Deployment synchronizes the required auth secrets to your selected host. You do not need to repeat their names in deploy.secrets. In CI, supply them through the process environment.

Choose Your Next Step

Follow Protect User Data to use the signed-in user in model rules. Dashboard starters also support two-factor verification.

Before deploying, set the production origin and callback.