WorkOS Docs Homepage
DashboardSign In


Learn how to configure a connection to Cloudflare via SAML.

Each SSO Identity Provider requires specific information to create and configure a new Connection. Often, the information required to create a Connection will differ by Identity Provider.

To create a Cloudflare SAML Connection, you’ll need to manually enter the SSO URL, IdP Entity ID, and X.509 Certificate obtained from your Cloudflare instance. Instructions on where to obtain these will be covered in this guide.

The first thing you’ll need to do is create a new Cloudflare SAML connection in your WorkOS Dashboard. Start by logging in to your WorkOS dashboard and browse to the “Organizations” tab on the left hand navigation bar.

Select the organization you’d like to configure a Cloudflare SAML Connection for, and from the dropdown menu select “Add Connection”.

A screenshot showing how to add an SSO connection in the WorkOS Dashboard.

Select “Cloudflare SAML” as the Identity Provider and give the Connection a descriptive name. Once this is filled out, click “Create Connection”.

A screenshot showing how to create a Cloudflare SAML Connection.

WorkOS provides the ACS URL and the SP Entity ID. These are available in your Connection’s Settings in the Developer Dashboard.

A screenshot showing where to find the Service Provider details in the WorkOS Dashboard.

The ACS URL is the location an Identity Provider redirects its authentication response to. In Cloudflare’s case, it needs to be set by the organization when configuring the application in the Cloudflare instance.

The SP Entity ID is a URI used to identify the issuer of a SAML request. In this case, the entity ID is used to communicate that WorkOS will be the party performing SAML requests to the organization’s Cloudflare instance.

Cloudflare SAML is a unique integration in that it sits between WorkOS and the Identity Provider. This allows for additional rules to be configured, but also means there are two connections that need to be made. The first necessary connection is between Cloudflare and the IdP, and the second connection is between WorkOS and Cloudflare.

First, create the connection between Cloudflare and the Identity Provider. Cloudflare Access allows you to connect with any IdP that supports a SAML 2.0 connection. Follow the documentation from Cloudflare to configure a SAML application connection between Cloudflare and your IdP.

The one deviation from the CloudFlare documentation is that the SAML attributes must include email, firstName, lastName, and id. Email is included by default as the “Email attribute name”, but you will need to add the other three as SAML attributes.

When setting up the connection, be sure to enter email, firstName, lastName, and id as SAML attributes.

A screenshot showing how to configure SAML attributes in Cloudflare Access.

Save the connection and then click the “Test” button. When successful, you will see a success screen including your saml_attributes that have been added.

A screenshot showing a successful test of Cloudflare Access.

Next, create the connection between Cloudflare and WorkOS. From the Cloudflare Zero Trust dashboard Access menu, select “Applications”, then “Add an application”.

A screenshot showing where to add an application in Cloudflare Access.

Select “SaaS” for the type of application.

A screenshot highlighting the SaaS application type in Cloudflare.

Copy the ACS URL and Entity ID from the Connection Settings in your WorkOS Dashboard.

A screenshot showing where to find the Service Provider details in the WorkOS Dashboard.

Select the name of your application from the dropdown menu. If your application is not listed, type the name to save it.

Paste the ACS URL and SP Entity ID to the corresponding fields in Cloudflare. Then select the Name ID Format that you would like to use for this application. For this example we’ll use Unique ID.

A screenshot showing where to input Service Provider details into the Cloudflare application.

Now, Configure the attribute statements. WorkOS requires that email, firstName, lastName, and id be included. Cloudflare automatically sends id and email, so you only need to add firstName and lastName. These attributes were configured in Step 1, and the mapped values are the same here.

Add firstName and lastName to both the right and left sides of the SAML attribute statements.

A screenshot showing where to configure Cloudflare attribute mapping.

Users can automatically be assigned roles within your application by sending their group memberships. To enable this, set up a group attribute statement following the guidance below.

This feature is currently in beta, contact customer support for more information.

Add a new attribute statement with groups as the “Name” and map it to the “IdP attribute” for groups, as shown in the example below.

A screenshot showing how to configure a groups attribute in Cloudflare.

Select the Identity Provider that you are using from the list. In this example we are using an Okta SAML connection.

A screenshot highlighting where to select the Identity Provider in the Cloudflare application.

Configure at least one policy and one rule, then click next. For this example the Policy sets the session length to 30 minutes for everyone.

A screenshot showing where to configure policy and rules for the Cloudflare application.

The SSO endpoint, Entity ID, and Public key (X.509 certificate) all will be entered in the Connection details in the WorkOS Dashboard. The SSO endpoint and Entity ID can be entered as-is, but the Public Key needs to be formatted as an X.509 certificate.

A screenshot showing where to copy the connection credentials from the Cloudflare dashboard.

To format the Public Key, copy the value to a text editor and add the following header and footer to the Public Key. Ensure there are no spaces above or below the Key value, then save with the file extension “.cert”.

Certificate format

The format of the file should look like this when you’re finished.

Completed Certificate Format

Navigate to the Connection in your Developer Dashboard. Enter the SSO endpoint in the IdP SSO URL field and enter the “Access Entity ID or Issuer” value into the “IdP URI (Entity ID)” field.

Upload the file that you saved for the X.509 certificate to the “Add an X.509 Certificate” field. Click Save Configuration.

A screenshot showing where upload the Metadata configuration details.

Your Connection will then be Active and good to go!