External Account Login & Developer Identity Linking for GitHub, GitLab and Self-Hosted Git Providers

[FTMahringer]

Problem / Motivation

Synapse supports an admin user and can have multiple normal users. For plugin development, marketplace publishing, authorship and collaboration features, users should be able to connect or sign in with external developer accounts.

Important targets:

• GitHub
• GitLab.com
• Self-hosted GitLab
• Forgejo/Gitea or other self-hosted Git providers later

This would allow Synapse to use a verified developer identity when creating plugins, publishing plugins, showing authorship, assigning ownership, and simplifying developer workflows.

---

Proposed Solution

Add external login/account linking support using OAuth2/OIDC where possible.

Core functionality:

• Admin remains the primary system owner
• Multiple users can exist inside Synapse
• Users can connect external accounts
• External account identity can be used for plugin author metadata
• Plugin creation/scaffolding can prefill author username/name/email
• Marketplace publishing can use linked identity
• Self-hosted Git providers can be configured by the admin

Possible supported providers:

GitHub
GitLab.com
Self-hosted GitLab
Forgejo/Gitea later
Generic OIDC later

---

Suggested Data Model

User
 ├── id
 ├── username
 ├── email
 ├── role
 └── externalAccounts[]

ExternalAccount
 ├── provider
 ├── providerUserId
 ├── username
 ├── displayName
 ├── email
 ├── avatarUrl
 ├── profileUrl
 ├── accessTokenRef
 ├── refreshTokenRef
 └── scopes

Secrets/tokens should not be stored directly on the entity. Store them through Synapse secret management and only reference them from the external account record.

---

Plugin Author Use Case

When a user creates a plugin, Synapse can automatically use the linked provider identity.

Example generated plugin metadata:

author:
  username: FTMahringer
  displayName: Fynn Mahringer
  profileUrl: https://github.com/FTMahringer
  provider: github

This improves:

• plugin author attribution
• marketplace trust
• publishing flow
• generated README files
• plugin template scaffolding
• repository creation workflows

---

Admin Configuration

Admins should be able to configure allowed external login providers.

Possible settings:

auth:
  externalProviders:
    github:
      enabled: true
      clientId: ...
      clientSecretRef: ...
    gitlab:
      enabled: true
      baseUrl: https://gitlab.com
      clientId: ...
      clientSecretRef: ...
    selfHostedGitlab:
      enabled: true
      baseUrl: https://git.example.com
      clientId: ...
      clientSecretRef: ...

---

Security Requirements

• Admin can enable/disable providers
• Admin can restrict which providers are allowed
• Users can link/unlink accounts
• Tokens are encrypted/managed via secret storage
• Scope minimization
• Clear consent screen before connecting accounts
• Audit log entries for link/unlink/login events
• Optional domain allowlist for organizations or teams
• Optional admin approval for new external users

---

Future Extensions

• Import organization/team memberships from GitHub/GitLab
• Use external identity for plugin signing
• Use external identity for marketplace publisher verification
• Create plugin repositories automatically from templates
• GitHub/GitLab project sync
• Contributor analytics for plugins
• Role mapping based on teams/groups
• Generic OIDC provider support

---

Priority

Medium / High

This becomes important before the plugin marketplace, plugin publishing workflow and developer ecosystem become public-facing.