gh-varaku1012-aditi-code-plugins-auth0-oauth-plugin/commands/oauth-setup-auth0.md

description

description
Interactive Auth0 setup wizard for configuring OAuth applications, connections, and tenant settings

Auth0 OAuth Setup Wizard

Interactive guided setup for Auth0 authentication from scratch.

Quick Start

/oauth-setup-auth0

This will walk you through:

1. Auth0 Tenant Creation - Create new Auth0 account/tenant
2. Application Configuration - Set up app (SPA, Web, Mobile, M2M)
3. Connection Setup - Configure database, social, enterprise login
4. Callback URL Configuration - Set up redirect URIs
5. Basic Security - Enable MFA, set token expiration
6. Environment Variables - Generate .env file template

Step-by-Step Wizard

Step 1: Auth0 Tenant Setup

If you don't have an Auth0 account:

1. Visit: https://auth0.com/signup
2. Create account with:
   • Email: Your business email
   • Password: Strong password
   • Company: Your company name
3. Choose region: US, EU, or AU
4. Create tenant - Auth0 generates unique domain:
   • Example: mycompany.auth0.com

What you'll get:

• Auth0 Dashboard access
• Domain: YOUR_DOMAIN.auth0.com
• Client ID & Secret for dashboard

---

Step 2: Select Application Type

Choose based on your tech stack:

Option 1: Single Page Application (SPA)

For: React, Vue, Angular, Svelte, Next.js (client-side)

Characteristics:

• Code runs in browser
• Public client (no secret needed)
• OAuth Flow: Authorization Code + PKCE
• Token Storage: In-memory (secure)

Setup:

Auth0 Dashboard → Applications → Create Application
Name: My React App
Type: Single Page Application

Settings:
- Allowed Callback URLs: http://localhost:3000/callback
- Allowed Logout URLs: http://localhost:3000
- Allowed Web Origins: http://localhost:3000
- Token Endpoint Authentication: None

Option 2: Web Application (Server-Side)

For: Next.js, Express, Django, Rails (with server)

Characteristics:

• Code runs on server
• Confidential client (has secret)
• OAuth Flow: Authorization Code (no PKCE needed)
• Token Storage: HTTP-only cookies

Setup:

Auth0 Dashboard → Applications → Create Application
Name: My Next.js App
Type: Regular Web Applications

Settings:
- Allowed Callback URLs: http://localhost:3000/api/auth/callback
- Allowed Logout URLs: http://localhost:3000
- Token Endpoint Authentication: Post
- Secret: [Auto-generated, copy to .env]

Option 3: Machine-to-Machine (M2M)

For: Backend services, scheduled jobs, CLI tools

Characteristics:

• No user interaction
• Confidential client
• OAuth Flow: Client Credentials
• Use Case: Calling Auth0 Management API

Setup:

Auth0 Dashboard → Applications → Create Application
Name: My Backend Service
Type: Machine-to-Machine Applications

Settings:
- Grant Types: client_credentials
- Audience: https://YOUR_DOMAIN/api/v2/
- Secret: [Auto-generated, copy to .env]

Option 4: Native Application

For: iOS, Android, React Native apps

Characteristics:

• Runs on device
• Public client (no secret)
• OAuth Flow: Authorization Code + PKCE
• Callback: Custom URL scheme or App Link

Setup:

Auth0 Dashboard → Applications → Create Application
Name: My Mobile App
Type: Native

Settings:
- Allowed Callback URLs: com.myapp://callback
- Allowed Logout URLs: com.myapp://logout
- Token Endpoint Authentication: None

---

Step 3: Configure Connections

Choose how users authenticate:

Option 1: Username/Password Database

Built-in Auth0 database

Enable:

Auth0 Dashboard → Connections → Database → Username-Password-Authentication

Settings:
- Allow Signup: Yes (if you want user self-registration)
- Require Email Verification: Yes
- Password Policy: Good (mixed case, numbers, symbols)
- Disable signup for: [Your application]

Usage:

Users can sign up at: YOUR_DOMAIN/signup
Or you create users via API

---

Option 2: Social Connections

Let users login with Google, GitHub, etc.

Google OAuth Setup

1. Create Google Cloud project:

   • Visit: https://console.cloud.google.com
   • Create new project: "My App Auth"
   • Enable Google+ API

2. Create OAuth credentials:

   • APIs & Services → Credentials → Create OAuth 2.0 Client ID
   • Authorized redirect URIs:
     • https://YOUR_DOMAIN/login/callback
     • https://YOUR_DOMAIN/login/callback?connection=google-oauth2
   • Copy: Client ID and Client Secret

3. Add to Auth0:

   Auth0 Dashboard → Connections → Social → Google
   
   Client ID: [Paste from Google Cloud]
   Client Secret: [Paste from Google Cloud]
   
   Enable for: [Your application]
   

GitHub OAuth Setup

1. Create GitHub OAuth App:

   • Visit: https://github.com/settings/developers
   • Register new OAuth application
   • Authorization callback URL:
     • https://YOUR_DOMAIN/login/callback
   • Copy: Client ID and Client Secret

2. Add to Auth0:

   Auth0 Dashboard → Connections → Social → GitHub
   
   Client ID: [Paste from GitHub]
   Client Secret: [Paste from GitHub]
   
   Enable for: [Your application]
   

---

Option 3: Enterprise Connections (Active Directory/LDAP)

