Allow users to sign up and log in via GitHub, GitLab, or Google instead of requiring email + password. This extends the existing Signup API (POST /api/v1/signup) and adds social login buttons to the DeployHQ login and signup pages.

Why all three? GitHub is most relevant for developers. GitLab is developer-focused and already used for repo linking. Google provides broadest coverage for non-developer team members. (Google SAML SSO is a separate enterprise feature — admin-configured, per-account, enforceable. Social login with Google is for individual users without enterprise SSO.)

DeployHQ uses a two-tier auth system:

Social login must live in Identity because that's where users go to log in. Without social buttons there, a user who signed up with GitHub would have no way to log back in (they have no password).

#Key Insight: SAML Already Solved This

Identity already has a full SAML SSO implementation that handles:

• Passwordless user creation (random password, auto-verify email)
• External identity linking (SamlIdentity model)
• Cross-service session bridging (LoginToken — 30-second single-use tokens)
• JIT (Just-In-Time) user provisioning

Social login follows the exact same pattern — it's a new provider type feeding into existing infrastructure, not a new auth system.

#Flow 1: Browser Login (Existing Account)

This is how a user with an existing DeployHQ account logs in with GitHub:

Key points:

• Users see the login form on DeployHQ (deployhq.com/login), not on Identity directly
• Clicking "Sign in with GitHub" redirects to Identity with the account context (same as the existing SSO button)
• The access token never leaves the Identity server
• LoginToken is the same session bridge used by SAML SSO
• Main App needs zero changes for this flow — token consumption already works

#Flow 2: API Signup (New Account)

This is how a new user signs up via the API (used by CLI, MCP, or browser-based signup):

Key points:

• No LoginToken redirect needed — the API returns the account directly
• PKCE is required for all API callers (the signup endpoint is public)
• The authorization code is single-use and short-lived (~10 minutes)
• Identity exchanges it server-side — the access token never reaches the client

#Flow 3: Browser Signup (New Account)

This is how a new user signs up with GitHub through the DeployHQ website:

Key points:

• User starts on deployhq.com/signup, not the login page
• No password needed — Identity creates user with random password + auto-verified email
• After OAuth completes, DeployHQ creates the account and all resources (same as email/password signup)
• User is logged in immediately after account creation

#Flow 4: Account Linking Decision Tree

How Identity decides what to do when a social provider returns a user:

#Scenario 1: New Developer Signs Up with GitHub

Context: A developer discovers DeployHQ and wants to sign up using their GitHub account via the CLI.

1. Developer runs dhq signup --github
2. CLI generates PKCE code_verifier and code_challenge
3. CLI opens browser to https://github.com/login/oauth/authorize?client_id=...&scope=user:email&code_challenge=...
4. Developer clicks "Authorize" on GitHub
5. GitHub redirects to http://localhost:8432/callback?code=abc123
6. CLI captures the code and sends:
   copy

   POST /api/v1/signup
   {
     "provider": "github",
     "provider_code": "abc123",
     "redirect_uri": "http://localhost:8432/callback",
     "code_verifier": "dBjftJeZ4CVP..."
   }
   

7. Identity exchanges the code, finds the developer's GitHub profile (email: [email protected], verified)
8. Identity creates a new user (random password, email auto-verified) + OauthIdentity record
9. SignupService creates the billing account, DeployHQ account, API key, and SSH key
10. CLI receives the full response and displays: "Account created! Your API key is: ..."

Result: Developer has a DeployHQ account with no password. They can log in with GitHub, or use password reset to set one.

#Scenario 2: Existing User Links GitHub to Their Account

Context: A user already has a DeployHQ account (signed up with email/password). They click "Sign in with GitHub" on the login page.

1. User visits deployhq.com/login
2. Clicks "Sign in with GitHub" (redirects to Identity)
3. Authorizes on GitHub (email: [email protected], verified)
4. Identity calls User.locate("[email protected]") — finds the existing user
5. Identity creates an OauthIdentity record linking GitHub UID to the existing user
6. Identity creates a LoginToken and redirects to DeployHQ
7. User is logged in

Result: User now has two login methods: email/password AND GitHub. Both continue to work.

#Scenario 3: Social Signup Hits 2FA

Context: A developer's GitHub email matches an existing Identity user who has 2FA enabled.

