@dataroadinc/setup-auth

CLI tool and programmatic API for automated OAuth setup across cloud platforms. This package helps developers and administrators set up OAuth authentication for their applications across multiple cloud providers.

Features

Multi-Platform Support: Google Cloud Platform, Azure AD, GitHub OAuth
Automated Setup: Streamlined OAuth client creation and configuration
Vercel Integration: Automatic redirect URL management for Vercel deployments
Service Account Management: GCP service account and IAM role setup
Webhook Support: Automated redirect URL updates via webhooks
Stateless Versioning: Dynamic changelog generation with @dataroadinc/versioning
Programmatic API: Stable, versioned API for callback URL registration

Installation

Recommended: Install as a devDependency unless you need to use the programmatic API at runtime.

As a devDependency (CLI usage only)

npm install --save-dev @dataroadinc/setup-auth

or with pnpm:

pnpm add -D @dataroadinc/setup-auth

As a regular dependency (if using programmatic API)

If you need to use the programmatic API in your application code (e.g., for webhook handlers), install as a regular dependency:

npm install @dataroadinc/setup-auth

or with pnpm:

pnpm add @dataroadinc/setup-auth

Use as a devDependency if you only use the CLI or scripts in CI/CD, not in your app's runtime code. If you import it in your application code, use a regular dependency.

Quick Start

Development

For development, you can run the CLI directly using tsx:

# Install dependencies
pnpm install

# Set up environment variables
cp env.local.example .env.local
# Edit .env.local with your configuration

# Run the CLI
pnpm start --help

Production

For production use, it's recommended to use tsx to run the TypeScript source directly, which handles path mapping automatically:

# Install tsx globally
npm install -g tsx

# Run the CLI
tsx src/index.js --help

Alternatively, you can build and run the compiled version, but you'll need to handle path mapping:

# Build the project
pnpm build

# Run with path mapping (requires tsconfig-paths)
npx tsconfig-paths/register node dist/index.js --help

Programmatic API

The setup-auth package now provides a stable, programmatic API that allows programs to register callback URLs and perform OAuth setup operations without relying on CLI commands.

Basic Usage

import {
  registerCallbackUrls,
  updateCallbackUrls,
  type CallbackUrlConfig,
} from "@dataroadinc/setup-auth"

// Register callback URLs for a new deployment
const config: CallbackUrlConfig = {
  provider: "gcp",
  platform: "vercel",
  deploymentUrl: "https://my-app-abc123.vercel.app",
  callbackPath: "/api/auth/callback/gcp",
  projectConfig: {
    gcpProjectId: process.env.GCP_OAUTH_PROJECT_ID!,
  },
}

const result = await registerCallbackUrls(config)

if (result.success) {
  console.log("Callback URLs registered successfully:", result.registeredUrls)
  console.log("OAuth Client ID:", result.clientId)
} else {
  console.error("Registration failed:", result.error)
}

Integration Examples

Next.js API Route

// pages/api/auth/setup.ts
import { NextApiRequest, NextApiResponse } from "next"
import { updateCallbackUrls } from "@dataroadinc/setup-auth"

export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  if (req.method !== "POST") {
    return res.status(405).json({ error: "Method not allowed" })
  }

  const config = {
    provider: "gcp" as const,
    platform: "vercel" as const,
    deploymentUrl: process.env.VERCEL_URL,
    projectConfig: {
      gcpProjectId: process.env.GCP_OAUTH_PROJECT_ID!,
    },
  }

  const result = await updateCallbackUrls(config)

  if (result.success) {
    res.status(200).json({
      success: true,
      redirectUris: result.redirectUris,
    })
  } else {
    res.status(500).json({
      success: false,
      error: result.error,
    })
  }
}

CI/CD Pipeline

