[ZT] SSO apps (#25412)

---------

Co-authored-by: marciocloudflare <[email protected]>

Author: pedrosousa

src/content/docs/cloudflare-one/applications/configure-apps/dash-sso-apps.mdx

@@ -9,65 +9,100 @@ sidebar:
 
 import { FeatureTable, APIRequest, GlossaryTooltip } from "~/components";
 
-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.
+Cloudflare offers single sign-on (SSO) for all customers who log in with a custom email domain. By creating a Cloudflare SSO connector, you can enforce 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
 
+Cloudflare Dashboard SSO is available for free to all plans.
+
 <FeatureTable id="account.single_sign_on" />
 
 ## 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](/fundamentals/manage-members/).
+1. You must control your email domain and be able to add a TXT record to verify this.
+   - 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.
+
+2. You must be a super administrator and be able to access the Cloudflare API.
+
+3. A Cloudflare Zero Trust organization with any subscription tier (including Free) must be created. To set up a Cloudflare Zero Trust organization, refer to [Create a Cloudflare Zero Trust organization](/cloudflare-one/setup/#create-a-zero-trust-organization).
 
 ## 1. Set up an IdP
 
 Add an IdP to Cloudflare Zero Trust by following [our detailed instructions](/cloudflare-one/identity/idp-integration/).
 
 Once you configure your IdP, make sure you also [test your IdP](/cloudflare-one/identity/idp-integration/#test-idps-in-zero-trust).
 
-## 2. Contact your account team
+## 2. Register your domain with Cloudflare for SSO
+
+:::caution
+Cloudflare recommends creating an [Account API token](/fundamentals/api/get-started/create-token/) with the role `SSO Connector Edit` and storing it securely. This acts as a backup plan, allowing you to disable SSO via the API if you are accidentally locked out, such as due to changes in your IdP configuration later.
+:::
 
-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.
+Using a command line terminal where you have already set the environment variable `CLOUDFLARE_API_TOKEN` to a user or account API token which has the `SSO Connector Edit` permission, run the following command to create an SSO connector. Replace `{account_id}` with your account ID, and `{domain}` with your email domain.
 
-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.
+```bash title="cURL command"
+curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/sso_connectors" \
+  --request POST \
+  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
+  --json '{"email_domain":"{domain}"}'
+```
 
-### SSO domain requirements
+```json output
+{
+	"success": true,
+	"errors": [],
+	"messages": [],
+	"result": {
+		"id": "c3ebcba5c20b42f73e111110d0be67d",
+		"enabled": false,
+		"email_domain": "cool.cats",
+		"verification": {
+			"code": "cloudflare_dashboard_sso=111111111",
+			"status": "pending"
+		},
+		"created_on": "2025-09-05T20:35:34Z"
+	}
+}
+```
 
-- 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. Verify domain ownership
 
-:::caution
+Copy the verification code (for example `cloudflare_dashboard_sso=1111111`) and create a TXT record in your DNS configuration with that value. Cloudflare will automatically poll that DNS record until it is found or a timeout is reached within two days.
 
-Enabling Cloudflare Dashboard SSO for an email domain (for example, `@mycompany.com`) will apply globally across all Cloudflare accounts where users log in with that domain. All users will be required to authenticate via the specified identity provider (IdP), including users on pre-existing Cloudflare accounts.
+If verification fails due to timeout, you may manually reinitiate the polling by running the following command:
 
-:::
+```bash title="cURL command"
+curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/sso_connectors/{sso_connector_id}/begin_verification" \
+  --request POST \
+  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
+```
 
-## 3. Enable dashboard SSO
+Once the verification polling has completed or timed out, you will receive an email notification with the verification result.
 
-:::note
+## 4. Enable dashboard SSO
 
-Cloudflare recommends carefully storing your [Global API key](/fundamentals/api/get-started/keys/) to access when necessary. You will need your Global API key when you [disable SSO](#option-2-disable-dashboard-sso).
+:::caution
+Enabling Cloudflare Dashboard SSO for an email domain (for example, `@mycompany.com`) will apply globally to all users with that domain, regardless of which accounts those users have access to. All users will be required to authenticate via the specified identity provider, including users registered on Cloudflare prior to the domain being configured for SSO.
 :::
 
-1. In [Zero Trust](https://one.dash.cloudflare.com/), go to **Settings** > **Authentication**.
-2. In the **Cloudflare dashboard SSO** card, set your email domain to **Enabled**. This action can only be performed by Super Administrators.
-3. Do not log out or close your browser window. Instead, open a different browser or an incognito window.
-4. In the [Cloudflare dashboard](https://dash.cloudflare.com), log in with your email address from your SSO domain.
-5. If you can log in successfully, you have successfully set up your dashboard SSO application.
-6. If you cannot log in successfully:
+Enable the connector by running the following — again, replacing the `{account_id}` value with your account ID, and additionally replacing the `{sso_connector_id}` with the value you obtained from the `id` field in the response to the previous call.
 
-   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](/cloudflare-one/identity/idp-integration/).
+```bash title="cURL command"
+curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/sso_connectors/{sso_connector_id}" \
+  --request PATCH \
+  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
+  --json '{"enabled": true}'
+```
 
 ## Limitations
 
 Cloudflare dashboard SSO does not support:
 
 - Users with plus-addressed emails, such as `[email protected]`. 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](/cloudflare-one/applications/configure-apps/dash-sso-apps/#2-contact-your-account-team) based on the [SSO domain requirements](/cloudflare-one/applications/configure-apps/dash-sso-apps/#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.
+- Adding a separate email-based policy to the SSO application that does not match your SSO domain policy.
+- Multiple domain policies. If another domain policy is required, you can create another SSO connector. This will create a second policy for that new domain in your SSO application.
+- Deleting the auto-generated `allow email domain` policy. If this policy is deleted, your organization's administrators cannot access the Cloudflare dashboard.
 
 ## IdP-initiated SSO
 
@@ -88,7 +123,7 @@ Configure an identity provider (IdP)-initiated single sign-on (SSO) session usin
 #### Configure Okta as the IdP
 
 1. Log in to your [Okta Admin Dashboard](https://login.okta.com/) and go to **Applications** > **Applications**.
-2. Select **Create App Integration** to start a new SAML integration to handle the IdP-initated SSO flow.
+2. Select **Create App Integration** to start a new SAML integration to handle the IdP-initiated SSO flow.
 3. In the pop-up, select **SAML 2.0** and select **Next**.
 4. Enter a name for the app and select **Next**.
 5. In the **Single Sign-On URL** field, paste the **SSO Endpoint URL** [you copied earlier](/cloudflare-one/applications/configure-apps/dash-sso-apps/#prerequisites-1).
@@ -117,123 +152,151 @@ If there is an issue with your SSO IdP provider, you can add an alternate IdP us
 
 1. [Add](/api/resources/zero_trust/subresources/identity_providers/methods/create/) one-time PIN login:
 
-<APIRequest
-  path="/accounts/{account_id}/access/identity_providers"
-  method="POST"
-  json={{
-    type: "onetimepin",
-    config: {},
-  }}
-/>
+   <APIRequest
+   	path="/accounts/{account_id}/access/identity_providers"
+   	method="POST"
+   	json={{
+   		type: "onetimepin",
+   		config: {},
+   	}}
+   />
 
 2. [Get](/api/resources/zero_trust/subresources/access/subresources/applications/methods/list/) the `id` of the `dash_sso` Access application. You can use [`jq`](https://jqlang.github.io/jq/download/) to quickly find the correct application:
 
-```bash title="cURL command"
-curl 'https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/access/apps' \
---header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
-| jq '.result[] | select(.type == "dash_sso")'
-```
-
-```json title="Response"
-{
-  "id": "3537a672-e4d8-4d89-aab9-26cb622918a1",
-  "uid": "3537a672-e4d8-4d89-aab9-26cb622918a1",
-  "type": "dash_sso",
-  "name": "SSO App"
-  ...
-}
-```
+   ```bash title="cURL command"
+   curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/access/apps" \
+     --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
+     | jq '.result[] | select(.type == "dash_sso")'
+   ```
+
+   ```json output {2}
+   {
+   	"id": "3537a672-e4d8-4d89-aab9-26cb622918a1",
+   	"uid": "3537a672-e4d8-4d89-aab9-26cb622918a1",
+   	"type": "dash_sso",
+   	"name": "SSO App"
+   	// ...
+   }
+   ```
 
 3. Using the `id` obtained above, [update](/api/resources/zero_trust/subresources/access/subresources/applications/methods/update/) **SSO App** to accept all identity providers. To avoid overwriting your existing configuration, the PUT request body should contain all fields returned by the previous GET request.
 
-<APIRequest
-  path="/accounts/{account_id}/access/apps/{app_id}"
-  method="PUT"
-  parameters={{ app_id: "3537a672-e4d8-4d89-aab9-26cb622918a1" }}
-  json={{
-    id: "3537a672-e4d8-4d89-aab9-26cb622918a1",
-		uid: "3537a672-e4d8-4d89-aab9-26cb622918a1",
-		type: "dash_sso",
-		name: "SSO App",
-    allowed_idps: [],
-    // ... (other existing properties)
-  }}
-	code={{
-		mark: [9]
-	}}
-/>
+   <APIRequest
+   	path="/accounts/{account_id}/access/apps/{app_id}"
+   	method="PUT"
+   	parameters={{ app_id: "3537a672-e4d8-4d89-aab9-26cb622918a1" }}
+   	json={{
+   		id: "3537a672-e4d8-4d89-aab9-26cb622918a1",
+   		uid: "3537a672-e4d8-4d89-aab9-26cb622918a1",
+   		type: "dash_sso",
+   		name: "SSO App",
+   		allowed_idps: [],
+   		// ... (other existing properties)
+   	}}
+   	code={{
+   		mark: [9],
+   	}}
+   />
 
 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.
 
-1. Get your SSO `connector_id`:
-
-```bash title="cURL command"
-curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/sso/v2/connectors \
---header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
-```
-
-```json title="Response"
-{
-  "result": [
-    {
-      "connector_id": "2828",
-      "connector_tag": "d616ac82cc7f87153112d75a711c5c3c",
-      "email_domain": "yourdomain.com",
-      "connector_status": "V",
-      ...
-    }
-  ],
-  "success": true,
-  "errors": [],
-  "messages": []
-}
-```
+1. Get your SSO connector `id`:
+
+   ```bash title="cURL command"
+   curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/sso_connectors" \
+     --request GET \
+     --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
+   ```
+
+   ```json output
+   {
+   	"result": [
+   		{
+   			"id": "d616ac82cc7f87153112d75a711c5c3c",
+   			"email_domain": "cool.cats",
+   			"enabled": true
+   			// ...
+   		}
+   	],
+   	"success": true,
+   	"errors": [],
+   	"messages": []
+   }
+   ```
 
 2. Disable the SSO connector:
 
-```bash title="cURL command"
-curl --request PATCH \
-'https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/sso/v2/connectors/2828' \
---header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
---header "Content-Type: application/json" \
---data '{
-  "sso_connector_status": "DIS"
-}'
-```
-
-```json title="Response"
-{
-	"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"`.
+   ```bash title="cURL command"
+   curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/sso_connectors/{connector_id}" \
+     --request PATCH \
+     --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
+     --json '{
+       "enabled": false
+     }'
+   ```
+
+   ```json output
+   {
+   	"result": [
+   		{
+   			"id": "d616ac82cc7f87153112d75a711c5c3c",
+   			"email_domain": "cool.cats",
+   			"enabled": false
+   			// ...
+   		}
+   	],
+   	"success": true,
+   	"errors": [],
+   	"messages": []
+   }
+   ```
+
+Users can now log in using their Cloudflare account email and password. If a user does not have a password, they can use the [forgot password](/fundamentals/user-profiles/change-password-or-email/#forgot-your-password) method on the login page to create one.
 
 ## Change your team name
 
-Cloudflare does not allow you to change your <GlossaryTooltip term="team name">team name</GlossaryTooltip> while dashboard SSO is enabled. To change your team name, you must disable dashboard SSO and reach out to your account team.
+Cloudflare does not allow you to change your <GlossaryTooltip term="team name">team name</GlossaryTooltip> while a SSO connector is created. To change your team name, you must disable and delete your SSO connector(s).
 
 :::caution
-Before disabling SSO, make sure you have access to your Cloudflare account email. This will allow you to reset your password in case you get logged out of the Cloudflare dashboard.
+Before disabling SSO, make sure you have access to your Cloudflare user email. This will allow you to reset your password in case you get logged out of the Cloudflare dashboard.
 :::
 
 1. In [Zero Trust](https://one.dash.cloudflare.com/), go to **Settings** > **Authentication**.
-2. If SSO is enabled, turn off **Cloudflare dashboard SSO**. This action can only be performed by Super Administrators.
-3. Ask your account team to delete your **SSO App** from **Access** > **Applications**. The SSO app cannot be deleted using the Zero Trust dashboard or API.
-4. Go to **Settings** > **Custom Pages**.
-5. Under **Team domain**, select **Edit** to enter the new team name. Select **Save**.
-6. In your identity provider, update your Cloudflare integration with the new team name. For example, if you are using a SAML IdP, you will need to update the Single Sign-on URL and Entity ID to `https://<new-team-name>.cloudflareaccess.com/cdn-cgi/access/callback`.
-7. Ask your account team to reactivate your SSO domain. Once your SSO domain is reactivated, a new **SSO App** application will appear in Zero Trust under **Access** > **Applications**.
-8. In Zero Trust, go to **Settings** > **Authentication**.
-9. Turn on **Cloudflare dashboard SSO** to re-enable SSO.
-
-
+2. Turn off **Cloudflare dashboard SSO** for any enabled domains. This action can only be performed by Super Administrators.
+
+3. Get all SSO connectors for your account.
+
+   ```bash title="cURL command"
+   curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/sso_connectors" \
+     --request GET \
+     --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
+   ```
+
+4. Disable any active SSO connectors using the `id` of each connector from the previous step.
+
+   ```bash title="cURL command"
+   curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/sso_connectors/{connector_id}" \
+     --request PATCH \
+     --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
+     --json '{
+       "enabled": false
+     }'
+   ```
+
+5. Delete all SSO connectors using the `id` of each connector from the previous step.
+
+   ```bash title="cURL command"
+   curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/sso_connectors/{connector_id}" \
+     --request DELETE \
+     --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
+   ```
+
+6. In [Zero Trust](https://one.dash.cloudflare.com/), go to **Settings** > **Custom Pages**.
+7. Under **Team domain**, select **Edit** to enter the new team name. Select **Save**.
+8. In your identity provider, update your Cloudflare integration with the new team name. For example, if you are using a SAML IdP, you will need to update the Single Sign-on URL and Entity ID to `https://<new-team-name>.cloudflareaccess.com/cdn-cgi/access/callback`.
+9. Recreate any deleted SSO connectors using the steps in [Register your domain with Cloudflare for SSO](/cloudflare-one/applications/configure-apps/dash-sso-apps/#2-register-your-domain-with-cloudflare-for-sso).
+10. Follow the verification and enable steps after recreating the SSO connectors.