Skip to content
downpipes docs

Connect a SAML 2.0 identity provider

downpipes runs its own native SAML 2.0 service provider inside your own Cloudflare account, so people sign in against your existing SAML provider and land in the console. There is no per-vendor SAML preset; one generic form drives any SAML 2.0 provider. The full walkthrough, the email-trust policy and the v1 scope live on Connect SAML.

What you need

  • Admin access to your SAML provider to create a SAML application and export its signing certificate.
  • Owner access to the downpipes console, since connection management is owner-only and asks for a step-up sign-in.

Set it up

  1. In the downpipes console, open the external identity providers screen (/access/idp), choose the SAML 2.0 tile and Add a connection. This is owner-only and asks for a step-up sign-in. Set a connection id first, because the ACS URL is built from it.
  2. Note the ACS (assertion consumer service) URL the form shows, which is your console origin followed by /admin/saml/acs/<connId>, for example https://console.example.com/admin/saml/acs/saml, and the SP entity id you set.
  3. In your provider, create a SAML 2.0 application (a generic or custom SAML app). Set its ACS, Reply or Single sign-on URL to the value from step 2, and set the SP entity id or Audience to the one you entered.
  4. Choose an emailAddress or persistent NameID format and turn on signing of assertions. downpipes requires a signed assertion and does not accept the transient NameID format.
  5. Download your provider’s X.509 signing certificate in PEM form and paste it into the connection. If your provider rotates certificates, paste each one so the overlap is covered.
  6. Enter the IdP entity id and the IdP single sign-on URL, choose the email-trust policy (require-flag is the safe default), run Test connection, then Add the connection.
  7. After it is created, download the SP metadata from the connection card and register it at your provider if it prefers metadata over the values you entered by hand.

Group-to-role mapping

Map a groups attribute your provider asserts onto downpipes roles on Group-to-role mapping. Configure your SAML app to release a groups attribute alongside the NameID, and map the email attribute too so a person’s pending invite can bind. Under the require-flag email-trust policy, an email the assertion does not mark verified yields a subject-only sign-in, which is a successful sign-in and not a failure; only the auto-binding of a pending invite is skipped.

Good to know

  • downpipes is SP-initiated and sign-only. It verifies a signed assertion and starts sign-in from downpipes; it does not decrypt encrypted assertions and does not accept an identity-provider-initiated POST.
  • Trust rests on the certificate you paste. The service provider verifies signatures against the certificates you pin and ignores any key embedded in the assertion, so a forged key is never trusted.
  • The transient NameID format is not accepted, because a per-session pseudonym is not stable enough to key a returning person’s access; use emailAddress or persistent.
  • The ACS URL is built from your console origin, so register the exact value the form shows, including the connection id, or the assertion lands nowhere.

Last updated .