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 a person who holds a role, an invite or a mapped group signs in against your existing SAML provider and lands 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 the assertion or of the response. downpipes requires a valid signature on the assertion or on the whole response, 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 (the form defaults to trust-idp), 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.

A SAML sign-in needs a trusted email, or the engine refuses it. Set the Email attribute to the attribute your provider carries the address in. The form defaults to trust-idp, which trusts any well-formed email the assertion carries, so choose it only when your provider sends correct addresses; on trust-idp, a pending Owner, access-admin, approver or restore-operator invite stays pending, and only a Viewer, Operator or unprivileged custom role binds.

Choose require-flag to trust an email only through the verified attribute. Set the Email verified attribute field; every role, Owner included, can then bind. The engine saves a blank Email attribute under either policy, but then refuses every sign-in on that connection, and it refuses to create a require-flag connection with no verified attribute. The audit log records which policy you chose.

Good to know

  • downpipes is SP-initiated and sign-only. It verifies a signed assertion or a signed response 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.
  • A connection lets people authenticate; it does not admit them. downpipes signs a person in only when the account holds a role, a pending invite for its verified email, or a mapped group. Invite people or set a role on the Roles and access tab (/access/roles); map a group on Group-to-role mapping. Anyone else is refused and sent back to the sign-in page.

Last updated .