Architectural Overview of Gitter's GitHub/GitLab Identity Integration

Problem and Takeaway

Gitter must let developers join a chat community using their existing GitHub or GitLab credentials, keeping password data out of its own storage. The key takeaway is that OAuth 2.0 provides a secure, standards-based way to delegate authentication while preserving data boundaries.

Requirements

• External provider (GitHub or GitLab) must handle user authentication.
• Gitter must map the provider’s unique user identifier to an internal profile.
• Community access should be gated by membership in a specific GitHub organization or repository.
• The design must assume the external provider is the authoritative source for identity and group membership.
• Operational checks are needed to detect API rate-limit errors or version incompatibilities.

Smallest Suitable Design

The minimal architecture consists of three components:

1. OAuth Provider – GitHub or GitLab, which issues short-lived access tokens.
2. Token Exchange Service – Gitter’s backend that validates the token and extracts the user ID and organization membership.
3. Mapping Store – a lightweight database table that links the provider’s user ID to Gitter’s internal user ID and stores the community gating rule.

This design avoids storing passwords and keeps the trust relationship external.

Trust and Data Boundaries

Trust is placed in the external provider; Gitter only stores the derived identifier and the community rule. The data boundary separates authentication data (provider-issued) from chat history and metadata (Gitter-managed).

Operational Checks

To verify the integration works, perform the following checks:

• Confirm the linked OAuth provider in the Gitter account settings.
• Run a token introspection request to ensure the token includes the expected organization claim.
• Observe the login flow for any delay caused by rate limiting.

Example command (run in a terminal with network access and a valid bearer token):

curl -s -H "Authorization: Bearer $TOKEN" \
  https://api.github.com/user

Replace $TOKEN with a token that has the read:org scope. A successful response containing the organizations field confirms the user belongs to at least one organization that Gitter can use for gating.

Failure Modes

• API rate limiting from GitHub or GitLab can delay user synchronization or block login attempts.
• Version changes in the provider’s OAuth endpoints may break token validation logic.
• Privacy settings that restrict the scopes returned by the provider can prevent Gitter from seeing organization membership.

Conditions That Would Change the Design

• If the organization adopts SAML or OpenID Connect instead of OAuth 2.0, the token exchange step must be replaced.
• If compliance policies require local password storage, the design would need to add a secure password vault, altering the trust model.
• If the community gating rule shifts from organization membership to repository permission, the mapping store must accommodate additional criteria.

Concrete Example

Consider a GitHub user with ID U12345 who belongs to organization AcmeDev. Gitter creates an internal user record with ID G9876 and stores the mapping:

{
  "github_user_id": "U12345",
  "gitter_user_id": "G9876",
  "org_name": "AcmeDev",
  "community_rule": "members_of_AcmeDev"
}

When the user logs in via GitHub, Gitter receives the token, extracts U12345, looks up G9876, and grants access only if AcmeDev appears in the token’s organizations claim.

Verification Steps

1. Join a Gitter community that is gated by a specific GitHub organization. Successful membership indicates the gating rule is applied.
2. Review the account settings page to confirm the linked OAuth provider and the displayed organization name.
3. Test the login flow using a supported external provider (e.g., GitHub). Verify that the authentication redirect completes without error and that the user is immediately granted community access.

Limitations and Practical Check

Rate limiting can cause temporary failures; a practical way to check is to monitor the time between login attempts. If successive attempts take longer than a few seconds, the API may be throttling. Additionally, the mapping store must be updated whenever a user’s organization membership changes; otherwise, access may become stale. Regularly reviewing the Gitter admin UI for “last sync” timestamps provides a simple health check.