Architecting Identity Mapping via OAuth2 in Gitter

The Identity Mapping Problem

For developer-centric communities, requiring a separate account registration process creates a significant barrier to entry. The technical challenge is implementing a system where a user's identity is verified by a trusted third party (GitHub or GitLab) but managed within a chat environment without storing sensitive credentials like passwords locally.

The core takeaway is the use of Identity Mapping: linking a unique provider ID to a local session, ensuring that a user's presence in a chat room is tied to their verified developer persona rather than a standalone Gitter account.

Minimum Viable Design

The smallest suitable design to achieve this relies on the OAuth2 delegation flow. Instead of a local user database with password hashes, the system implements a mapping table that associates a Gitter User ID with a Provider ID (e.g., a GitHub numeric ID).

The Authentication Sequence

1. Redirection: The user is redirected to the provider (GitHub/GitLab) with a request for specific scopes (e.g., user:email).
2. Authorization: The provider authenticates the user and returns an authorization code to Gitter.
3. Token Exchange: Gitter exchanges this code for an access token via a secure server-to-server request.
4. Profile Retrieval: Gitter uses the token to fetch the provider's unique user ID.
5. Mapping: If the provider ID exists in the Gitter mapping table, the existing session is restored. If not, a new Gitter profile is initialized based on the provider's metadata.

Trust and Data Boundaries

To maintain security, a strict boundary is maintained between the Authentication Token and the Session Token.

By separating these, Gitter ensures that a compromise of a session cookie does not automatically grant full access to the user's GitHub account, as the access token is stored server-side and used only for specific identity verification tasks.

Operational Checks and Verification

To verify that the identity mapping is functioning correctly, administrators or users can perform the following checks:

• Provider Linkage: Navigate to the account settings page. The presence of a "Connected to GitHub/GitLab" indicator confirms the mapping table has a valid entry for the current session.
• Session Persistence: Log out and log back in using the same provider. If the user is returned to the same chat rooms with the same history, the identity mapping is persisting across sessions.

Failure Modes and Constraints

Dependence on external providers introduces specific risks that must be managed:

Provider API Downtime

If GitHub or GitLab experiences an outage, the /authorize and /token endpoints become unavailable. This prevents new users from joining and forces existing users to rely on active session tokens. Once a session expires during a provider outage, the user is completely locked out.

Rate Limiting

Frequent authentication requests or profile updates can trigger provider rate limits. This typically manifests as a 403 Forbidden or 429 Too Many Requests error during the token exchange phase.

Scope Changes

If the provider changes the required scopes for accessing user IDs, the authentication flow will fail. The system must be configured to handle "insufficient scope" errors by prompting the user to re-authorize the application with updated permissions.

Conditions for Design Evolution

The current design is optimal for low-friction entry, but would require changes under the following conditions:

• Multi-Provider Identity: If users need to link both GitHub and GitLab to a single Gitter profile, the mapping table must move from a 1:1 relationship to a 1:N relationship.
• Local Account Fallback: If the community requires access for users without third-party accounts, a local authentication layer (email/password) must be implemented, creating a hybrid identity system.
• Enterprise SSO: Integration with SAML or OIDC for corporate environments would require replacing the simple OAuth2 flow with a more complex Identity Provider (IdP) orchestration layer.