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 supported 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 Govern, Identity providers (the /access/idp screen), and choose the SAML 2.0 tile to open the add form. 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 choose Add SAML provider.
  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 set that attribute’s name on the connection.

Email binding works differently, and the default deliberately does not bind. Under require-flag downpipes trusts an email only when a verified-flag attribute is asserted and true, and the console’s SAML form has no field for that attribute name, so a connection added here always drops the email and signs the person in subject-only. That is a successful sign-in, not a failure, but a pending invite does not auto-bind by email and you grant the role against the subject instead. Choose trust-idp, and set the email attribute, only where your provider does not assert a verified-email flag and you accept that it sends correct addresses. From engine 0.3.6, the audit log records which policy you chose, but an older engine records only that you added the connection.

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 .