1. Client sends POST /api/v1/signup with GitHub auth code
2. Identity finds the existing user via email, notes 2FA is enabled
3. API returns HTTP 202:
   copy

   {
     "status": "two_factor_required",
     "two_factor_token": "tf_xxxxxxxxxxxx",
     "message": "Two-factor authentication is required.",
     "next_step": {
       "method": "POST",
       "url": "/api/v1/signup/verify_2fa",
       "params": { "two_factor_token": "tf_xxx", "two_factor_code": "from authenticator" }
     }
   }
   

4. Client prompts for 2FA code, sends:
   copy

   POST /api/v1/signup/verify_2fa
   { "two_factor_token": "tf_xxxxxxxxxxxx", "two_factor_code": "123456" }
   

5. Identity validates 2FA, returns user hash
6. SignupService creates the account
7. Client receives full signup response

#Scenario 4: GitHub Returns No Verified Email

Context: A user's GitHub account has no verified email (or email is set to private with no public verified email).

1. Client sends POST /api/v1/signup with GitHub auth code
2. Identity exchanges code, calls GET /user/emails
3. GitHub returns emails but none have verified: true
4. API returns HTTP 422:
   copy

   {
     "error": "provider_email_unverified",
     "message": "Your email address is not verified with GitHub. Please verify your email at github.com and try again."
   }
   

Result: No account created. User must verify their email on GitHub first.

#Scenario 5: Social-Only User Loses GitHub Access

Context: A user signed up with GitHub only (no password). Their GitHub account gets compromised and they lose access.

1. User cannot click "Sign in with GitHub" (account compromised)
2. User clicks "Forgot password?" on the Identity login page
3. Identity sends a password reset email to their verified email (auto-verified at signup)
4. User sets a new password via the reset link
5. User can now log in with email/password

Result: Recovery works because Identity auto-verified the email at social signup.

#Scenario 6: Invited User Claims Account with GitHub

Context: An account admin invites [email protected]. The invited user wants to claim their account using GitHub instead of setting a password.

1. Admin invites user -> email sent with link to /users/claim/{invite_code}
2. User clicks invite link -> sees claim form with password fields, SSO button, and social login buttons
3. User clicks "Sign up with GitHub"
4. OAuth flow: GitHub authorizes, Identity provisions user (same as normal social signup)
5. Claim controller links the DeployHQ user to the new Identity account (atech_identity_key), clears invite code, marks as activated
6. User is logged in to their new account

Result: Invited user has a DeployHQ account linked to GitHub. No password set. Same as the existing SSO claim path, but with GitHub/GitLab instead of SAML.

#Scenario 7: User Tries Both Auth Methods Simultaneously

Context: A client sends both email/password and provider params in the same request.

1. Client sends:
   copy

   {
     "email": "[email protected]",
     "password": "secret123",
     "provider": "github",
     "provider_code": "abc123",
     "redirect_uri": "...",
     "code_verifier": "..."
   }
   

2. API returns HTTP 422:
   copy

   {
     "error": "invalid_params",
     "message": "Cannot use both email/password and social login in the same request"
   }
   

#Social Signup

POST /api/v1/signup

Request (social login variant):

Success response (201):

{
  "account": { "identifier": "...", "name": "...", "subdomain": "...", "url": "..." },
  "api_key": "...",
  "ssh_public_key": { "id": 1, "public_key": "ssh-rsa ...", "fingerprint": "..." },
  "oauth_urls": { "github": "...", "gitlab": "...", "bitbucket": "..." },
  "mcp_config": { "account": "...", "api_key": "...", "email": "..." },
  "email_verified": true
}

Error responses:

#2FA Completion

POST /api/v1/signup/verify_2fa

Returns the same 201 signup response on success, or 422 on failure.

#GitHub

#GitLab

#Google

OAuth App credentials: You register a "GitHub OAuth App" (and a "GitLab OAuth App") in each provider's developer settings. This gives you a client_id + client_secret that identifies DeployHQ as an application. Every user who clicks "Sign up with GitHub" authenticates through this same OAuth App — each user authorizes with their own GitHub account, but the app credentials just identify DeployHQ. This is the same model the main app already uses for repo linking (config/external_api_keys.yml). Identity needs these credentials to exchange authorization codes server-side. Storage: either Identity's own config file or fetched from the main app's internal API (like SAML config). Determine during spike.

