Authentication & Authorization – Google SSO Integration

🧭 Epic

Depends on: Add SSO & IdP-Issued Tokens to Gateway
Title: Turn-key Google SSO for the Gateway
Goal: Ship a ready-made Google OpenID Connect provider plus walkthrough docs so ops teams can enable Gmail/Workspace login in ≤ 10 minutes by dropping a few env-vars.
Why now: Many orgs live in Google Workspace; re-using that identity source slashes onboarding toil and removes yet another password.

🧭 Type of Feature

• Developer-experience / Docs
• New functionality (pluggable IdP)
• Security hardening

🙋‍♂️ User Story 1 – Fast Google Login

As a: Platform engineer
I want: to set GOOGLE_OIDC_CLIENT_ID/SECRET and (optionally) GOOGLE_WORKSPACE_DOMAIN in my .env, and have the UI redirect to Google’s consent screen
So that: users authenticate with the same account they read mail with.

✅ Acceptance Criteria

Scenario: Successful Google OAuth login
Given generic SSO is enabled
And the Google provider has a valid client-id & secret
When an unauthenticated browser hits "/"
Then the gateway MUST redirect to https://accounts.google.com/o/oauth2/v2/auth
And after consent MUST exchange the code for an ID-token
And MUST create an encrypted session cookie containing sub, email, hd claim & groups

🙋‍♂️ User Story 2 – Workspace Domain Whitelisting

As a: Security admin
I want: to restrict login to my company’s Workspace domain
So that: personal @gmail.com accounts cannot reach the gateway.

✅ Acceptance Criteria

Scenario: Reject foreign Gmail accounts
Given GOOGLE_WORKSPACE_DOMAIN is "my-company.com"
When a user signs in with alice@gmail.com
Then the gateway MUST respond 403 "forbidden_domain"

🙋‍♂️ User Story 3 – Google Groups → RBAC

As a: Security admin
I want: Google Groups memberships mapped automatically to RBAC groups
So that: membership in finance-analysts@my-company.com unlocks the same scope in the gateway.

✅ Acceptance Criteria

Scenario: RBAC via Google group
Given a user belongs to Google group "finance-analysts@my-company.com"
When the callback completes
Then "finance-analysts" MUST appear in the session group list
And RBAC policy evaluation MUST succeed for that scope

🙋‍♂️ User Story 4 – Copy-paste Setup Guide

As an: Operator
I want: README steps with screenshots of Google Cloud Console and a Make target that spins up a tunnel & prints the callback URL
So that: I can enable the feature without trawling external docs.

✅ Acceptance Criteria

• README.md gains a “Google SSO” block right next to GitHub SSO.
  It lists the new variables:

  Setting	Description	Example
  GOOGLE_OIDC_CLIENT_ID	OAuth 2.0 Client ID	1234567890.apps.googleusercontent.com
  GOOGLE_OIDC_CLIENT_SECRET	OAuth Client secret	super_secret
  GOOGLE_WORKSPACE_DOMAIN	(opt) Allowed domain	my-company.com
  GOOGLE_GROUPS_SCOPE	(opt) Scope to fetch groups	https://www.googleapis.com/auth/admin.directory.group.readonly
  GOOGLE_CALLBACK_PATH	Callback path	/auth/google/callback

  The style matches the existing env-var tables .

• A Make target make google-sso-demo opens an ngrok/localhost.run tunnel and echoes the redirect URI.

📐 Design Sketch

flowchart TD
    Browser -->|OAuth 2.0 / OIDC| Google[(Google Identity)]
    Google --> AuthSvc[Gateway Auth Service]
    subgraph Gateway
        AuthSvc --> RBAC[Role Mapper]
        RBAC --> API["UI / JSON-RPC / REST"]
    end

🔄 Roll-out Plan

1. Phase 0: Feature-flag EXPERIMENTAL_SSO_GOOGLE off.
2. Phase 1: Ship docs + sample .env.google.example.
3. Phase 2: Promote to Supported after ≥ 2 production clusters run it.
4. Phase 3: Remove any bespoke Google login scripts.

📝 Spec-Draft Clauses

1. Google Auth Clause – “Gateways MUST implement OAuth 2.0 Authorisation Code with PKCE against Google Identity endpoints.”
2. Domain Restriction Clause – “If GOOGLE_WORKSPACE_DOMAIN is set, non-matching hd or email domains MUST be rejected with 403.”
3. Groups Clause – “When GOOGLE_GROUPS_SCOPE is granted, returned group aliases SHOULD map 1-to-1 to RBAC groups.”

📣 Next Steps

• Prototype provider with google-auth-oauthlib; cover both consumer Gmail & Workspace tenants.
• Unit-test tokeninfo & People API mocks.
• Record a 90 sec asciinema demo.