For company employees using company email

Setup Active Directory:

Auth0 Dashboard → Connections → Enterprise → Active Directory/LDAP

Name: Company AD
LDAP URL: ldap://ad.company.com:389
Bind DN: admin@company.com
Bind Password: [AD admin password]
Base DN: cn=users,dc=company,dc=com

Mapping:
- Email: mail
- Name: displayName
- Username: sAMAccountName

Enable for: [Your application]

Result: Users can login with company credentials, no password duplication

---

Step 4: Create API

If your frontend needs to call protected APIs:

Auth0 Dashboard → APIs → Create API

Name: My API
Identifier: https://api.myapp.com
Signing Algorithm: RS256

Scopes:
+ read:items (Read access to items)
+ write:items (Write access to items)
+ delete:items (Delete items)
+ admin (Full admin access)

Usage in App:

// Request these scopes during login
Auth0Provider({
  authorizationParams: {
    scope: 'openid profile email read:items write:items'
  }
})

// Access token will include these scopes
// Backend validates scopes before allowing access

---

Step 5: Basic Security Configuration

Enable Multi-Factor Authentication (MFA)

Auth0 Dashboard → Connections → Authenticators

Enable:
- Google Authenticator ✅
- SMS (optional)
- Email OTP

For application:
- Require MFA: Yes / No / Per-user rule

Optional: Require MFA for certain users:

// Auth0 Rule: Enforce MFA for admin users
module.exports = function(user, context, callback) {
  if (user.email.endsWith('@admin.company.com')) {
    context.multifactor = {
      provider: 'google-authenticator',
      allowRememberBrowser: false
    }
  }
  callback(null, user, context)
}

---

Set Token Expiration

Auth0 Dashboard → Applications → Settings → Advanced

Token Settings:
- ID Token Expiration: 36000 (10 hours)
- Access Token Expiration: 600 (10 minutes) ← IMPORTANT
- Refresh Token Expiration: 2592000 (30 days)
- Refresh Token Rotation: Enabled ✅

Why short access token?

• If leaked, attacker has limited time window
• Refresh tokens can be rotated automatically
• Best practice: 5-15 minutes

---

Enable HTTPS for Callback URLs

Auth0 Dashboard → Applications → Settings

Allowed Callback URLs:
- Production: https://myapp.com/callback ✅
- Staging: https://staging.myapp.com/callback ✅
- Local dev: http://localhost:3000/callback (only for dev)

Allowed Logout URLs:
- Production: https://myapp.com ✅
- Staging: https://staging.myapp.com ✅
- Local dev: http://localhost:3000 (only for dev)

---

Step 6: Generate Environment Variables

Based on your setup, create .env.local:

# Auth0 Configuration
AUTH0_DOMAIN=YOUR_DOMAIN.auth0.com
AUTH0_CLIENT_ID=YOUR_CLIENT_ID
AUTH0_CLIENT_SECRET=YOUR_CLIENT_SECRET
AUTH0_CALLBACK_URL=http://localhost:3000/callback

# For Next.js
AUTH0_BASE_URL=http://localhost:3000
AUTH0_SECRET=use [node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"]

# For APIs
AUTH0_AUDIENCE=https://api.myapp.com
AUTH0_SCOPE=openid profile email read:items

# API Configuration
API_URL=http://localhost:3001

---

Quick Reference

URLs to Save

• Auth0 Dashboard: https://manage.auth0.com
• Your Tenant: https://YOUR_DOMAIN.auth0.com
• Login Page: https://YOUR_DOMAIN.auth0.com/login

Common Task Commands

View users:

Auth0 Dashboard → User Management → Users

View logs:

Auth0 Dashboard → Logs (Real-time logs of auth events)

View rules:

Auth0 Dashboard → Rules (Custom logic for auth flow)

Reset user password:

Auth0 Dashboard → Users → Select user → Actions → Reset password

---

Verification Checklist

• Auth0 tenant created
• Application configured (SPA/Web/M2M/Native)
• Callback URLs set (http://localhost:3000/callback)
• Logout URLs set (http://localhost:3000)
• Connection enabled (Database/Google/GitHub/AD)
• API created with scopes
• MFA configured
• Token expiration set (10 min for access tokens)
• Environment variables generated
• Test login from Auth0 dashboard works

---

Next Steps

After setup completes:

1. Install SDK for your framework:

   • React: /oauth-implement react
   • Next.js: /oauth-implement nextjs
   • Node.js: /oauth-implement nodejs

2. Run security audit:

   • /oauth-security-audit

3. Test your implementation:

   • Try login flow
   • Check token in browser dev tools
   • Verify API access

4. Deploy to production:

   • Update callback URLs to production domain
   • Update environment variables
   • Enable HTTPS everywhere
   • Consider Auth0 compliance (GDPR, HIPAA, SOC2)

---

Troubleshooting

Q: Callback URL mismatch error? A: Ensure your callback URL in Auth0 exactly matches redirect_uri in your app (including http/https and port)

Q: Connection not showing in login? A: Check that connection is enabled for your application (Connections → Select connection → Applications toggle)

Q: Can't create users via signup? A: Ensure "Allow Signup" is enabled in Database connection settings

Q: Users can't login with social connection? A: Verify social connection is enabled for your application

---

Status: Setup wizard complete! Next command: /oauth-implement [framework] to add auth to your app