Security Review: Sourcegraph GitHub OAuth Integration
Executive Summary
This document provides a comprehensive security analysis of Sourcegraph's GitHub OAuth authentication flow, detailing the permissions requested, their purpose, and security implications.
TL;DR
Sourcegraph's GitHub OAuth implementation follows security best practices:
Principle of Least Privilege: Only requests the scopes necessary for configured features
Defense in Depth: Multiple validation layers (email, org, team, SSO)
PKCE Support: Protection against authorization code interception
Conditional Scoping: Adapts to deployment configuration
SSO Integration: Enforces enterprise SSO requirements
NOTE: All this applies to GitHub App authentication as well. GitHub Apps have the added benefit that user OAuth tokens are scoped to access only repositories the GitHub App has explicit access to.
1. OAuth Scopes Requested
Sourcegraph's GitHub OAuth integration requests different scopes based on the instance configuration.
1.1 Always Requested Scopes
Scope | Purpose | Permissions Granted |
|---|---|---|
user:email repo | User identification Repository access | • Read users' email addresses • Access email verification status • Read public repositories • Read private repositories • Access repository metadata • Read commit statuses • Read repository invitations |
1.2 Conditionally Requested Scopes
Scope | Condition | Purpose | Permissions Granted |
|---|---|---|---|
read:org | • allowOrgs configured • • | Organization membership verification | • Read organization memberships • Read team memberships • Read organization projects • Access organization teams list |
2. OAuth Flow Sequence
The complete authentication flow involves multiple validation steps:
2.1 Configuration Options
The GitHub OAuth provider supports several configuration options:
Field | Type | Purpose | Security Impact |
|---|---|---|---|
allowOrgs | []string | Restrict access to specific GitHub organizations | Prevents unauthorized users from accessing the instance |
allowOrgsMap | map[string][]string | Restrict access to specific GitHub teams | Granular team-level access control |
allowSignup | bool | Allow new user registration | Controls whether new users can self-register |
requiredSsoOrgs | []string | Require SAML SSO authorization for specific orgs | Enforces SSO for enterprise security compliance |
allowGroupsPermissionsSync | bool | Enable team/org permissions synchronization | Automates repository permission inheritance |
2.2 Authentication Validation Steps
After receiving the OAuth token, Sourcegraph performs several security checks:
Scope Verification
Validates that GitHub granted the requested scopes
Stores granted scopes with the external account
Email Verification
Security Check: Ensures at least one verified email exists
Rejection Reason: "Could not get verified email for GitHub user"
This prevents users from adding unverified email addresses to GitHub and from using them to gain access.
Organization Membership - If allowOrgs is configured
Validates user belongs to the allowed organizations
Rejection Reason: "User does not belong to allowed GitHub organizations or teams"
Allows admins to restrict access to Sourcegraph via GitHub orgs
Team Membership - If allowOrgsMap configured
Validates user belongs to specific teams within organizations
More granular than organization-level checks
SAML SSO Authorization
Validates SSO authorization via X-GitHub-SSO header
Two modes:
Specific orgs: Requires SSO for listed organization IDs
"all" mode: Rejects if ANY unauthorized SSO orgs are detected
Rejection Reason: "Authentication rejected because you have unauthorized GitHub SSO organizations"
Common when SSO has been configured on GitHub itself, which could lead to users not having access to the correct repositories on Sourcegraph
3. Security Controls
3.1 Access Control Mechanisms
Implemented Controls:
Email Verification Requirement
Prevents unverified accounts from authenticating
Organization Allowlist
Restricts access to members of specified GitHub organizations
Team-Based Access Control
Enables fine-grained team-level restrictions
SAML SSO Enforcement
Ensures users have authorized SSO for required organizations
Detects unauthorized organizations via GitHub's X-GitHub-SSO response header
PKCE Support
Implements Proof Key for Code Exchange for enhanced security
4. Permission Scope Analysis
4.1 user:email Scope
What Sourcegraph Can Access:
✅ Read users' email addresses
✅ Determine which emails are verified
What Sourcegraph CANNOT Access:
❌ Modify email addresses
❌ Add/remove emails
Used For:
User identification during authentication
Linking GitHub accounts to Sourcegraph accounts via verified email
Validating email verification status
4.2 repo Scope
What Sourcegraph Can Access:
✅ Read code from public repositories
✅ Read code from private repositories (user has access to)
✅ Read repository metadata (description, topics, etc.)
✅ Read commit statuses
✅ Read deployment information
What Sourcegraph CANNOT Access:
❌ Write to repositories
❌ Create/delete repositories
❌ Modify repository settings
❌ Push commits
⚠️ Security Consideration: This is a broad read-only scope that grants access to all repositories the user can access on GitHub, including private repositories. This is necessary for:
Code search across private repositories
Repository syncing
Code intelligence features
Mitigation:
Only requested on self-hosted instances (not Sourcegraph.com)
Users must explicitly approve this scope during OAuth consent
4.3 read:org Scope
What Sourcegraph Can Access:
✅ Read organization memberships
✅ Read team memberships
✅ Read organization projects
✅ List teams within organizations
What Sourcegraph CANNOT Access:
❌ Modify organization settings
❌ Add/remove organization members
❌ Create/delete teams
Used For:
Validating user belongs to allowed organizations (allowOrgs)
Validating user belongs to allowed teams (allowOrgsMap)
Syncing team/organization permissions (allowGroupsPermissionsSync)