# .github/workflows/deploy.yml
name: Deploy and Setup Auth

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: "18"
      - name: Install dependencies
        run: pnpm install
      - name: Deploy to Vercel
        run: vercel --prod
      - name: Setup OAuth Callback URLs
        run: |
          node -e "
          const { registerCallbackUrls } = require('@dataroadinc/setup-auth');

          registerCallbackUrls({
            provider: 'gcp',
            platform: 'vercel',
            deploymentUrl: process.env.VERCEL_URL,
            projectConfig: {
              gcpProjectId: process.env.GCP_OAUTH_PROJECT_ID
            }
          }).then(result => {
            if (result.success) {
              console.log('OAuth setup successful:', result.clientId);
            } else {
              console.error('OAuth setup failed:', result.error);
              process.exit(1);
            }
          });
          "
        env:
          VERCEL_URL: ${{ steps.deploy.outputs.url }}
          GCP_OAUTH_PROJECT_ID: ${{ secrets.GCP_OAUTH_PROJECT_ID }}

For complete documentation on the programmatic API, see Programmatic API Guide.

Configuration

Create a .env.local file in the root directory with the required environment variables. See env.local.example for a complete list of all available variables.

Required Variables

# Organization Configuration
EKG_ORG_PRIMARY_DOMAIN=your-domain.com

# Project Configuration
EKG_PROJECT_NAME=your-project-name

# Google Cloud Platform OAuth Configuration
GCP_OAUTH_ALLOWED_DOMAINS=your-domain.com,another-domain.com
GCP_OAUTH_ORGANIZATION_ID=your-gcp-organization-id
GCP_OAUTH_PROJECT_ID=your-gcp-project-id
GCP_OAUTH_APPLICATION_CREDENTIALS=/path/to/your/service-account-key.json

# Vercel Configuration
VERCEL_TEAM_ID=team_xxxxxxxxxxxxxxxxxxxx
VERCEL_PROJECT_ID=prj_xxxxxxxxxxxxxxxxxxxx
VERCEL_PROJECT_NAME=your-vercel-project-name
VERCEL_ACCESS_TOKEN=your-vercel-access-token

# OAuth Client Configuration (will be created by setup commands)
GCP_OAUTH_CLIENT_ID=
GCP_OAUTH_CLIENT_SECRET=

Optional Variables

Many additional variables are available for customization. See env.local.example for the complete list including:

Organization branding and metadata
Project descriptions and labels
Internal and external endpoint URLs
Authentication secrets
Azure AD and GitHub OAuth configuration
SPARQL endpoint configuration

Available Commands

gcp-setup-service-account - [ADMIN ONLY] One-time setup: Creates service account, IAM roles, and OAuth consent screen
gcp-setup-oauth - [DEVELOPER] Per-deployment setup: Creates/updates OAuth clients for end-user authentication
github-setup-oauth - Set up "Login with GitHub" (GitHub OAuth) for the given project
azure-setup-oauth - Set up "Login with Microsoft" (Azure AD OAuth) for the given project
gcp-view - View various types of items around the OAuth2 setup
update-redirect-urls - Update OAuth redirect URLs for a deployment
setup-webhook - Set up a webhook for automatic redirect URL updates
login - Perform cloud provider login (GCP user, ADC, service account, Azure, AWS, etc.)

Documentation

Comprehensive documentation is available in the docs/ directory:

Development Guide - Complete setup and workflow
Code Formatting - IDE setup and formatting rules
Markdown Formatting - Documentation standards
Versioning - Stateless versioning with dr-ts-versioning
Open Source Release - Release planning and status
Vercel Integration - Vercel integration details
GCP Integration - Google Cloud Platform integration
Automation and Testing - Automation principles and testing
Authentication and Workflow - Authentication automation
OAuth Automation - OAuth automation details

Development

# Install dependencies
pnpm install

# Run in development mode
pnpm start

# Build for production
pnpm build

# Run tests
pnpm test

# Lint code
pnpm lint

# Format code
pnpm format

License

MIT