OAuth

This guide walks you through setting up OAuth authentication with Google and GitHub providers in Shield360 using NextAuth.js.

Overview

Shield360 supports OAuth authentication through NextAuth.js with these providers:

• Google OAuth - Sign in with Google accounts
• GitHub OAuth - Sign in with GitHub accounts
• Email/Password - Traditional credentials-based authentication

NextAuth.js automatically handles:

• OAuth 2.0 authorization flow
• Token management and refresh
• User session management
• Security best practices

When users sign in via OAuth, Shield360 automatically:

• Creates new user accounts if they don’t exist
• Links OAuth accounts to existing email-based accounts
• Syncs profile information (name, profile picture)
• Runs user setup and database configuration

Google OAuth setup

1. Create Google Cloud project

Access Google API console

Visit the Google API Console to create OAuth 2.0 credentials.

Create or select project

• Click on the project dropdown at the top
• Click “New Project” or select an existing project
• Give your project a meaningful name like “Shield360 Authentication”

Enable required APIs

• Navigate to “APIs & Services” > “Library”
• Search for and enable “Google+ API” or “People API”
• This allows access to user profile information

2. Configure OAuth consent screen

Setup consent screen

• Navigate to “APIs & Services” > “OAuth consent screen”
• Choose “External” for user type (unless you have Google Workspace)
• Fill in required information:
  • App name: Shield360
  • User support email: Your email address
  • Developer contact information: Your email address

Add test users (Development)

• For testing, add email addresses that can access your app
• Production apps will be available to all users once published

3. Create OAuth credentials

Create Web Application Credentials

• Navigate to “APIs & Services” > “Credentials”
• Click “Create Credentials” > “OAuth client ID”
• Select “Web application”

Configure redirect URIs

As per NextAuth.js Google provider documentation:

• Authorized JavaScript origins:

  http://localhost:3000
  https://yourdomain.com

• Authorized redirect URIs:

  http://localhost:3000/api/auth/callback/google
  https://yourdomain.com/api/auth/callback/google

Caution

The redirect URIs must match exactly, including the port number (3000 in your case).

Save credentials

• Click “Create”
• Copy the Client ID and Client Secret
• Store them securely for environment configuration

GitHub OAuth setup

1. Create GitHub OAuth app

Access GitHub Developer Settings

Go to GitHub Settings > Developer settings > OAuth Apps

Register New OAuth Application

Click “New OAuth App” and configure:

• Application name: Shield360
• Homepage URL: http://localhost:3000 (development) or https://yourdomain.com (production)
• Authorization callback URL:

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

Note

As per NextAuth.js GitHub provider documentation, GitHub only allows one callback URL per Client ID/Secret.

Generate Client Secret

• Click “Register application”
• Copy the Client ID
• Click “Generate a new client secret”
• Copy the Client Secret immediately (it won’t be shown again)

2. GitHub app permissions (Optional)

Note

If creating a GitHub App instead of OAuth App, set “Email addresses” permission to read-only to access private email addresses as mentioned in the NextAuth.js documentation.

Environment Configuration

# NextAuth Configuration
NEXTAUTH_URL=https://yourdomain.com
NEXTAUTH_SECRET=your-production-secret

# Google OAuth
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret

# GitHub OAuth
GITHUB_CLIENT_ID=your-github-client-id
GITHUB_CLIENT_SECRET=your-github-client-secret

Production Setup

Update OAuth app URLs

Update both Google and GitHub OAuth apps with production URLs:

• Google: Add https://yourdomain.com to origins and https://yourdomain.com/api/auth/callback/google to redirect URIs
• GitHub: Update callback URL to https://yourdomain.com/api/auth/callback/github

HTTPS requirement

Ensure your production domain has a valid SSL certificate. OAuth providers require HTTPS in production.

Features & behavior

User management

• New Users: Automatically created when signing in via OAuth for the first time
• Existing Users: OAuth accounts are linked to existing email-based accounts
• Profile Sync: Name and profile picture are synced from OAuth providers
• Database Setup: New users get proper database configurations and permissions

Session management

NextAuth.js handles all session management including:

• JWT token creation and validation
• Session persistence across browser sessions
• Automatic token refresh when needed
• Secure cookie configuration

Troubleshooting

OAuth button not appearing

Solutions:

• Check that environment variables are set correctly
• Ensure .env file is in the correct directory (src/client/) for development
• You can create a .env file to in the same directory as the docker-compose.yml file with the creds

Redirect URI mismatch error

Solutions:

• Verify redirect URIs match exactly in OAuth app settings
• Check port numbers (3001 vs 3000)
• Ensure protocol matches (http/https)

Invalid client error

Solutions:

• Verify client credentials are copied correctly
• Check for extra spaces or characters in environment variables
• Ensure you’re using credentials from the correct OAuth app

NEXTAUTH_URL mismatch

Solutions:

• Set NEXTAUTH_URL=http://localhost:3000 for development
• Set NEXTAUTH_URL=https://yourdomain.com for production
• Ensure the URL matches your actual application URL

---

Create a dashboard

Create custom visualizations with flexible widgets, queries, and real-time AI monitoring

Manage prompts

Version, deploy, and collaborate on prompts with centralized management and tracking

LLM playground

Compare cost, duration, and response tokens across different LLMs to find the most efficient model