Support multiple OIDC providers, each with its own button label

[ulsklyc]

Split out of #654, where @Kyrodan asked for it alongside three other SSO wishes. This one is separate because it is by far the largest of them: it touches the data model, not just the login screen.

The request. Support more than one OIDC provider, each with its own button label on the login page ("Sign in with Authentik", "Sign in with Entra ID") rather than the single generic "Sign in with SSO".

Why this is not a small change. The current implementation assumes exactly one provider throughout:

• Configuration is four env vars (OIDC_ISSUER, OIDC_CLIENT_ID, OIDC_CLIENT_SECRET, OIDC_REDIRECT_URI) with no room for a second set. Numbered variables (OIDC_2_ISSUER) would be an awkward fit for a wizard and for the deploy descriptors, several of which enumerate every variable by hand.
• The discovery result is cached in a single module-level Configuration.
• /oidc/start and /oidc/callback carry no provider identifier, so a callback cannot tell which provider it came from.
• users stores one oidc_sub and one oidc_provider. Two providers means either one identity per account per provider (a new table) or a decision that an account belongs to exactly one provider.
• The account settings page offers one "link SSO account" action.

The oidc_provider column already stores the iss claim rather than a fixed string, which was done with exactly this in mind, so the identity side is not starting from zero.

Open questions:

• Can one account be linked to two providers at once, or is an account bound to one?
• Where does the configuration live? Four env vars per provider does not scale past two or three; a JSON blob in the env is hostile to a setup wizard; a database table means SSO configuration stops being reproducible from the .env alone, which is a real loss for a self-hosted app.
• What happens to an existing single-provider setup on upgrade? It has to keep working untouched.

I would want the first question answered before anything is designed, since it decides whether this needs a migration at all.

Related: #654 (OIDC_ALLOW_SIGNUP, shipped) and #847 (SSO as the only way in).

[ulsklyc]

Decided: an account belongs to exactly one provider.

That was the question blocking the design, so here is the reasoning and what follows from it.

A household is a list of people, and a person has one identity source. Letting one account hold two identities buys flexibility that nobody in a household actually needs, and it costs a new table plus a migration that every existing installation has to survive. users.oidc_sub and users.oidc_provider therefore stay exactly as they are, and the identity side of this needs no migration at all.

But one thing does have to change before a second provider is allowed in, and it is not in the list above:

CREATE UNIQUE INDEX idx_users_oidc_sub ON users(oidc_sub) WHERE oidc_sub IS NOT NULL;

That index is global, and findOrCreateOidcUser looks up WHERE oidc_sub = ? without asking which provider the claim came from. sub is only guaranteed unique within an issuer - that is the spec, not an implementation detail. With one provider configured this is correct by construction. With two, a provider that hands out short or reused subject identifiers (numeric ids, usernames, email-shaped subs - all of which real IdPs emit) can produce a sub that already belongs to somebody else's account, and the second person signs in as the first. The unique index turns that into a hard error rather than a silent takeover, which is better than nothing but still means one provider can lock accounts out of the other.

So the identity work is: lookup and uniqueness move from sub to (oidc_provider, oidc_sub). oidc_provider already stores the iss claim, which is why this is a migration of one index and one query rather than of the data. It is worth doing that part on its own merits - it is the correct reading of the spec either way.

Still open, and the harder half: where the configuration lives. Numbered variables (OIDC_2_ISSUER) do not fit the wizard or the deploy descriptors that enumerate every variable by hand; a JSON blob in the env is hostile to the wizard; a database table means SSO configuration stops being reproducible from the .env alone, which is a real loss for a self-hosted app. I do not have a good answer yet, and it decides the shape of everything else, so this stays open until it has one.

Related: #847 (SSO as the only way in) is implemented in #849.

[Kyrodan]

Decided: an account belongs to exactly one provider.

For me, an account could have more than one provider-account linked. In my case it could be my (local) Synology SSO and additionally a Google/GitHub/Microsoft Account. You mentioned my pro-argument indirect in the related discussion: if an OIDC-Provider is currently not available, you cannot login anymore. So with more than one OIDC-Provider linked to one account this lowaers the risk of not able to login because you have a second "backup" Provider.

But this is just a nice-to-have-feature for me.

Still open, and the harder half: where the configuration lives.

Please do not place the OIDC-Config in database (only). It should be configurable (and changeable) from "outside". Enumerating variables would be okay for me. Alternatively have the OIDC-Config in a separate JSON-File (and maybe a variable pointing to the path of this config file). You could then mount this file/folder in Docker like you prefer:

• volume-mounted
• path-mounted - absolutely on your filesystem or (like I prefer for these kind of config files) relative to docker-compose file.

[ulsklyc]

Correcting myself: the identity half does not stand on its own after all.

My last comment said the lookup change - moving from oidc_sub to (oidc_provider, oidc_sub) - was worth doing on its own merits, independently of the unresolved question of where multi-provider configuration lives. I went to implement it, and that is wrong. I would rather say so than leave it standing as an instruction to anyone who picks this up.

What breaks. users.oidc_provider holds the iss claim, which is a URL. As a description of where an account came from, that is correct. As a key, it is not: it changes when the deployment changes. A self-hoster who moves their IdP from auth.local to auth.example.com, or puts it behind a different hostname, keeps the same provider and the same people - but a strict (provider, sub) match would no longer find their accounts and would create second ones. Today that migration survives untouched, precisely because the lookup only matches on sub. So the "correct reading of the spec" would, on its own, introduce a regression for existing installations that does not exist today.

Where the actual key comes from. The projects that solve this properly - Nextcloud's user_oidc, Grafana - do not key on iss. They key on an internal provider identifier that comes from the configuration: a short name the operator gives each provider, stable across any URL change. Yuvomi has no such identifier, and it cannot have one until the configuration question is answered, because that question is exactly what would create it.

So the two halves are one piece of work after all, and in this order: decide where provider configuration lives and what names providers get, then build the lookup and the index on that name. Doing the index first would be a migration that has to be migrated again.

What does stay true from the last comment: the security reasoning. sub is only unique within an issuer - that is the spec, not an implementation detail - so a second provider cannot be allowed in while the unique index is global. That constraint is real and still blocks the feature. It just cannot be lifted before the configuration has a shape, rather than in advance of it.

One implementation note for whoever gets there, since it is easy to miss: idx_users_oidc_sub is not only the uniqueness constraint. The SSO-only rule from #847 uses it to answer "is any account linked at all". A replacement index has to keep oidc_sub as its leading column, or that query quietly loses its cover.

Still open, and still the deciding question: numbered env vars do not fit the wizard or the deploy descriptors, a JSON blob in the env is hostile to the wizard, and a database table means SSO configuration stops being reproducible from .env alone. I do not have a good answer yet.