Login page visibility: Social login buttons show for all accounts that don't have enforce_sso: true. When SSO is enforced, the login page already hides password login - social buttons should not appear either. No new per-account toggle needed.

Signup API: Always available regardless of account SSO settings (new accounts don't have SSO configured yet).

#Token Handling

• Authorization codes exchanged server-side only (Identity -> Provider)
• Access tokens never sent to or from the client
• Access tokens not stored in the database (not needed after profile fetch)
• PKCE required for all API callers (public endpoint)

#Replay & CSRF Protection

• Browser flow: state parameter in session (same as SAML's InResponseTo)
• API flow: Codes are single-use + bound to redirect_uri + PKCE code_verifier

#Log Filtering

Identity's ApiController logs decoded params and sends to Sentry. Must add provider_code, access_token, code_verifier to filter lists before deploying social login code.

#Account Linking (diverges from SAML)

• New users (no existing Identity account): auto-create user + OauthIdentity. Safe — no existing account to take over.
• Existing users (Identity account already exists for this email): do NOT auto-link. Send a confirmation email instead. User must click to confirm the link. This prevents account takeover — anyone can create a GitHub account with your email.
• Returning social users (OauthIdentity already exists for provider+uid): return existing user immediately.
• Only with verified, deliverable provider emails — unverified and noreply emails rejected.

#Email Selection (GitHub-specific)

• Prefer: primary: true AND verified: true AND NOT @users.noreply.github.com
• Fallback: any verified: true AND NOT noreply
• Reject with provider_email_not_deliverable if only noreply emails (breaks password-reset recovery)

#redirect_uri Allowlist

• Browser clients: pre-registered HTTPS origins only
• CLI/MCP: http://localhost:* and http://127.0.0.1:* (per RFC 8252)
• Everything else rejected with invalid_redirect_uri

#Rate Limiting

• Rack::Attack: 3 signups per IP per hour + 10 code exchanges per IP per hour
• Circuit breaker: trip after 3 provider 5xx in 60 seconds, 5-minute cooldown
• Per-provider feature flag kill switch

#2FA Policy

• Social login respects 2FA: if enabled, user must still complete 2FA (same as SAML)
• Browser: temporary auth-only session + existing 2FA prompt page
• API: returns two_factor_required + token for follow-up call

#Recovery for Social-Only Users

• Password reset via email works (email is auto-verified at signup)
• Phase 3 adds "Set password" hint in account settings

These are chosen for consistency with existing SAML behavior:

Social login is not enforced at the account level. Unlike SAML SSO (which supports enforce_sso: true to force all users through the IdP), social login is an optional convenience method. Users can always fall back to email/password. This is intentional:

• SSO enforcement exists for compliance (centralized auth, offboarding control, audit trails). Social login serves a different purpose: reducing signup/login friction for developers.
• Enforcing GitHub/GitLab login would require all team members to have accounts on those platforms, which isn't reasonable.
• Social login adds an OauthIdentity link — it doesn't replace or disable password authentication.

Team should confirm or override during the spike (Task 1.1).

#Phase 1: Identity Service (~8.5 days)

#Phase 2: Main App (~5 days)

#Phase 2.5: Invite Claim Flow (~1 day)

#Phase 3: Edge Cases (~2 days)

#Phase 4: Documentation & CLI (~3 days)

Total: ~23 days = ~4.5 weeks

Phase 1 grew by ~3 days due to security controls promoted from Phase 3 (redirect_uri allowlist, rate limiting, account link confirmation, security review gate).

MVP (2.5 weeks): GitHub only, defer GitLab + Google + CLI + "Set password" UI.

#Identity Service (19 tests)

#Main App (18 tests)

• Per-provider feature flags: social_login_github, social_login_gitlab, social_login_google — each can be enabled/disabled independently without deploying code
• Staged rollout: enable for internal accounts first, then gradually expand
• Kill switch: disable all social signup instantly if issues detected
• Support runbook: how to unlink a mislinked OauthIdentity, disable for a specific user, investigate failed signups
• Rollback: disabling the flag stops new social signups but doesn't break existing linked users (they fall back to password reset)

1. Review defaults: Auto-link by verified email, 2FA required if enabled, PKCE required for all API callers. Override any of these?

Everything in the "Reference" column already exists and works in production: