/configure-studio-auth

name: nuxt-studio:configure-auth
description: Step-by-step guide for configuring OAuth authentication (GitHub/GitLab/Google) for Nuxt Studio
argument-hint: No arguments required - interactive OAuth setup guide
allowed-tools: [Read, Write, Edit, WebFetch, AskUserQuestion]

Configure Studio OAuth Authentication

Guide the user through OAuth provider setup with detailed instructions and credential management.

Execution Steps

1. Detect Current Configuration

Read .env.local (or .env) to check for existing OAuth configuration:

# Check for existing OAuth variables

Identify which providers (if any) are already configured:

• GitHub: NUXT_OAUTH_GITHUB_CLIENT_ID
• GitLab: NUXT_OAUTH_GITLAB_CLIENT_ID
• Google: NUXT_OAUTH_GOOGLE_CLIENT_ID

2. Choose Provider (if not already configured)

If no provider is configured, ask user:

**Question**: "Which OAuth provider would you like to set up?"

• Header: "OAuth Provider"
• Options:
• **GitHub** (Recommended): "Best for GitHub repositories. Quick setup."
• **GitLab**: "For GitLab.com or self-hosted instances"
• **Google**: "Universal option for any team members"
• Multi-select: false

If multiple providers already configured, ask which one to reconfigure.

3. Determine Deployment URL

Ask user:

**Question**: "What is your Studio deployment URL?"

• Header: "Deployment URL"
• Options:
• **Local Development**: "http://localhost:3000 (for testing)"
• **Production**: "Custom production URL (e.g., https://studio.yourdomain.com)"
• Multi-select: false

If "Production" selected, ask for the full URL.

4. Provider-Specific Setup Instructions

Based on chosen provider, provide detailed setup instructions:

For GitHub OAuth:

**Step 1: Create OAuth App**

Provide instructions:

1. Open GitHub OAuth Apps page:
   https://github.com/settings/developers

2. Click "New OAuth App"

3. Fill in the form:
   - Application name: "[Your Site] - Studio CMS"
   - Homepage URL: https://yourdomain.com
   - Authorization callback URL: [DEPLOYMENT_URL]/api/auth/callback/github

   Example callback URL:
   - Local: http://localhost:3000/api/auth/callback/github
   - Production: https://studio.yourdomain.com/api/auth/callback/github

4. Click "Register application"

5. Note your Client ID (shown on the page)

6. Click "Generate a new client secret"

7. Copy the secret IMMEDIATELY (shown only once)

Offer to open the URL in browser:

• Use WebFetch to check if URL is accessible
• Tell user: "I can't open browsers, but visit this URL: https://github.com/settings/developers"

**Step 2: Get Credentials**

Ask user for credentials:

"Please paste your GitHub OAuth credentials:"

Use AskUserQuestion or prompt user to provide: 1. Client ID 2. Client Secret

**Step 3: Update Environment Variables**

Update .env.local file:

# GitHub OAuth
NUXT_OAUTH_GITHUB_CLIENT_ID=[provided_client_id]
NUXT_OAUTH_GITHUB_CLIENT_SECRET=[provided_secret]

Use Edit tool to update the file, or Write if it doesn't exist.

For GitLab OAuth:

**Step 1: Create OAuth Application**

Provide instructions:

1. Open GitLab Applications page:
   - GitLab.com: https://gitlab.com/-/profile/applications
   - Self-hosted: https://your-gitlab.com/-/profile/applications

2. Fill in the form:
   - Name: "[Your Site] - Studio CMS"
   - Redirect URI: [DEPLOYMENT_URL]/api/auth/callback/gitlab

   Example callback URL:
   - Local: http://localhost:3000/api/auth/callback/gitlab
   - Production: https://studio.yourdomain.com/api/auth/callback/gitlab

   - Confidential: ✅ CHECK THIS BOX (required!)
   - Scopes: Select these:
     ✅ read_user
     ✅ read_repository
     ✅ write_repository

3. Click "Save application"

4. Copy the Application ID and Secret

**Step 2: Check for Self-Hosted**

Ask user:

"Are you using self-hosted GitLab?"

• If yes, ask for GitLab server URL (e.g., https://gitlab.yourcompany.com)
• If no, use https://gitlab.com

**Step 3: Get Credentials**

Prompt user for: 1. Application ID 2. Secret 3. Server URL (if self-hosted)

**Step 4: Update Environment Variables**

# GitLab OAuth
NUXT_OAUTH_GITLAB_CLIENT_ID=[application_id]
NUXT_OAUTH_GITLAB_CLIENT_SECRET=[secret]

# For self-hosted only:
NUXT_OAUTH_GITLAB_SERVER_URL=[server_url]

For Google OAuth:

**Step 1: Create Google Cloud Project**

Provide instructions:

1. Open Google Cloud Console:
   https://console.cloud.google.com/apis/credentials

2. Create or select a project

3. Configure OAuth Consent Screen (if first time):
   - Click "OAuth consent screen" in sidebar
   - User Type:
     * Internal (for Google Workspace - recommended)
     * External (for any Google accounts)
   - App name: "[Your Site] Studio CMS"
   - User support email: [your email]
   - Authorized domains: yourdomain.com
   - Scopes: openid, email, profile
   - Save and continue

4. Create OAuth Client ID:
   - Click "Credentials" → "Create Credentials" → "OAuth client ID"
   - Application type: "Web application"
   - Name: "Studio CMS"
   - Authorized JavaScript origins:
     * Local: http://localhost:3000
     * Production: https://studio.yourdomain.com
   - Authorized redirect URIs:
     * Local: http://localhost:3000/api/auth/callback/google
     * Production: https://studio.yourdomain.com/api/auth/callback/google
   - Click "Create"

5. Copy Client ID and Client Secret

**Step 2: Get Credentials**

Prompt user for: 1. Client ID (format: *.apps.googleusercontent.com) 2. Client Secret

**Step 3: Update Environment Variables**

# Google OAuth
NUXT_OAUTH_GOOGLE_CLIENT_ID=[client_id]
NUXT_OAUTH_GOOGLE_CLIENT_SECRET=[secret]

5. Update nuxt.config.ts

Read nuxt.config.ts and check if runtimeConfig includes OAuth configuration.

If not, add it:

runtimeConfig: {
  oauth: {
    [provider]: {
      clientId: process.env.NUXT_OAUTH_[PROVIDER]_CLIENT_ID,
      clientSecret: process.env.NUXT_OAUTH_[PROVIDER]_CLIENT_SECRET
    }
  },
  public: {
    studi