[Feature Request]: Authentication & Authorization - GitHub SSO Integration Tutorial (Depends on #220)

[crivetimihai]

Authentication & Authorization – GitHub SSO Integration

🧭 Epic

Depends on: Add SSO & IdP-Issued Tokens to Gateway
Title: Turn-key GitHub SSO for the Gateway
Goal: Ship a plug-and-play GitHub identity-provider module plus step-by-step docs so that, once the generic SSO framework is in place, an operator can enable GitHub login & RBAC in ≤ 10 minutes by dropping a handful of env-vars.
Why now: GitHub is the canonical developer identity source for most teams. Offering a first-class, documented integration right after core SSO lands will unblock adoption and avoid every project reinventing the same “GitHub OAuth callback” glue.

---

🧭 Type of Feature

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

---

🙋‍♂️ User Story 1 – One-click GitHub Login

As a: Platform engineer
I want: to set GITHUB_OIDC_CLIENT_ID/SECRET + GITHUB_ORG in my .env and have the UI redirect to GitHub OAuth automatically
So that: users authenticate with the same account they push code with.

✅ Acceptance Criteria

Scenario: Successful GitHub OAuth login
Given the generic SSO feature-flag is ON
And the GitHub provider is configured with valid client-id/secret
When an unauthenticated browser visits "/"
Then the gateway MUST redirect to GitHub's consent screen
And MUST honour the received OIDC code
And MUST create an encrypted session cookie carrying the user's GH login & teams

---

🙋‍♂️ User Story 2 – Team-to-Role Mapping

As a: Security admin
I want: GitHub organisation teams to map automatically to RBAC groups
So that: membership in tools-maintainers on GitHub grants the mcp-admin role in the gateway.

✅ Acceptance Criteria

Scenario: Enforce RBAC via GitHub team
Given a user belongs to GitHub team "finance-analysts"
When the callback finishes
Then the gateway MUST attach group "finance-analysts" to the session
And subsequent API calls MUST evaluate RBAC policies using that group list

---

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

As an: Operator
I want: a README section with copy-paste cURL/Make targets & screenshots for creating the GitHub OAuth App
So that: I can enable the integration without reading GitHub docs end-to-end.

✅ Acceptance Criteria

• README.md gains a “GitHub SSO” subsection directly after the existing Authentication table .

• It lists the new variables:

  Setting	Description	Example
  GITHUB_OIDC_CLIENT_ID	OAuth App / GitHub App Client ID	Iv1.abc123
  GITHUB_OIDC_CLIENT_SECRET	OAuth Client secret	shhh_very_secret
  GITHUB_ORG	Restrict login to a single organisation	my-company
  GITHUB_TEAM_CLAIM	(opt) Comma-sep team slugs treated as groups	platform,finance
  GITHUB_CALLBACK_PATH	Callback endpoint exposed by gateway	/auth/github/callback

• Includes a Make target make github-sso-demo that spins up a local tunnel (e.g. ngrok) and echoes the callback URL.

---

📐 Design Sketch

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

Loading

Component	Change	Detail
auth_providers/github.py	NEW	OIDC discovery, code-exchange & token verification
auth_service.py	UPDATE	Register “github” provider under the generic SSO plugin interface
DB	UPDATE	Store gh_id, login, avatar_url in users table
Config	ADD	GITHUB_* vars shown above

---

🔄 Roll-out Plan

1. Phase 0: Feature-flag EXPERIMENTAL_SSO_GITHUB (off by default).
2. Phase 1: Ship docs & terraform-friendly env-var examples.
3. Phase 2: Promote to Supported once three gateways run it in staging.
4. Phase 3: Deprecate bespoke GitHub login scripts; rely solely on the provider.

---

📝 Spec-Draft Clauses

1. GitHub Auth Clause – “Gateways MUST support OAuth 2.0 Authorisation Code flow with PKCE for github.com and GitHub Enterprise Server ≥ 3.11.”
2. Team Claim Clause – “When the teams scope is granted, the gateway SHOULD translate <org>/<team> slugs into RBAC groups of the same name.”

---

📣 Next Steps

• Prototype provider against GitHub public cloud & GHES.
• Integrate unit-tests mocking /login/oauth/access_token & /user/orgs endpoints.
• Draft README insert & record a 60 sec asciicast demo.

This epic ensures that - once generic SSO groundwork ships - enabling GitHub SSO is literally a five-line diff in .env plus the documented callback route.