Cloudflare dashboard SSO application

By adding a Cloudflare Dashboard SSO application to your Cloudflare Zero Trust account, you can enforce single sign-on (SSO) to the Cloudflare dashboard with the identity provider (IdP) of your choice. SSO will be enforced for every user in your email domain.

Availability

	Free	Pro	Business	Enterprise
Availability	No	No	No	Yes (with Standard or Premium Success plans)

Prerequisites

All users in your email domain must exist as a member in your Cloudflare account and IdP. To add users to your Cloudflare account, refer to Manage Cloudflare account access.

1. Set up an IdP

Add an IdP to Cloudflare Zero Trust by following our detailed instructions.

Once you configure your IdP, make sure you also test your IdP.

2. Contact your account team

Ask your account team to approve and create your SSO domain. An SSO domain is the email domain associated with the members in your Cloudflare account. For example, if your SSO domain is configured for emails ending in @yourcompany.com, a member with email @test.com would not see the Log in with SSO option and would have to enter their username and password.

Once your SSO domain is approved, a new SSO App application will appear under Access > Applications. The application is pre-configured with allow email domain as the default rule and your IdP as the authentication providers.

SSO domain requirements

The email domain must belong to your organization. Public email providers such as @gmail.com are not allowed.
Every user with that email domain must be an employee in your organization. For example, university domains such as @harvard.edu are not allowed because they include student emails.
Your SSO domain can include multiple email domains.

3. Enable dashboard SSO

In Zero Trust ↗, go to Settings > Authentication.
In the Cloudflare dashboard SSO card, set your email domain to Enabled. This action can only be performed by Super Administrators.
Do not log out or close your browser window. Instead, open a different browser or an incognito window.
In the Cloudflare dashboard ↗, log in with your email address from your SSO domain.
If you can log in successfully, you have successfully set up your dashboard SSO application.
If you cannot log in successfully:
1. Return to Zero Trust and go to Settings > Authentication.
2. For Cloudflare dashboard SSO, set your email domain to Disabled.
3. Re-configure your IdP.

Limitations

Cloudflare dashboard SSO does not support:

Users with plus-addressed emails, such as example+2@domain.com. If you have users like this added to your Cloudflare organization, they will be unable to login with SSO.
Adding a separate email-based policy to the SSO application that does not match your SSO domain policy. As your account team must approve and create your SSO domain based on the SSO domain requirements, adding a new domain policy on your own will not work.
Deleting the auto-generated allow email domain policy. If this policy was deleted, your organization's administrators would not be able to access the Cloudflare dashboard.

IdP-initiated SSO

IdP-initiated login is supported for Cloudflare dashboard SSO, with configuration available via your identity provider (IdP).

A step-by-step guide is currently available for Okta, and similar configurations are possible with other identity providers that support custom SSO endpoints.

Okta

Configure an identity provider (IdP)-initiated single sign-on (SSO) session using Cloudflare Zero Trust and Okta.

Prerequisites

In Zero Trust ↗, go to Access > Applications > select your SSO App.
Select Configure to access the application settings.
In the Basic Information section, find the SSO Endpoint URL and copy it. You will need the copied SSO Endpoint URL for your IdP setup.

Configure Okta as the IdP

Log in to your Okta Admin Dashboard ↗ and go to Applications > Applications.
Select Create App Integration to start a new SAML integration to handle the IdP-initated SSO flow.
In the pop-up, select SAML 2.0 and select Next.
Enter a name for the app and select Next.
In the Single Sign-On URL field, paste the SSO Endpoint URL you copied earlier.
Set the Name ID Format to EmailAddress.
Set the Application Username to Email.
Select Next > Finish to save the integration.
Test the integration by going to your Okta User Dashboard, locating the new app tile, and selecting it to verify the SSO flow.

(Optional) Enforce single IdP login with Instant Auth

If you use only one IdP (for exampple, Okta) for Cloudflare SSO and want users to skip the identity provider selection prompt:

In Zero Trust ↗, go to Access > Applications > select your SSO App.
Go to Login methods.
Disable Accept all available identity providers and ensure only Okta is selected as the login method.
Enable Instant Auth to allow users to skip identity provider selection.

Bypass dashboard SSO

This section describes how to restore access to the Cloudflare dashboard in case you are unable to login with SSO.

Option 1: Add a backup IdP

If there is an issue with your SSO IdP provider, you can add an alternate IdP using the API. The following example shows how to add Cloudflare One-time PIN as a login method:

Add one-time PIN login:

curl 'https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/access/identity_providers' \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "type": "onetimepin",
  "config": {}
}'

Get the id of the dash_sso Access application. You can use jq ↗ to quickly find the correct application:

curl 'https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/access/apps' \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
| jq '.result[] | select(.type == "dash_sso")'

{
  "id": "3537a672-e4d8-4d89-aab9-26cb622918a1",
  "uid": "3537a672-e4d8-4d89-aab9-26cb622918a1",
  "type": "dash_sso",
  "name": "SSO App"
  ...
}

Using the id obtained above, update SSO App to accept all identity providers:

curl --request PUT \
'https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/access/apps/3537a672-e4d8-4d89-aab9-26cb622918a1' \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "id": "3537a672-e4d8-4d89-aab9-26cb622918a1",
  ...
  "allowed_idps": [],
  ...
}'

Users will now have the option to log in using a one-time PIN.

Option 2: Disable dashboard SSO

The following API calls will disable SSO enforcement for an account. This action can only be performed by Super Administrators.

Get your SSO connector_id:

curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/sso/v2/connectors \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

{
  "result": [
    {
      "connector_id": "2828",
      "connector_tag": "d616ac82cc7f87153112d75a711c5c3c",
      "email_domain": "yourdomain.com",
      "connector_status": "V",
      ...
    }
  ],
  "success": true,
  "errors": [],
  "messages": []
}

Disable the SSO connector:

curl --request PATCH \
'https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/sso/v2/connectors/2828' \
--header "X-Auth-Email: $CLOUDFLARE_EMAIL" \
--header "X-Auth-Key: $CLOUDFLARE_API_KEY" \
--header "Content-Type: application/json" \
--data '{
  "sso_connector_status": "DIS"
}'

{
  "result": {
    "id": "2828"
  },
  "success": true,
  "errors": [],
  "messages": []
}

Users can now log in using their Cloudflare account email and password. To re-enable SSO, send a PATCH request with "sso_connector_status" : "V".

Was this helpful?

Community
X
Discord
YouTube
GitHub