Single sign-on overview: bring your own identity provider

downpipes can let your team sign in with the identity provider you already run. The engine is its own native OpenID Connect relying party, its own native OAuth2 client, and its own native SAML 2.0 service provider, all running as a Worker inside your own Cloudflare account. There is no Cloudflare Access in the path: Access stays additive, never a prerequisite. You point a connection at your provider, the engine completes the federated sign-in itself, and a verified person lands in the console.

This page is for a self-hoster deciding whether and how to wire single sign-on. It sets the no-custody and optional-and-additive expectations, lays out the exact menu of providers, and states the v1 scope limits plainly so nothing surprises you on the step-by-step pages. The procedure itself lives on Connect OIDC or OAuth2 and Connect SAML.

Optional, and never a lockout

Single sign-on is something you add, not something you depend on. The passkey owner front door and the break-glass shared token stay independent of any connection. So an identity provider outage is a greyed-out sign-in button, not a way to be locked out of your own backups: the owner can still reach the console on a passkey, and the break-glass token still works. That independence is the whole reason an external provider is safe to bolt on.

The flip side is just as direct. Disabling or deleting a connection takes effect at once. The engine bumps that connection’s session epoch, which kills the connection’s live sessions, and the connection drops out of the pre-authentication provider list so its sign-in button disappears immediately. There is no lag where a removed provider keeps minting sessions.

The provider menu

The preset registry ships 8 named providers plus a Generic OIDC hatch and a Generic OAuth2 hatch. The named presets pre-fill the endpoints, scopes, claim names and the provider-specific gotchas, so you type only a handful of values (a tenant id, an Okta domain, a Keycloak realm) plus your client id and, for a confidential client, a secret.

The split between the two protocols matters for how trust is established, covered next.

OIDC versus OAuth2 trust

An OIDC connection (every named provider except GitHub) gets a signed id_token from the provider, and the engine cryptographically verifies it. An OAuth2 connection (GitHub, and the Generic OAuth2 hatch) has no id_token at all. For an OAuth2 connection, trust derives from the TLS-protected token exchange, and identity comes from a userinfo call made with the resulting access token. The access token is opaque and is used only as a bearer credential against the provider’s own API.

That is an important honesty point. GitHub and Generic OAuth2 do not verify any token signature, because there is no signed token to verify. They are still safe, because the code exchange happens over a screened HTTPS fetch and the identity is read straight from the provider’s authenticated API, keyed on the immutable user id rather than a renameable username. But do not picture a signed assertion where there is not one.

No custody by construction

A stored connection record never holds a client secret value. The record carries a secret descriptor only: a mode, and an optional non-secret reference. That descriptor is what the console and the audit trail see, so neither ever holds your secret.

There are four named secret-custody modes in the type, but only two are wired in this build. A connection record describes itself with one of these:

The two unwired modes are the trap to know about, but they cannot trap you silently: a connection configured for secrets-store or private_key_jwt is refused at save time, not at first login. Validation runs before the record is ever written to storage, so a proposal in either mode is rejected with a 400 and nothing is persisted. The console deliberately offers only the two working choices, a public client (PKCE) or a write-only do-plaintext secret, so you cannot even reach that rejected save from the UI.

A SAML connection has no client secret of any kind. Its trust root is the set of public X.509 signing certificates you pin, which are not secret and live in the record openly.

The key fetch cannot be steered off your provider

Because a connection’s issuer is a value you supply, it is also the value an attacker would want to change. The engine screens every call it makes to a provider, discovery, the JWKS key fetch and the token exchange, before the request leaves: the URL must be https, never an IP literal, and never localhost or a .localhost name, with a second classifier for the IPv6 unique-local, link-local and obfuscated forms an IP check alone misses. Redirects are never followed, so a 3xx towards a metadata address or a private range is refused rather than chased. The same pin applies to the Cloudflare Access path, where the key fetch is held to an https host under *.cloudflareaccess.com, so a tampered team-domain value cannot redirect it either. See connect an OIDC provider for the mechanism in full.

v1 scope limits

A few capabilities are deliberately not in v1. Knowing them up front saves a misconfiguration.

The SAML service provider is sign-only and SP-initiated. It rejects an EncryptedAssertion outright (there is no decryption key, and none is advertised in the metadata), and it does not expose an identity-provider-initiated flow. The connection type carries an allowIdpInitiated flag, but the console hard-codes it off, and the access endpoint enforces SP-initiated-only by consuming a single-use RelayState record that only an SP-initiated request can have created. The full SAML behaviour and the email-trust policy are covered on Connect SAML.

If you have a SAML-only provider and would rather drive it through the OIDC path, a SAML-to-OIDC bridge is an optional self-hosted recipe you stand up yourself. It is not part of the engine.

Who can manage connections

Connecting an identity provider decides who can sign in, which makes it an authentication trust root. A group mapped through a connection can even confer access-admin, so connection management is reserved to the owner-exclusive keys.ceremony capability, not the broader access.policy. A generic administrator cannot add, remove, or enable a provider.

Once a second owner exists on the account, creating, deleting or enabling a connection additionally takes a second owner’s approval (a break-glass admin-token sign-in is the exception). Each of those actions runs through the dual-control owner gate, the same second-owner approval pattern used for the other account-takeover-sensitive operations, so no single owner can quietly change who is allowed in. For the wider second-owner model see dual control for recovery and the change-control page.

Where this fits

Last updated 3 July 2026.