Add OpenID Connect authentication

[duytbp]

Hi @unknwon,

You mentioned in #8032 that you like OIDC but want to revisit the authentication-provider infrastructure first. I’d like to check whether the direction below matches the refactor you have in mind before writing code.

This follows #4602, #7437, and #8032.

Background

Gogs supports credential-based sources and trusted reverse proxy authentication. Native OIDC would let deployments connect an identity provider without adding an authentication proxy.

I suggest starting with OIDC rather than generic OAuth 2.0. OIDC gives us discovery, verified identity tokens, and a stable subject. OAuth 2.0 alone does not define how an application identifies a user. Provider-specific OAuth adapters, such as GitHub, could follow later.

This covers the OIDC part of #4602, not the original GitHub OAuth request.

Problems

The current auth.Provider requires Authenticate(login, password). That contract does not fit a browser redirect and callback.

The user model assumes one authentication source per user. LoginSource and the editable LoginName do not enforce a unique OIDC identity.

Some sensitive actions confirm the user’s password through the current provider, including account deletion and organization deletion. An OIDC-only user cannot complete those checks without browser reauthentication.

Proposed direction

Separate credential and browser providers

The interface split could look roughly like this:

type Provider interface {
	Config() any
	HasTLS() bool
	UseTLS() bool
	SkipTLSVerify() bool
}

type CredentialProvider interface {
	Provider
	Authenticate(login, password string) (*ExternalAccount, error)
}

type BrowserProvider interface {
	Provider
	AuthorizationURL(context.Context, BrowserLoginRequest) (string, error)
	AuthenticateCallback(context.Context, BrowserCallbackRequest) (*BrowserAccount, error)
}

This sketch is illustrative. The shared TLS methods need not remain in that exact form.

LDAP, SMTP, PAM, and legacy GitHub authentication would remain credential providers. OIDC would implement the browser provider. Git-over-HTTP and LFS would continue to use credential providers only.

Give browser identities a unique record

I suggest a small external-identity record rather than overloading User.LoginName:

ExternalIdentity
- ID
- UserID
- LoginSourceID
- IdentityNamespace
- Subject
- CreatedUnix

For OIDC, IdentityNamespace is the exact verified issuer and Subject is the verified sub. A callback would resolve an identity only when the source ID, namespace, and subject all match. An identity registered through one source would not be accepted through another source automatically.

The schema must guarantee that one browser identity resolves to at most one user. OIDC identifiers require exact, case-sensitive comparison, so the schema plan must define portable indexes for every supported database.

OIDC-created users would keep the OIDC source as their primary User.LoginSource. The identity row would be authoritative, while LoginName would be empty or a read-only compatibility copy.

Deleting a user would remove its identities. A referenced source could not be deleted, while deactivation would disable its logins. Removing an auth.d source would leave its identities dormant.

This adds a small schema migration, but it gives OIDC a database-enforced identity invariant and leaves room for explicit account linking later.

Registration and conflicts

After a verified callback, Gogs would look up the source, namespace, and subject. It would sign in a match or, when allowed, create an OIDC-backed account from validated claims.

A conflicting username or email would stop registration with a clear error. Matching claims would never select or link an existing account automatically. Explicit linking requires its own reauthentication, confirmation, recovery, and unlinking rules, so I suggest handling it in a later proposal.

OIDC and security scope

The first version would include discovery, authorization code flow, PKCE S256, random one-time state and nonce values, and optional registration with verified-email checks.

The web layer would own the short-lived transaction, callback binding, validated redirect, and one-time consumption. Discovery would be lazy and time-bounded. Gogs would not retain tokens or log sensitive protocol data.

I suggest using golang.org/x/oauth2 and github.com/coreos/go-oidc/v3/oidc rather than implementing discovery or token verification in Gogs.

The current React sign-in page would show browser providers separately from the username and password selector. Successful callbacks would reuse the existing MFA and session-completion flow.

OIDC would authenticate web sessions only. OIDC-only users would use SSH or a Gogs personal access token for Git-over-HTTP and LFS. Group mapping, profile synchronization, provider logout, account linking, and API bearer tokens remain out of scope.

For password-confirmed sensitive actions, the first version would either add browser reauthentication or disable those actions for browser-only accounts until reauthentication is available. It would not fall back to an identity-provider password.

Relationship to #8032 and delivery

#8032 contains useful provider, configuration, and UI work. The main differences here are the browser-provider interface, source-bound external identities, conflict rejection, and stronger state, nonce, and PKCE handling.

If accepted, I would first refactor the provider interfaces without changing behavior. A follow-up would add OIDC sign-in, identity storage, registration, UI, documentation, and tests. Account linking would remain separate.

Before writing the detailed implementation plan, I’d appreciate your view on three points:

1. Does the credential-provider and browser-provider split match the authentication refactor you have in mind?
2. Does a dedicated external-identity record make sense for enforcing source, issuer, and subject uniqueness, or would you prefer the first version to stay within the existing user fields?
3. Should browser reauthentication for password-confirmed sensitive actions be included in the first OIDC version, or should those actions initially be unavailable to browser-only accounts?

If this looks reasonable, I can follow up with the detailed implementation plan before starting work.

[unknwon]

Hi @duytbp, thanks for your time and thoughts here!

That said, I am pretty made up mind on how OIDC will be added to Gogs and have no plan to accept any external contribution until the initial version gets added. ❤️