Authorization code received. You can close this tab.
") print(f"CODE={code}", flush=True) elif "error" in params: err = params.get("error", [""])[0] desc = params.get("error_description", [""])[0] self.send_response(200) self.send_header("Content-Type", "text/html") self.end_headers() self.wfile.write(f"{err}: {desc}
".encode()) print(f"ERROR: {err} - {desc}", flush=True) else: self.send_response(400) self.end_headers() self.wfile.write(b"Unexpected request") print(f"Unexpected: {self.path}", flush=True) import threading threading.Thread(target=self.server.shutdown).start() def log_message(self, format, *args): pass print("Listening on http://localhost:8400 ...", flush=True) print("Open the authorization URL in your browser.", flush=True) http.server.HTTPServer(("", 8400), Handler).serve_forever() ' ``` **Important**: Use a timeout of at least 120000ms for this bash command since the user needs time to authenticate in the browser. Tell the user to open the authorization URL in their browser. After they authenticate with their IdP, the browser will redirect to `http://localhost:8400/callback?code=`,
the server will capture it and shut down.
## Step 7: Exchange Code for Token
```bash
curl -s -X POST \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=authorization_code" \
-d "code=" \
-d "client_id=" \
-d "redirect_uri=http://localhost:8400/callback" \
-d "code_verifier="
```
Expected response:
```json
{
"access_token": "oauth:",
"token_type": "bearer",
"expires_in": 900,
"scope": "",
"resource": "https:///",
"refresh_token": "oauth:"
}
```
Save the **access_token** and **refresh_token**.
## Step 8: Access the Protected Resource
```bash
curl -s https:/// \
-H "Authorization: Bearer "
```
This should now return the actual content behind Cloudflare Access.
## Step 9: Refresh the Token (if needed)
If the access token expires (default 900 seconds), use the refresh token:
```bash
curl -s -X POST \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=refresh_token" \
-d "refresh_token=" \
-d "client_id="
```
## Quick Reference: Full Flow Summary
```
1. curl -sI # Detect 401 + www-authenticate header
2. curl -s # Get authorization server
3. curl -s /.well-known/oauth-authorization-server # Get endpoints
4. POST # Register public client
5. Generate PKCE code_verifier + challenge # S256, alphanumeric start
6. Start localhost:8400 listener # Catch callback
7. User opens authorization URL # Browser-based IdP auth
8. POST # Exchange code for token
9. curl -H "Authorization: Bearer " # Access resource
```
## Troubleshooting
| Problem | Cause | Fix |
| ------------------------------------------------------- | ------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| `code_challenge_method must be S256 for public clients` | Code challenge starts with `-` or `_`, corrupting the URL parameter | Regenerate until challenge starts with `[a-zA-Z0-9]` |
| `invalid_grant` on token exchange | Code expired or verifier mismatch | Redo the auth flow; codes are single-use and short-lived |
| 401 after using token | Token expired (default 15 min) | Use refresh token to get a new access token |
| No `www-authenticate` header | Site doesn't support OAuth resource metadata | Fall back to `cloudflared access curl` or browser auth |
| No `registration_endpoint` in AS metadata | Dynamic registration not enabled | Must use a pre-registered client or different auth method |
| Port 8400 already in use | Previous listener didn't shut down | Kill the process or use a different port (update redirect_uri accordingly) |
````
# Event subscriptions
import { Render } from "~/components";
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **Access settings**.
2. Under **Allow multi-factor authentication (MFA)**, select the [MFA methods](#supported-mfa-methods) you want to allow in your organization.
3. Set an **Authentication duration**. This determines how long a user can log in to Access without being prompted for MFA again. If the user does not have an active MFA session for the required authenticator method, they must complete MFA in addition to IdP authentication.
4. (Optional) To avoid double prompting a user for MFA, you can enable [**Use identity provider MFA**](#use-identity-provider-mfa). This will check the AMR value passed from the identity provider at the time of authentication, if that AMR value passes an allowed MFA method, the user will not be prompted for MFA for the duration configured.
5. (Optional) To apply your MFA methods and authentication duration to all Access applications, select **Apply global MFA settings by default**. You can [override the global MFA settings](/cloudflare-one/access-controls/policies/mfa-requirements/#configure-independent-mfa-for-an-application) for individual applications and policies.
:::note
The [App Launcher](/cloudflare-one/access-controls/access-settings/app-launcher/) is exempt from the global MFA requirement. Users must be able to access the App Launcher without MFA to enroll their authenticators.
:::
6. Select **Save**.
1. Get your existing Zero Trust organization configuration:
After you turn on independent MFA, users can [enroll authenticators](#enroll-authenticators) through the [App Launcher](/cloudflare-one/access-controls/access-settings/app-launcher/).
### Configure PIV key requirements
If you plan to use PIV keys for [MFA for infrastructure applications](/cloudflare-one/access-controls/policies/mfa-requirements/#infrastructure-applications), configure the PIV key requirements in your organization's Access settings. These requirements determine which PIV keys users can enroll.
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **Access settings**.
2. Under **Allow multi-factor authentication (MFA)**, turn on the "Personal Identity Verification (PIV) key" authenticator.
3. Configure the following settings:
| Setting | Description | Options |
| ----------------- | ---------------------------------------------- | --------------------------------------------------------------- |
| **Key type** | The SSH key algorithm | ECDSA, Ed25519, RSA |
| **Key size** | The key length in bits | ECDSA: 256, 384, 521. RSA: 2048, 3072, 4096 |
| **PIN policy** | When the user must enter their PIV PIN | `never`, `once` (once per session), `always` (every use) |
| **Touch policy** | When the user must touch the hardware key | `never`, `always` (every use), `cached` (cached for 15 seconds) |
| **Require FIPS** | Require the PIV key to be on a FIPS-validated device | `true`, `false` |
4. Select **Save**.
:::note
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Resources** > **Lists**.
2. Select **Create new list**.
3. Enter a **List name** (for example, `Approved security keys`) and an optional description.
4. Set **List type** to **MFA AAGUIDs**.
5. Add one or more AAGUID entries:
- To add predefined AAGUIDs, select authenticators from the **Known authenticators** list.
- To add a custom AAGUID, fill out the following fields:
- **MFA AAGUIDs** — The AAGUID of the authenticator, in 32-character hexadecimal format without dashes (for example, `8c39ee867f9a4a959ba3f6b097e5c2ee`).
- **Description** — An optional label such as the authenticator's name and model.
6. Select **Save**.
Send a `POST` request to create the list:
:::tip
You can look up AAGUIDs for common authenticators in the [FIDO Alliance Metadata Service](https://fidoalliance.org/metadata/). Most vendors also publish AAGUIDs for their hardware on their support sites.
:::
### 2. Assign an AAGUID list to your organization
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **Access settings**.
2. Under **Allow multi-factor authentication (MFA)**, go to **Limit MFA to specific authentication methods**.
3. Select an existing [AAGUID list](#1-create-an-aaguid-list).
4. Select **Save**.
After you save, only authenticators whose AAGUIDs appear in the list can be enrolled. Users with previously enrolled security keys or biometrics outside the list can continue to use them until they are [deleted by an administrator](#delete-a-user-authenticator). A previously enrolled FIDO2 key outside the list stops working on the next connection. To remove the restriction, unset the AAGUID list.
1. Get your existing Zero Trust organization configuration:
:::note
AAGUID restrictions and [AMR matching](#use-identity-provider-mfa) can both be turned on simultaneously, but AMR matching is more permissive than independent MFA when AAGUID restrictions are configured. Most identity providers do not include AAGUID information in their AMR claims, so Access cannot verify that the authenticator used for IdP MFA is in the list of approved AAGUIDs. If the IdP returns a matching AMR value, Access will skip the independent MFA prompt regardless of which authenticator the user used at the IdP.
:::
## Use identity provider MFA
If your identity provider already prompts users for MFA, you can configure Access to accept that MFA instead of prompting again. Access checks the Authentication Method Reference (AMR) claim returned by the IdP, as defined in [RFC 8176](https://datatracker.ietf.org/doc/html/rfc8176). If the AMR value matches an [allowed authenticator type](#supported-mfa-methods) for the application or policy, Access skips the independent MFA prompt.
### Supported AMR values
| AMR value | Matches Access authenticator type | Description |
| --------- | --------------------------------- | -------------------------------------- |
| `hwk` | Security key | Proof-of-possession of a hardware key |
| `swk` | Security key | Proof-of-possession of a software key |
| `otp` | Authenticator application | One-time password |
| `face` | Biometrics | Facial recognition |
| `fpt` | Biometrics | Fingerprint |
| `iris` | Biometrics | Iris scan |
| `retina` | Biometrics | Retina scan |
| `vbm` | Biometrics | Voice biometric |
Access ignores AMR values that do not map to a supported authenticator type (for example, `pwd`, `sms`, `tel`, `geo`, `kba`, `sc`, `pin`, `user`, `mca`, `rba`, `wia`).
### Turn on AMR matching
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **Access settings**.
2. Under **Allow multi-factor authentication (MFA)**, turn on **Use identity provider MFA**.
3. Under **Authentication Method Reference (AMR) matching duration**, set how long a successful IdP MFA remains valid. During this period, users can log in to Access without an additional MFA prompt. You can set a custom duration (default 24 hours) or check for a [valid AMR value](#supported-amr-values) on every login.
4. Select **Save**.
1. Get your existing Zero Trust organization configuration:
### When AMR matching is skipped
Access does not apply AMR matching in the following cases:
- The IdP does not return an `amr` claim.
- The IdP returns only AMR values that do not map to an [allowed authenticator type](#supported-mfa-methods) for the application or policy.
- The user's AMR matching session has expired because they last performed MFA via their IdP longer ago than the configured AMR matching duration.
In these cases, Access falls back to checking for existing MFA sessions. If there are no valid MFA sessions, Access prompts the user to complete independent MFA.
:::note
Identity providers differ in how they populate the `amr` claim. Some providers, including Okta, may return provider-specific values such as `pop` that are not part of RFC 8176. Test the behavior with your IdP before relying on AMR matching for production applications.
:::
## Turn off independent MFA
:::caution
Turning off independent MFA removes MFA protection on all Access applications. Before turning off independent MFA, verify that your Access policies provide adequate coverage. Remove [custom MFA settings](/cloudflare-one/access-controls/policies/mfa-requirements/) from any applications and policies that use it, then turn off independent MFA at the organization level.
:::
To turn off independent MFA for the organization:
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **Access settings**.
2. Under **Allow multi-factor authentication (MFA)**, turn off **Apply global MFA settings by default**.
3. Turn off all MFA methods (**Biometrics**, **Security key**, and **Authenticator application**).
If you get an error updating MFA settings, ensure that you have removed custom MFA settings from all applications and policies.
1. Get your existing Zero Trust organization configuration:
## Enroll authenticators
Users enroll authenticators through the [App Launcher](/cloudflare-one/access-controls/access-settings/app-launcher/).
If a user already has at least one authenticator enrolled, Access requires them to [verify with an existing MFA method](#mfa-verification-for-authenticator-changes) before they can add a new authenticator.
To enroll an authenticator:
1. Go to your organization's App Launcher at `.cloudflareaccess.com`.
2. Log in with your identity provider or with a one-time PIN (OTP).
3. Go to **Account** > **MFA devices** > **Add an MFA device**.
:::note
Administrators can also share a direct enrollment link to help onboard users: `.cloudflareaccess.com/AddMfaDevice`
:::
4. If you already have an MFA device enrolled, complete the MFA verification prompt.
5. Select the authenticator type you want to enroll and follow the on-screen instructions.
1. Select **Authenticator application**.
2. Scan the QR code with your authenticator app (for example, Google Authenticator, Microsoft Authenticator, or Authy). Alternatively, you can manually enter the setup key into your authenticator app. Use SHA1 as the hash function and set the time-step size to 30 seconds.
3. Enter the 6-digit time-based one-time password (TOTP) generated by your authenticator app to verify enrollment.
:::note
You can only have one TOTP authenticator enrolled at a time. If you use multiple devices, scan the same QR code on each device during enrollment. To replace an existing TOTP authenticator, delete it first and then enroll a new one.
:::
1. Select **Security key**.
2. When your browser prompts you, insert your security key and follow the on-screen instructions.
3. After your browser confirms the registration, the security key is enrolled.
You can enroll multiple security keys for backup purposes.
1. Select **Biometrics** > **Register biometrics**.
2. You will be prompted to enroll with an authenticator type that is available on your device (for example, **Add macOS Touch ID** or **Add Windows Hello**).
3. After your browser confirms the registration, the platform authenticator is enrolled.
PIV key enrollment requires additional client-side setup and is only used for [MFA with infrastructure applications](/cloudflare-one/access-controls/policies/mfa-requirements/#infrastructure-applications). For full instructions, refer to [Enroll a PIV key for infrastructure apps](#enroll-a-piv-key-for-infrastructure-apps).
FIDO2 key enrollment requires additional client-side setup and is only used for [MFA with infrastructure applications](/cloudflare-one/access-controls/policies/mfa-requirements/#infrastructure-applications). This method is separate from browser-based security key enrollment. For full instructions, refer to [Enroll a FIDO2 key for infrastructure apps](#enroll-a-fido2-key-for-infrastructure-apps).
You can now use these authenticators to log in to your organization's applications.
### Enroll a FIDO2 key for infrastructure apps
Before users can enroll, turn on the **FIDO2 key** authenticator in your organization's [global MFA settings](#turn-on-independent-mfa).
The App Launcher generates the enrollment command for your account. Do not construct the enrollment command manually.
:::note
On macOS, install OpenSSH with Homebrew before you run the command. The `ssh-keygen` included with macOS does not support FIDO2 keys. On Linux, use an OpenSSH build that includes `libfido2` support.
:::
1. Go to your organization's App Launcher at `.cloudflareaccess.com`.
2. Log in with your identity provider or a one-time PIN (OTP).
3. Go to **Account** > **MFA devices** > **Add an MFA device** > **FIDO2 key**.
4. Select the tab for your operating system.
5. Copy the enrollment command shown in the App Launcher.
6. Run the command in a local terminal on the device you use for SSH.
7. Follow the prompts, then copy the JSON output.
8. Return to the App Launcher and paste the JSON into the enrollment field.
9. Complete the enrollment.
#### Configure your SSH client for a FIDO2 key
The command creates the identity at `~/.ssh/id_ed25519_sk_cf`.
Add the following configuration to your `~/.ssh/config` file:
```txt
Host *
IdentityFile ~/.ssh/id_ed25519_sk_cf
```
Alternatively, supply the identity when you connect:
```sh
ssh -i ~/.ssh/id_ed25519_sk_cf @
```
For more information on how OpenSSH uses FIDO2 hardware keys, refer to Yubico's [Securing SSH with FIDO2](https://developers.yubico.com/SSH/Securing_SSH_with_FIDO2.html).
### Enroll a PIV key for infrastructure apps
PIV key enrollment is separate from the general authenticator enrollment above and requires additional client-side setup.
Before enrolling, you must have a YubiKey with firmware 4.3 or later and a key generated in PIV slot `9a`. If you have not generated a PIV key yet, refer to [Generate a PIV key](#generate-a-piv-key).
#### Generate a PIV key
If you do not already have a PIV key on your YubiKey, generate one in slot `9a`:
```bash
ykman piv keys generate \
--algorithm ECCP256 \
--pin-policy once \
--touch-policy always \
9a pubkey.pem
```
Touch your YubiKey when it blinks to confirm key generation. Then create a self-signed certificate to make the key visible to SSH agents:
```bash
ykman piv certificates generate --subject "CN=SSH-Identity" 9a pubkey.pem
```
After generating the key, [generate attestation certificates](#generate-attestation-certificates) and continue with enrollment.
#### Generate attestation certificates
Attestation certificates prove that the key was generated on genuine hardware. Run the following commands to export them from your YubiKey:
```bash
ykman piv keys attest 9a leaf.pem
ykman piv certificates export f9 intermediate.pem
```
- `leaf.pem` contains the public key and metadata for the key in slot `9a`.
- `intermediate.pem` is the YubiKey attestation CA certificate.
#### Upload certificates to Cloudflare
1. Go to your organization's App Launcher at `.cloudflareaccess.com`.
2. Log in with an identity provider (IdP), a one-time pin, or with Cloudflare as your IdP.
3. Go to **Account** > **MFA devices** > **Add an MFA device**.
4. Select **PIV key**.
5. Paste the contents of `leaf.pem` into the **Leaf certificate** field.
6. Paste the contents of `intermediate.pem` into the **Intermediate certificate** field.
7. Select **Enroll**.
Access extracts and stores the SSH public key from your certificate for future authentication to infrastructure apps. You can enroll multiple PIV keys for backup purposes.
#### Configure your SSH client
After enrollment, configure your SSH client to use the PIV key. The following example uses `yubikey-agent` on macOS. For Linux, refer to the [yubikey-agent documentation](https://github.com/nicholasgasior/yubikey-agent).
1. Install and start `yubikey-agent`:
```bash
brew install yubikey-agent
brew services start yubikey-agent
```
2. Extract the SSH public key from your leaf certificate:
```bash
openssl x509 -in leaf.pem -pubkey -noout | ssh-keygen -i -m PKCS8 -f /dev/stdin > ~/.ssh/id_yubikey.pub
```
3. Add the following to your `~/.ssh/config`:
```txt
Host *
IdentityAgent /opt/homebrew/var/run/yubikey-agent.sock
IdentitiesOnly yes
AddKeysToAgent yes
IdentityFile ~/.ssh/id_yubikey.pub
```
4. Verify that the key is loaded:
```sh
ssh-add -L
```
The output should show an `ecdsa-sha2-nistp256` key.
### Delete an authenticator
Users can delete their own authenticators from the App Launcher. If the user has at least one authenticator enrolled, Access requires them to [verify with an existing MFA method](#mfa-verification-for-authenticator-changes) before they can remove a device.
1. Go to your organization's App Launcher at `.cloudflareaccess.com`.
2. Go to **Account** > **MFA devices**.
3. Select the 3-dot menu next to the MFA device, then select **Remove MFA device**.
4. If you have other MFA devices enrolled, complete the MFA verification prompt.
Administrators can also [delete authenticators on behalf of users](/cloudflare-one/access-controls/access-settings/independent-mfa/#delete-a-user-authenticator).
### MFA verification for authenticator changes
When a user has at least one authenticator enrolled, Access requires MFA verification before the user can add or remove an authenticator from the App Launcher. This verification step is separate from the IdP login and uses the user's existing independent MFA device.
After the user completes MFA verification, they have 10 minutes to add or remove authenticators without additional prompts. This window is tied to the current device. After 10 minutes, or if the user switches to a different device, Access requires MFA verification again.
This prevents an attacker with compromised IdP credentials from modifying a user's enrolled authenticators. Even if an attacker gains access to the user's IdP session, they cannot bypass the independent MFA verification step without also possessing the user's enrolled authenticator. If a user loses their only authenticator and cannot verify, an administrator can delete it to allow re-enrollment. Refer to [Manage user authenticators](#manage-user-authenticators).
:::note
MFA verification is not required when a user enrolls their first authenticator, since they do not yet have an MFA device to verify with.
:::
## Manage user authenticators
Administrators can view and delete authenticators enrolled by users. This is useful for resolving lockouts or responding to security events.
### View user authenticators
To view a user's enrolled authenticators:
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Team & Resources** > **Users**.
2. Select a user.
3. Go to **MFA devices**. Each entry shows the authenticator's ID, its user-configured name, and the MFA method.
### Delete a user authenticator
If a user is locked out or you need to revoke an authenticator for security reasons, you can delete it from the dashboard or API.
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Team & Resources** > **Users**.
2. Select the user whose authenticator you want to delete.
3. Under **MFA devices**, find the authenticator and select **Delete**.
The user will need to enroll a new authenticator the next time they access an application that requires MFA.
Send a `DELETE` request to remove a specific authenticator:
### Lockout recovery
If a user loses access to all of their enrolled authenticators:
1. [Delete](#delete-a-user-authenticator) the user's authenticators.
2. The user can then access a protected application and will be provided a link to enroll a new authenticator.
3. Alternatively, share the direct enrollment link with the user: `.cloudflareaccess.com/AddMfaDevice`.
:::tip
To prevent lockouts, users should enroll multiple authenticators (for example, a security key and an authenticator application) when available.
:::
## Related links
- [Enforce MFA on applications and policies](/cloudflare-one/access-controls/policies/mfa-requirements/)
# Access settings
import { DirectoryListing } from "~/components";
team domain |
| [Application token](/cloudflare-one/access-controls/applications/http-apps/authorization-cookie/application-token/) | Allows the user to access a specific Access application. | [Policy session duration](#policy-session-duration), which defaults to the [application session duration](#application-session-duration) | The hostname protected by the Access application |
The user can access the application for the entire duration of the application token's lifecycle. When the application token expires, Cloudflare will automatically issue a new application token if the global token is still valid (and the user's identity still passes your Access policies). If the global token has also expired, the user will be prompted to re-authenticate with the IdP.
The global token expiration is usually set to equal or exceed the application token expiration. Setting a longer global token provides a more secure way to allow for longer user sessions, since the global token cannot be used to directly access an application.
In summary, Access checks sessions from most specific to least specific:
1. **[Client session](/cloudflare-one/team-and-resources/devices/cloudflare-one-client/configure/client-sessions/)** (if enabled) — Overrides all other durations. The user re-authenticates when this expires.
2. **[Policy session](#policy-session-duration)** — Controls access to a specific application for users matching a specific policy.
3. **[Application session](#application-session-duration)** — The default policy session duration for all policies in the application.
4. **[Global session](#global-session-duration)** — Controls how often the user must log in to the IdP across all applications.
Refer to the [Order of enforcement](#order-of-enforcement) flowchart for a visual representation.
/cdn-cgi/access/logout`
- `.cloudflareaccess.com/cdn-cgi/access/logout`
This action [revokes the user's session](#per-user) across all applications. Access will immediately clear the authorization cookie from the user's browser, and all previously issued tokens will stop being accepted in 20-30 seconds. The only difference between these two URLs is which domain the authorization cookie is deleted from. For example, going to `/cdn-cgi/access/logout` will remove the application cookie and make the logout action feel more instantaneous.
You can use these URLs to create custom logout buttons or links directly within your application.
:::note
At this time, end users cannot log themselves out on a per-application basis.
:::
## AJAX
Pages that rely heavily on AJAX or single-page applications can block sub-requests due to an expired Access token without prompting the user to re-authenticate.
You can configure Access to provide a `401` response on sub-requests with an expired session token. We recommend using this response code to either force a page refresh or to display a message to the user that their session has expired.
In order to receive a `401` for an expired session, add the following header to all AJAX requests:
`X-Requested-With: XMLHttpRequest`
# AI controls
import { DirectoryListing } from "~/components";
(self-hosted app)"]
mcp -- "Cf-Access-Token: <JWT>" --> app1["Internal API
(self-hosted app)"]
mcp -- "Cf-Access-Token: <JWT>" --> app2["Company wiki
(self-hosted app)"]
idp[Identity provider] <--> mcp
```
### Prerequisites
- Add your downstream applications (for example, your `Internal API` and `Company wiki`) as [self-hosted Access applications](/cloudflare-one/access-controls/applications/http-apps/self-hosted-public-app/).
- Add your MCP server as a [self-hosted Access application](/cloudflare-one/access-controls/applications/http-apps/self-hosted-public-app/).
### 1. Configure downstream applications
On each self-hosted application that the MCP server needs to access (for example, the `Internal API` and `Company wiki` apps), create a Linked App Token policy:
```
Access will now validate the JWT token against the Linked App Token rule and propagate the user's identity to the downstream application.
## SaaS MCP server (Access for SaaS with OAuth)
If your MCP server is registered as an [Access for SaaS OIDC application](/cloudflare-one/access-controls/ai-controls/secure-mcp-servers/) and implements [MCP OAuth](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization), it receives an OAuth `access_token` from Cloudflare Access. The MCP server forwards this token to downstream self-hosted applications in the `Authorization: Bearer` header.
This approach requires your MCP server to implement the OAuth authorization code flow. Use the [self-hosted MCP server approach](#self-hosted-mcp-server-recommended) if you want Cloudflare to handle authentication for you.
```mermaid
flowchart LR
accTitle: SaaS MCP server accessing internal applications
User --> client["MCP client"]
client --> mcp["MCP server
(Access for SaaS app)"]
mcp -- "Authorization: Bearer <token>" --> app1["Internal API
(self-hosted app)"]
mcp -- "Authorization: Bearer <token>" --> app2["Company wiki
(self-hosted app)"]
idp[Identity provider] <--> mcp
```
### Prerequisites
- Add your downstream applications (for example, your `Internal API` and `Company wiki`) as [self-hosted Access applications](/cloudflare-one/access-controls/applications/http-apps/self-hosted-public-app/).
- Add your MCP server as an [Access for SaaS OIDC application](/cloudflare-one/access-controls/ai-controls/secure-mcp-servers/#saas-managed-third-party-mcp-server).
### 1. Configure downstream applications
On each self-hosted application that the MCP server needs to access (for example, the `Internal API` and `Company wiki` apps), create a Linked App Token policy:
)` suffix before forwarding the name. |
| HTTP `User-Agent` | Used when valid MCP client information is unavailable. |
| Neither is present | The portal omits `X-Forwarded-User-Agent` and continues the request. |
An upstream server can record this header in logs or use it for diagnostics. Do not use it for authentication or authorization because the MCP client controls the value.
### Built-in portal tools
Every portal exposes the following built-in tools to MCP clients, in addition to the upstream server tools:
| Tool | Description |
| ----------------------------- | --------------------------------------------------------------------------------------------------- |
| `portal_list_servers` | Lists all available upstream servers with their ID, name, and whether they are currently turned on. |
| `portal_toggle_servers` | Opens a URL-based server selection page where you can turn servers on or off. |
| `portal_toggle_single_server` | Turns a single server on or off by server ID, without leaving the MCP client. |
When [context optimization](#optimize-context) is turned on, additional tools are exposed depending on the mode:
| Mode | Additional tools |
| -------------------- | ------------------------------------------------------------------------------------ |
| `minimize_tools` | `portal_query_tools` — Search tools by regex pattern and return full definitions. |
| `search_and_execute` | `portal_query_tools` and `portal_execute` — Search tools and execute them via proxy. |
### Session lifecycle
MCP `2026-07-28` requests are stateless and do not create an MCP protocol session. The portal retains authentication, server selection, and upstream OAuth state for the user's portal authorization grant.
Earlier 2025 clients create a session that persists until the user disconnects or the session expires after 24 hours of inactivity.
Users can turn individual servers on or off without disconnecting. For stateless requests, server toggles apply to every request that uses the same portal authorization grant. For legacy clients, toggles are scoped to the MCP session. Toggles do not affect other users.
### Naming
MCP server portals were previously referred to as **Agents Gateway** in some contexts. The API paths, Terraform resources, and internal codebases may still use `agents_gateway` or `agw` prefixes. The product name is **MCP server portals** and the dashboard navigation is **MCP Portals**.
## Prerequisites
- An [active domain on Cloudflare](/fundamentals/manage-domains/add-site/) for the portal URL that uses either a [full setup](/dns/zone-setups/full-setup/) or a [partial (`CNAME`) setup](/dns/zone-setups/partial-setup/)
- An [identity provider](/cloudflare-one/integrations/identity-providers/) configured on Cloudflare Zero Trust
## Add an MCP server
Add individual MCP servers to Cloudflare Access to bring them under centralized management.
To add an MCP server:
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **MCP Portals**.
2. Go to the **MCP servers** tab.
3. Select **Add MCP server**.
4. Enter any name for the server.
5. (Optional) Enter a custom string for the **Server ID**.
6. In **HTTP URL**, enter the full URL of your MCP server. For example, if you want to add the [Cloudflare Documentation MCP server](https://github.com/cloudflare/mcp-server-cloudflare/tree/main/apps/docs-ai-search), enter `https://docs.mcp.cloudflare.com/mcp`.
7. Add [Access policies](/cloudflare-one/access-controls/policies/) to show or hide the server in an [MCP server portal](#create-a-portal). The MCP server link will only appear in the portal for users who match an Allow policy. Users who do not pass an Allow policy will not see this server through any portals.
:::caution
Blocked users can still connect to the server (and bypass your Access policies) by using its direct URL. If you want to enforce authentication through Cloudflare Access, [configure Access as the server's OAuth provider](/cloudflare-one/access-controls/ai-controls/secure-mcp-servers/).
:::
8. Under **OAuth credentials**, select **Automatic (recommended)** to use DCR. Add the [dashboard callback URL](#dashboard-callback-url) to the OAuth provider's redirect URI allowlist.
9. Select **Save and connect server**.
10. If the MCP server supports OAuth, you will be redirected to log in to your OAuth provider. You can log in to any account on the MCP server. The account used to authenticate will serve as the admin credential for that MCP server. You can [configure an MCP portal](#create-a-portal) to use this admin credential to make requests.
Cloudflare Access will validate the server connection and retrieve a list of prompts and tools. Once the server is successfully connected, the [server status](#server-status) will change to **Ready**. You can now add the MCP server to an [MCP server portal](#create-a-portal).
### Connect a private MCP server
MCP server portals can connect to an MCP server available only on your private network. The MCP server URL, [OAuth protected resource metadata](https://www.rfc-editor.org/rfc/rfc9728.html), and DCR endpoint can use a private hostname when server-level Gateway routing is turned on. OAuth authorization and token endpoints must be accessible on the public Internet.
Before you add the server, connect its network to Cloudflare. Use [Cloudflare Tunnel](/cloudflare-one/networks/connectors/cloudflare-tunnel/) or another [Cloudflare One connector](/cloudflare-one/networks/connectors/). Configure a [private hostname route](/cloudflare-one/networks/connectors/cloudflare-tunnel/private-net/cloudflared/connect-private-hostname/) or [CIDR route](/cloudflare-one/networks/connectors/cloudflare-tunnel/private-net/cloudflared/connect-cidr/) for the server.
To add the private MCP server:
1. Follow the steps in [Add an MCP server](#add-an-mcp-server), and enter the private URL in **HTTP URL**.
2. Turn on **Route traffic through Cloudflare Gateway**. Private server registration and capability synchronization require this setting.
3. Select **Save and connect server**.
4. Complete the upstream OAuth flow, if required.
5. Wait for the server status to change to **Ready**. You can then add the server to a portal.
### Configure manual OAuth credentials
Use manual OAuth credentials when the upstream provider does not support [OAuth Dynamic Client Registration](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#dynamic-client-registration). This flow uses an OAuth application that you register with the upstream provider.
1. Add the MCP server with **OAuth** as its authentication method.
2. In **Zero Trust** > **Access controls** > **MCP Portals**, go to the **MCP servers** tab.
3. Find the server, select the three dots > **Edit**, and go to **Authentication**.
4. Under **OAuth credentials**, select **Manual credentials**.
5. Copy the displayed **Redirect URI to register at the upstream provider**. Add it to the OAuth application's allowed redirect URIs. For more information, refer to [Shared Cloudflare callback URL](#shared-cloudflare-callback-url).
6. Select **Discover OAuth endpoints**. If discovery fails, expand **Show OAuth endpoints (advanced)** and enter the **Authorization endpoint** and **Token endpoint**. You can also enter an optional **Revocation endpoint** and **Issuer**.
7. Enter the OAuth application's **Client ID** and **Client secret**.
8. (Optional) Enter the space-separated **Scope** values requested from users.
9. (Optional) Enter the **Token endpoint auth method** expected by the provider. Supported values are `client_secret_post` and `client_secret_basic`.
10. Select **Save server**.
Cloudflare stores the client secret encrypted and does not return it through the dashboard or API. When editing the server, leave **Client secret** blank to keep the existing value. To rotate the secret, create or activate the replacement at the upstream provider, enter the new value, and save the server.
Manual credentials require per-user authentication. Leave **Require user auth** enabled when you add the server to a portal. The server remains in **Waiting** status until the first user completes upstream OAuth. Cloudflare then retrieves the server's tools and prompts and changes its status to **Ready**.
### MCP Apps
[MCP Apps](https://modelcontextprotocol.io/extensions/apps/overview) — tools that declare a UI resource in their description — will also be available after successfully connecting to an MCP server. A list of MCP clients that support MCP Apps is available in the [Extension Support Matrix](https://modelcontextprotocol.io/extensions/client-matrix).
### Server status
The MCP server status indicates the server's connection and tool and prompt synchronization status in Cloudflare Access.
| Status | Description |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Error | The server could not be reached or returned an error. Refer to [error details](#error-details) to identify and fix the cause. |
| Sync Required | The server's OAuth credentials can no longer be refreshed and the server needs to be reauthenticated. To fix the issue, [reauthenticate the server](#reauthenticate-the-mcp-server). |
| Waiting | The server's tools and prompts are being synchronized. A server with manual OAuth credentials remains in this state until its first user completes upstream OAuth. |
| Ready | The server connected successfully and its tools and prompts were synchronized. This status does not guarantee that the server will connect or return resources when queried. |
#### Error details
When an MCP server is in the **Error** or **Sync Required** state, hover over its status in the dashboard to view available diagnostic information. The API returns these details in the `error_details` object:
| Field | Description |
| ------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `status_code` | The HTTP status code returned by the MCP server, if available. |
| `mcp_code` | The MCP protocol error code, if the server returned an MCP error. |
| `retryable` | Whether the error is likely to be temporary and the connection is worth retrying. |
| `is_upstream` | `true` if the MCP server returned the error; `false` if the connection to the MCP server failed. |
| `cause` | The underlying error message. |
If `is_upstream` is `true`, use `status_code`, `mcp_code`, and `cause` to troubleshoot the MCP server. If it is `false`, verify that the server URL is correct and reachable. Retry the sync when `retryable` is `true`; otherwise, correct the reported cause before trying again. Reauthenticate the server only when the error points to expired or invalid credentials.
### Reauthenticate the MCP server
To reauthenticate an MCP server in Cloudflare Access:
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **MCP Portals**.
2. Go to the **MCP servers** tab.
3. Select the server that you want to reauthenticate, then select **Edit**.
4. Select **Authenticate server**.
You will be redirected to log in to your OAuth provider. The account used to authenticate will serve as the new admin credential for this MCP server.
### Synchronize the MCP server
For servers that use DCR, Cloudflare Access synchronizes tools and prompts approximately every two hours. During synchronization, Cloudflare connects to your MCP server using the [admin credential](#reauthenticate-the-mcp-server) and fetches the current list of tools and prompts. If the admin credential's OAuth access token has expired, Cloudflare refreshes it automatically using the stored refresh token before connecting.
Resources are not synchronized or stored. When an MCP client sends a `resources/list` request, the portal fetches resources live from the upstream servers. Servers that cannot connect or respond are omitted from the result.
:::note
Synchronization uses the admin credential, not individual user credentials. If the admin credential's refresh token has expired or been revoked, the [server status](#server-status) will change to **Sync Required** and you will need to [reauthenticate the server](#reauthenticate-the-mcp-server). This will not impact end users' ability to connect to the MCP server. It will impact the ability to fetch tool and prompt information or additions and removals.
:::
To manually refresh the MCP server in Zero Trust:
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **MCP Portals**.
2. Go to the **MCP servers** tab and find the server that you want to refresh.
3. Select the three dots > **Sync capabilities**.
The MCP server page will show the updated list of tools and prompts. By default, new tools and prompts are automatically enabled. For mappings with `default_disabled` set to `true`, they remain hidden until explicitly enabled.
You can also trigger a sync via the API. The sync endpoint returns the current server state after synchronization, including the updated [server status](#server-status), tool count, and [error details](#error-details) if the sync failed.
### Upstream OAuth callback URLs
MCP server portals use upstream OAuth callback URLs to authorize administrators and end users so they can access MCP servers.
OAuth providers typically exact-match the full URI, including the path.
If your upstream OAuth provider restricts redirect URIs, add the URLs that match your server's configuration:
| OAuth configuration | **Use the Cloudflare-hosted OAuth callback** on? | Redirect URIs to allowlist at the upstream provider |
| --- | --- | --- |
| Automatic (DCR) | No | The [dashboard callback URL](#dashboard-callback-url) for administrator authorization. If users authorize with their own credentials, also add `https:///servers-callback` for each portal using this server. |
| Automatic (DCR) | Yes | The [dashboard callback URL](#dashboard-callback-url) for administrator authorization. If users authorize with their own credentials, also add `https://oauth-callbacks.cloudflareaccess.com/cdn-cgi/access/outbound-oauth-callback`. |
| Manual OAuth credentials | Not available | `https://oauth-callbacks.cloudflareaccess.com/cdn-cgi/access/outbound-oauth-callback`. The dashboard DCR callback URL is not used for this configuration. |
For automatic (DCR) servers, expand **Advanced settings** to access the **Use the Cloudflare-hosted OAuth callback** setting.
For manual OAuth configured through the API, register the [shared Cloudflare callback URL](#shared-cloudflare-callback-url) with the upstream provider. Set `is_shared_oauth_callback_enabled` to `true`. Cloudflare uses the shared callback URL regardless of the value of `registration_info.redirect_uris`, so you can omit this field. You cannot override the shared callback URL.
#### Dashboard callback URL
When Cloudflare registers the OAuth client using DCR, the dashboard uses the following callback URL:
```txt
https://dash.cloudflare.com//one/access-controls/ai-controls/mcp-server/oauth-callback/
```
The dashboard callback URL is scoped to the account and server.
Add the dashboard callback URL to the OAuth provider's redirect URI allowlist before authorizing the upstream MCP server. Otherwise, authorization may fail.
DCR uses the dashboard callback URL even when the **Use the Cloudflare-hosted OAuth callback** setting is on.
End users never use the dashboard callback URL to authorize the upstream MCP server.
#### Portal callback URL
When a user authorizes an upstream MCP server that requires per-user OAuth, the portal performs an OAuth authorization code flow with the upstream server on the user's behalf. As part of this flow, the portal registers a callback URL (`redirect_uri`) with the upstream server. The upstream server redirects to this URL after the user authorizes access.
When the **Use the Cloudflare-hosted OAuth callback** setting is off, the portal uses a callback URL on your portal domain:
```txt
https:///servers-callback
```
Add the callback URL to the OAuth provider's redirect URI allowlist.
Use `/servers-callback`, not `/server-callback`, for automatic (DCR) servers when the shared callback setting is off. Manual OAuth servers use the [shared Cloudflare callback URL](#shared-cloudflare-callback-url) instead.
#### Shared Cloudflare callback URL
When you configure an MCP server with manual OAuth credentials in the dashboard, Cloudflare uses the following shared callback URL for dashboard and per-user authorization:
```txt
https://oauth-callbacks.cloudflareaccess.com/cdn-cgi/access/outbound-oauth-callback
```
The **Use the Cloudflare-hosted OAuth callback** setting is not available when you configure manual OAuth credentials in the dashboard.
When Cloudflare uses DCR to register the OAuth client, turn on **Use the Cloudflare-hosted OAuth callback** to use the shared callback URL for per-user authorization. If the setting is off, per-user authorization uses the [portal-scoped callback URL](#portal-callback-url).
Use the shared callback URL if the upstream OAuth provider limits the number of allowed redirect URIs or if you want one callback URL for a server across multiple portals. DCR still uses the dashboard callback URL for administrator authorization, regardless of whether the **Use the Cloudflare-hosted OAuth callback** setting is on. The setting is off by default. Configure it separately for each MCP server that uses DCR.
To turn on the setting, go to **Zero Trust** > **Access controls** > **MCP Portals** > **MCP servers**, add or edit an MCP server that uses DCR, and turn on **Use the Cloudflare-hosted OAuth callback** under **Basic information** > **Advanced settings**.
## Create a portal
To create an MCP server portal:
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **MCP Portals**.
2. Select **Add MCP server portal**.
3. Enter any name for the portal.
4. Under **Custom domain**, select a domain from an active zone in your account. You can optionally specify a subdomain.
5. [Add MCP servers](#add-an-mcp-server) to the portal.
6. (Optional) Under **MCP servers**, [configure the tools and prompts](#manage-tools-and-prompts) available through the portal.
7. (Optional) Configure **Require user auth** for servers that support OAuth: - `Enabled`: (default) User will be prompted to utilize their own login credentials to establish a connection with the MCP server. - `Disabled`: Users who are connected to the portal will automatically have access to the MCP server via its [admin credential](#reauthenticate-the-mcp-server).
8. Add [Access policies](/cloudflare-one/access-controls/policies/) to define the users who can connect to the portal URL.
:::caution
[Independent MFA](/cloudflare-one/access-controls/policies/mfa-requirements/#independent-mfa), [purpose justification](/cloudflare-one/access-controls/policies/require-purpose-justification/), and [temporary authentication](/cloudflare-one/access-controls/policies/temporary-auth/) will not be enforced for MCP servers that are authorized through an MCP portal. For example, if independent MFA is enabled on a policy assigned to a server, users will not be prompted to perform MFA to authorize the server after authenticating to the portal. Refer to [Policy limitations](#policy-limitations) for details.
:::
9. Select **Add an MCP server portal**.
10. (Optional) [Customize the login experience](#customize-login-settings) for the portal.
Users can now [connect to the portal](#connect-to-a-portal) at `https://./mcp` using an MCP client.
### Customize login settings
Cloudflare Access automatically creates an Access application for each MCP server portal. You can customize the portal login experience by updating Access application settings:
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **Applications**.
2. Find the portal that you want to configure, then select the three dots > **Edit**.
3. To configure identity providers for the portal:
1. Go to **Authentication**.
2. Select the [identity providers](/cloudflare-one/integrations/identity-providers/) that you want to enable for your application.
3. (Recommended) If you plan to only allow access via a single identity provider, turn on **Apply instant authentication**. End users will not be shown the [Cloudflare Access login page](/cloudflare-one/reusable-components/custom-pages/access-login-page/). Instead, Cloudflare will redirect users directly to your SSO login event.
4. To customize the block page:
1. Go to **Additional settings**.
2.
To set an alias that applies to a specific portal:
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **MCP Portals**.
2. Find the portal you want to configure, then select the three dots > **Edit**.
3. Go to the **Servers** tab.
4. Select the **Tools authorized** or **Prompts authorized** value for the server you want to configure (for example, `10/10`).
5. Find the tool or prompt you want to modify, then select the three dots > **Edit**.
6. In the modal, update the **Name** and **Description** as needed.
7. Select **Confirm**.
To set an alias that applies across all portals using a server:
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **MCP Portals**.
2. Go to the **MCP servers** tab.
3. Find the server you want to configure, then select the three dots > **Edit**.
4. Go to the **Tools** or **Prompts** tab.
5. Find the tool or prompt you want to modify, then select the three dots > **Edit**.
6. In the modal, update the **Name** and **Description** as needed.
7. Select **Confirm**.
8. Scroll to the bottom of the page and select **Save server**.
Tools and prompts that have been modified display a **Modified** label in the dashboard.
#### Set aliases with the API
Send a `PUT` request to the [update a MCP portal](/api/resources/zero_trust/subresources/access/subresources/ai_controls/subresources/mcp/subresources/portals/methods/update/) endpoint. Include the `alias` field for each tool or prompt you want to rename.
","token_endpoint_auth_method":"client_secret_basic","scope":"repo read:user"}}',
client_secret: "",
is_shared_oauth_callback_enabled: true,
}}
/>
The decoded `auth_credentials` object must contain:
- `auth_mode`: Must be `manual`.
- `config.authorization_endpoint` and `config.token_endpoint`: The upstream provider's OAuth endpoints. `issuer` and `revocation_endpoint` are optional.
- `registration_info.client_id`: The client ID issued by the upstream provider.
- `registration_info.redirect_uris`: Cloudflare uses only the first URI in the array. When `is_shared_oauth_callback_enabled` is `true`, omit this field. Cloudflare adds the [shared callback URL](#shared-cloudflare-callback-url).
- `registration_info.token_endpoint_auth_method`: Optional. Accepted values are `none`, `client_secret_post`, and `client_secret_basic`.
- `registration_info.scope`: Optional space-delimited scope string.
Before you create the server, add the [shared callback URL](#shared-cloudflare-callback-url) to the upstream provider's allowed redirect URIs. Set `is_shared_oauth_callback_enabled` to `true`. Cloudflare then uses the shared callback for dashboard authorization and for users who connect through any portal that contains the server.
Do not include `client_secret` or OAuth tokens inside `auth_credentials`. Send `client_secret` as the separate sibling field shown above.
To change the OAuth metadata, send `auth_credentials` in a `PUT` request to the [update an MCP server](/api/resources/zero_trust/subresources/access/subresources/ai_controls/subresources/mcp/subresources/servers/methods/update/) endpoint. An existing manual OAuth server can be updated without `client_secret`; the stored secret remains unchanged. Send a new `client_secret` to rotate it. A new manual OAuth server, or a server being changed to manual OAuth, requires a non-empty `client_secret`.
The client secret is write-only. Cloudflare encrypts it before storage and never returns it from read, create, or update requests. Responses also omit the raw `auth_credentials` value. Use `auth_config_summary.has_client_secret` and `auth_config_summary.client_secret_version` to confirm that a secret is configured and identify its current version.
#### Bearer authentication credentials
The `auth_credentials` field accepts two forms:
- **A raw bearer token** — the portal sends the value as the `Authorization: Bearer ` header on requests to the upstream MCP server:
```json
{
"auth_type": "bearer",
"auth_credentials": "your-bearer-token"
}
```
- **A JSON-encoded object of custom headers** — for upstream MCP servers that require multiple headers or a non-standard header name:
```json
{
"auth_type": "bearer",
"auth_credentials": "{\"headers\":{\"X-Api-Key\":\"\",\"X-Client-Id\":\"\"}}"
}
```
The value of `auth_credentials` must be a JSON string. The parsed object must have a `headers` field mapping header names to string values. The portal forwards all headers verbatim to the upstream MCP server.
### View tool-call analytics
Use the account endpoint to retrieve daily or monthly MCP tool-call counts across the account:
By default, these counts include only successful tool calls. To include errors and cached calls, set `response_status=all`. Use `error` or `cached` to count either status separately.
1. Get your existing MCP portal configuration:
The `allow_code_mode` API field is deprecated. Use `code_mode` for new integrations.
### Connect with Code Mode
The portal policy determines whether the MCP client needs a query parameter. For _Opt-in_, append `?codemode=search_and_execute` to the portal URL. For _On by default_, clients can append `?codemode=off` instead.
For example, an _Opt-in_ portal at `https://./mcp` uses this URL:
```txt
https://./mcp?codemode=search_and_execute
```
For MCP clients with server configuration files, use the portal URL with the query string parameter:
```json title="MCP client configuration with Code Mode"
{
"mcpServers": {
"example-portal": {
"url": "https://./mcp?codemode=search_and_execute"
}
}
}
```
When Code Mode is active, the portal advertises `portal_codemode_search` and `portal_codemode_execute`. The AI agent can discover tools and compose multiple tool calls in one execution.
For more information on building with Code Mode, refer to the [Code Mode SDK reference](/agents/tools/codemode/api-reference/).
## Route portal traffic through Gateway
When Gateway routing is turned on, calls to MCP servers protected by your MCP server portal are routed through [Cloudflare Gateway](/cloudflare-one/traffic-controls/). This makes portal traffic appear in your [Gateway HTTP logs](/cloudflare-one/insights/logs/dashboard-logs/gateway-logs/) alongside the rest of your organization's HTTP traffic. You can then create [Data Loss Prevention (DLP) policies](#example-gateway-policy) to detect and block sensitive data from being sent to your upstream MCP servers.
### How Gateway routing works
When a user calls a tool through the portal, the portal proxies the request to the upstream MCP server. With Gateway routing turned on, this outbound request passes through Cloudflare Gateway before reaching the upstream server. Gateway inspects the traffic and applies any matching HTTP policies, including DLP scanning.
Because portal traffic routes through Gateway, it also respects [Gateway egress policies](/cloudflare-one/traffic-controls/egress-policies/). This means outbound requests to upstream MCP servers will originate from your dedicated egress IPs or Gateway IP ranges rather than generic Cloudflare IPs. If your upstream MCP servers restrict inbound traffic by source IP (for example, to a VPN or corporate IP range), you can use egress policies to ensure portal traffic comes from a predictable set of IPs.
:::note
Server-level Gateway routing also applies to DCR and [admin credential synchronization](#synchronize-the-mcp-server). Portal-level Gateway routing applies only to real-time requests through that portal.
:::
### TLS decryption
DLP inspection requires Gateway to decrypt TLS traffic. For portal traffic, Gateway decrypts and inspects the payload automatically — you do not need to turn on the account-level [TLS decryption](/cloudflare-one/traffic-controls/http-policies/tls-decryption/) setting. Because the portal terminates the connection from the MCP client and re-originates the request through Gateway, Gateway decrypts portal traffic regardless of whether the global TLS decryption setting is on.
This automatic decryption applies only to traffic that flows through the portal. To inspect MCP traffic that does not pass through the portal — for example, an agent on a [device running the WARP client](/cloudflare-one/team-and-resources/devices/cloudflare-one-client/) connecting directly to an upstream MCP server — you must turn on [TLS decryption](/cloudflare-one/traffic-controls/http-policies/tls-decryption/) as you would for any other [HTTP policy](/cloudflare-one/traffic-controls/http-policies/).
:::note
Portal traffic ignores the global TLS decryption setting, but it still respects [Do Not Inspect](/cloudflare-one/traffic-controls/http-policies/#do-not-inspect) HTTP policies. If a Do Not Inspect policy matches portal traffic, Gateway does not decrypt it and DLP cannot scan it. Check that your Do Not Inspect policies do not unintentionally exempt your upstream MCP servers from inspection.
:::
### Supported transports
Gateway routing supports [Streamable HTTP](https://spec.modelcontextprotocol.io/specification/2025-03-26/basic/transports/#streamable-http) connections only. If an upstream MCP server is configured with a Server-Sent Events (SSE) endpoint (a URL ending in `/sse`), the portal will automatically attempt to connect using Streamable HTTP instead. If the upstream server does not support Streamable HTTP, the connection will fail when Gateway routing is turned on.
### Enable Gateway routing
You can route every server in a portal through Gateway or turn on routing for individual servers. If Gateway routing is enabled on the portal, it applies to every server in that portal regardless of the server-level setting.
#### Route every server in a portal
To route traffic from every MCP server in a portal through Gateway:
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **MCP Portals**.
2. Find the portal you want to configure, then select the three dots > **Edit**.
3. Under **Basic information**, turn on **Route traffic through Cloudflare Gateway**.
4. Select **Save**.
#### Route an individual server
To route traffic from one MCP server through Gateway without enabling Gateway routing for the entire portal:
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **AI controls**.
2. Go to the **MCP servers** tab.
3. Find the server you want to configure, then select the three dots > **Edit**.
4. Under **Basic information**, turn on **Route traffic through Cloudflare Gateway**.
5. Select **Save**.
The API field for the server-level setting is `secure_web_gateway`. It defaults to `false`.
Portal traffic will now appear in your [Gateway HTTP logs](/cloudflare-one/insights/logs/dashboard-logs/gateway-logs/). To apply DLP scanning, [create a Gateway HTTP policy](#example-gateway-policy).
### Example Gateway policy
To scan traffic for sensitive data, [create a Gateway HTTP policy](/cloudflare-one/data-loss-prevention/dlp-policies/) that matches both the MCP server and a predefined or custom [DLP profile](/cloudflare-one/data-loss-prevention/dlp-profiles/).
Gateway HTTP policies for MCP portal traffic must explicitly target the upstream MCP server. Ensure that your policy matches the upstream MCP server hostname (for example, `example-mcp-server.example.workers.dev`) rather than the portal URL (`.`).
For example, the following policy blocks traffic that contains [credentials and secrets](/cloudflare-one/data-loss-prevention/dlp-profiles/predefined-profiles/#credentials-and-secrets) or [financial information](/cloudflare-one/data-loss-prevention/dlp-profiles/predefined-profiles/#financial-information):
| Selector | Operator | Value | Logic | Action |
| ----------- | -------- | -------------------------------------------------- | ----- | ------ |
| Host | in | `example-mcp-server.example.workers.dev` | And | Block |
| DLP Profile | in | _Credentials and Secrets_, _Financial Information_ | | |
### What happens when a request is blocked
When a tool call matches a Block DLP policy, Gateway blocks it and the portal surfaces the block to the MCP client as an error rather than completing the tool call. This applies in both directions:
- **Tool call requests**: If the data the agent sends to a tool matches a DLP profile, Gateway blocks the outbound request and the agent receives an error indicating the request was blocked.
- **Tool call responses**: If the data the upstream server returns matches a DLP profile, Gateway blocks the response and the portal returns an error instead of the matched content.
The agent can retry the request, but it will continue to be blocked until the content no longer matches the policy.
### Limitations
- DLP [AI prompt profiles](/cloudflare-one/data-loss-prevention/dlp-profiles/predefined-profiles/#ai-prompt) do not apply to MCP server portal traffic. AI prompt profiles are designed for specific web client API paths and do not match the MCP protocol format. Use standard DLP profiles instead.
- SSE transport is not supported through Gateway. If your upstream MCP server only supports SSE, Gateway routing will not work for that server.
- Portal-level Gateway routing does not apply to DCR or background synchronization. To route these operations through Gateway, turn on Gateway routing for the individual server.
## Connect to a portal
Users can connect to your MCP server running at `https://./mcp` using [Workers AI Playground](https://playground.ai.cloudflare.com/), [MCP inspector](https://github.com/modelcontextprotocol/inspector), or [other MCP clients](/agents/model-context-protocol/guides/remote-mcp-server/#connect-from-an-mcp-client) that support remote MCP servers.
To test in Workers AI Playground:
1. Go to [Workers AI Playground](https://playground.ai.cloudflare.com/).
2. Under **MCP Servers**, enter `https://./mcp` for the portal URL.
3. Select **Connect**.
4. In the popup window, log in to your Cloudflare Access identity provider.
5. The popup window will list the MCP servers in the portal that require authentication. For each of these MCP servers, select **Connect** and follow the login prompts.
6. Select **Done** to complete the portal authentication process.
Workers AI Playground will show a **Connected** status and list the available tools. You can now ask the AI model to complete a task using an available tool. Requests made to an MCP server will appear in your [portal logs](#view-portal-logs).
For MCP clients with server configuration files, add the portal as a remote HTTP server. The exact URL field depends on your client. For example:
```json title="MCP client configuration for MCP portals"
{
"mcpServers": {
"example-mcp-server": {
"url": "https://./mcp"
}
}
}
```
### Portal homepage
When users visit the portal domain (`https://./`) in a browser, the portal displays a homepage with connection details and setup instructions.
:::note
Do not visit the MCP endpoint URL (`https://./mcp`) directly in a browser. The `/mcp` path is intended for MCP clients only and will return an `invalid token` error if accessed in a browser.
:::
The homepage shows:
- The portal name and your organization branding (if configured in Cloudflare Access)
- The MCP endpoint URL with a copy button
- Per-client connection instructions for Claude Desktop, Workers AI Playground, OpenCode, Windsurf, and other MCP clients with OS-specific file paths
Authenticated users see their email address and a **Sign out** button in the session bar. Users who are not authenticated can still view the homepage and connection instructions.
### Sign out of a portal
To end a portal session, select **Sign out** from the [portal homepage](#portal-homepage) (`https://./`). The sign-out flow:
1. Revokes all portal-level OAuth grants for your user.
2. Deletes all upstream MCP server OAuth states associated with your session.
3. Redirects through Cloudflare Access logout.
After sign-out, the portal displays a confirmation page with a summary of the revoked sessions. To reconnect, visit the portal homepage and authenticate again.
### Connect with a service token
You can connect to an MCP portal using an [Access service token](/cloudflare-one/access-controls/service-credentials/service-tokens/) for machine-to-machine access. Service tokens bypass the browser-based OAuth flow and authenticate using the `CF-Access-Client-Id` and `CF-Access-Client-Secret` headers.
A service token session is authorized twice: once at the portal URL, and once for each upstream MCP server it tries to reach through the portal. Both checks need a matching [Service Auth policy](/cloudflare-one/access-controls/policies/#service-auth).
#### Required configuration
| Where | Policy action | Include rule | Purpose |
| --------------------------------- | ------------- | ------------------ | ------------------------------------------------------------------------------ |
| Portal Access application | Service Auth | Your service token | Lets the bot connect to the portal URL. |
| Each linked MCP server Access app | Service Auth | Your service token | Lets the bot see and call that server's tools through the portal. |
| Server's portal mapping | n/a | n/a | **Require user auth** must be **off** so the portal uses the admin credential. |
:::note
**Require user auth** in the dashboard maps to the `on_behalf` field on the portal-server mapping in the API and Terraform. For each linked server you want a service token to reach, set `on_behalf` to `false`. Servers with `on_behalf: true` are excluded from service token sessions because they require a per-user OAuth grant that a service token cannot provide.
:::
If a linked MCP server does not have a Service Auth policy matching the token, that server is hidden from the bot's tool list.
#### Set up a service token connection
1. [Create a service token](/cloudflare-one/access-controls/service-credentials/service-tokens/#create-a-service-token) in your Zero Trust account.
2. Open the portal's Access application and add a Service Auth policy that includes the service token.
3. For each upstream MCP server you want the bot to reach:
1. Open the server's Access application and add a Service Auth policy that includes the same service token.
2. Open the portal and edit the server. Turn **Require user auth** off so the portal uses the [admin credential](#reauthenticate-the-mcp-server) for that server.
4. Connect from your MCP client with the service token headers.
To configure this flow with the API, set `servers[].on_behalf` to `false` in the [MCP portal request](/api/resources/zero_trust/subresources/access/subresources/ai_controls/subresources/mcp/subresources/portals/methods/create/). Create a `non_identity` Access policy with a `service_token` include rule. Attach the policy to the portal and each linked server Access application. For a complete Terraform example, refer to [Configure via Terraform](#configure-via-terraform).
To verify the connection, send an MCP `initialize` request with the service token headers:
```sh
curl https://./mcp \
-H "CF-Access-Client-Id: " \
-H "CF-Access-Client-Secret: " \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
--data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"service-token-test","version":"1.0.0"}}}'
```
For `mcp-remote`, pass the credentials through environment variables instead of storing them in the MCP client configuration:
```json title="MCP client configuration for service token connections"
{
"mcpServers": {
"example-portal": {
"command": "npx",
"args": [
"-y",
"mcp-remote@latest",
"https://./mcp",
"--header",
"CF-Access-Client-Id:${ACCESS_CLIENT_ID}",
"--header",
"CF-Access-Client-Secret:${ACCESS_CLIENT_SECRET}"
],
"env": {
"ACCESS_CLIENT_ID": "",
"ACCESS_CLIENT_SECRET": ""
}
}
}
}
```
:::note
Service tokens do not support per-user OAuth with upstream MCP servers. The portal uses the [admin credential](#reauthenticate-the-mcp-server) for every upstream request made by a service token session. Servers with **Require user auth** turned on are excluded from service token sessions because they require a per-user OAuth grant that a service token cannot provide.
:::
### Device authentication
MCP server portals require a browser-based authentication flow. [Device authentication](/cloudflare-one/team-and-resources/devices/cloudflare-one-client/) (picking up identity from the Cloudflare One Client without a browser redirect) is not currently supported for MCP portals. Users must complete the Access login flow in a browser when first connecting.
## Optimize context
MCP server portals support context optimization options that reduce how many tokens tool definitions consume in the model's context window. These options are useful when a portal aggregates many MCP servers or servers that expose a large number of tools.
To use context optimization, append the `optimize_context` query parameter to your portal URL when connecting from an MCP client.
### Minimize tools
The `minimize_tools` option strips tool descriptions and input schemas from all upstream tools, leaving only their names. The portal exposes a special `query` tool that agents use to search and retrieve full tool definitions on demand. Agents can discover tools without loading all definitions upfront.
This option provides up to 5x savings in token usage, though querying tool definitions before use adds a small amount of overhead.
To connect with `minimize_tools`, use the following portal URL:
```txt
https://./mcp?optimize_context=minimize_tools
```
For MCP clients with server configuration files:
```json title="MCP client configuration with minimize_tools"
{
"mcpServers": {
"example-portal": {
"url": "https://./mcp?optimize_context=minimize_tools"
}
}
}
```
### Search and execute
The `search_and_execute` option hides all upstream tools and exposes only two tools to the agent: `query` and `execute`. The `query` tool searches and retrieves tool definitions. The `execute` tool runs the upstream tools. The generated code runs in an isolated [Dynamic Worker](/dynamic-workers/) environment, which keeps authentication credentials and environment variables out of the model context.
This option reduces the initial token cost of portal tools to a small constant, regardless of how many tools are available. However, the agent becomes fully reliant on `query` to discover tools before it can call them.
To connect with `search_and_execute`, use the following portal URL:
```txt
https://./mcp?optimize_context=search_and_execute
```
For MCP clients with server configuration files:
```json title="MCP client configuration with search_and_execute"
{
"mcpServers": {
"example-portal": {
"url": "https://./mcp?optimize_context=search_and_execute"
}
}
}
```
For more information on the Code Mode pattern behind `search_and_execute`, refer to [Code Mode](/agents/tools/codemode/).
## Manage portal sessions
Once connected to a portal, users can manage their upstream MCP server sessions without leaving their MCP client. The portal uses [MCP elicitations](https://modelcontextprotocol.io/specification/2025-03-26/server/elicitation) to provide a server selection page where you can enable or disable servers, log out of individual servers, and reauthenticate.
### Return to the server selection page
To manage your server connections during an active session, ask your AI agent to take you back to the server selection page. For example, prompt your agent with:
> Take me back to the server selection page.
The portal returns an authorization URL. Open this URL in your web browser to access the server selection page:
```txt
https://./authorize?elicitationId=
```
From this page you can:
- **Enable or disable servers** — Toggle individual upstream MCP servers on or off. Disabling a server removes its tools from the active session, which reduces context window usage.
- **Log out and reauthenticate** — Log out of a server and log back in if you need to change which data the server has access to. For example, you may need to reauthenticate with different permissions.
### Enable or disable a server inline
You can also enable or disable a specific server directly from your MCP client without visiting the server selection page. For example:
> Enable the wiki server.
> Disable my Jira server.
The portal toggles the server and refreshes the active tool list immediately. The resulting list only includes tools and prompts allowed by the portal policy. A server can be enabled while exposing no tools or prompts if its allowlist is empty.
### Reauthenticate a server
When an upstream MCP server token expires, the portal prompts you to reauthenticate from within your MCP client. Open the provided URL in your browser and complete the login to restore the session.
If your MCP client does not display the reauthentication prompt, use its authentication controls to remove the saved portal credentials. Then reconnect to the portal.
### Authorize new servers
When an admin adds a new upstream MCP server to a portal, the portal automatically prompts connected users to authorize the new server. The portal batches admin changes and redirects you to the authorization flow once, rather than interrupting for each individual server update.
## View portal logs
Portal logs allow you to monitor user activity through an MCP server portal. You can view logs on a per-portal or per-server basis.
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **MCP Portals**.
2. Find the portal or server that you want to view logs for, then select the three dots > **Edit**.
3. Select **Logs**.
### Log fields
| Field | Description |
| ---------- | --------------------------------------------------- |
| Time | Date and time of the request |
| Status | Whether the server successfully returned a response |
| Server | Name of the MCP server that handled the request |
| Capability | The tool used to process the request |
| Duration | Processing time for the request in milliseconds |
### Export logs with Logpush
:::note[Availability]
Only available on Enterprise plans.
:::
You can automatically export MCP portal logs to third-party storage destinations or security information and event management (SIEM) tools using [Logpush](/logs/logpush/). This allows you to integrate with your existing security workflows and retain logs for as long as your business requires.
To set up a Logpush job for MCP portal logs, refer to [Logpush integration](/cloudflare-one/insights/logs/logpush/). For a list of available log fields, refer to [MCP portal logs](/logs/logpush/logpush-job/datasets/account/mcp_portal_logs/).
## Known limitations
MCP server portals have the following known limitations:
- **Only remote HTTP MCP servers are supported.** MCP servers that use [stdio transport only](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports) (for example, `github/github-mcp-server`) do not expose a remote HTTP endpoint and cannot be added to an MCP server portal. To use a stdio-only server, you must self-host it behind an HTTP endpoint and authenticate with a [bearer token or custom headers](#create-an-mcp-server).
- **Some MCP servers block proxy-based clients.** Certain MCP servers reject requests from proxy-based clients like MCP server portals, returning a `403` error on the registration endpoint. These servers are not compatible with MCP server portals until those providers add Cloudflare as a supported MCP client.
- **Manual OAuth capabilities are captured during the first user authorization.** Servers configured with [manual OAuth credentials](#configure-manual-oauth-credentials) remain in **Waiting** status until a user completes upstream OAuth. Cloudflare stores the tools and prompts returned during that connection. Background and manual capability synchronization do not refresh them.
- **Admin OAuth tokens can expire silently.** The admin credential used to [authenticate an MCP server](#reauthenticate-the-mcp-server) is subject to the upstream provider's token expiration policy. When the token expires, the server status changes to **Error** or **Sync Required** and the server will not appear in the portal for end users. Admins are not notified when this happens. Periodically check the [server status](#server-status) and [reauthenticate](#reauthenticate-the-mcp-server) servers that show an error.
- **Each portal supports up to 80 MCP servers.**
## Policy limitations
MCP servers use a dedicated Access application type (_mcp_) that does not support the following Access policy features when the server is authorized through a portal.
- **[Independent MFA](/cloudflare-one/access-controls/policies/mfa-requirements/#independent-mfa)** — Users will not be prompted to perform MFA through Cloudflare Access when authorizing a server, regardless of whether MFA global enforcement is enabled or whether an MFA policy is assigned to the server.
- **[Purpose justification](/cloudflare-one/access-controls/policies/require-purpose-justification/)** — Users will not be prompted to provide a purpose justification when authorizing a server.
- **[Temporary authentication](/cloudflare-one/access-controls/policies/temporary-auth/)** — Users will not be prompted to request access and approvers will not receive approval requests when a user authorizes a server.
These limitations only apply to servers that are being authorized through a portal. Access policy selectors such as Emails, Groups, Country, and Device Posture Checks will be enforced.
Independent MFA, purpose justification, and temporary authentication will be enforced for servers that are not authorized through a portal.
## Troubleshooting
### Portal creation fails because of a zone hold
Cloudflare creates a custom hostname for each portal custom domain. Portal creation fails when a zone hold that includes subdomains applies to this hostname.
[Release the zone hold](/fundamentals/account/account-security/zone-holds/#release-zone-holds) for the selected zone and each parent zone. Then create the portal again. A parent zone can belong to a different Cloudflare account.
### After authenticating to the portal, my user receives the error `No allowed servers available, check your Zero Trust Policies`.
1. An MCP portal and server must both have an attached Access policy. Ensure that all MCP servers assigned to the portal have their own associated policy.
2. The server's admin authentication may be expired. Check that the [server's status](#server-status) is **Ready**. If the status shows **Error** or **Sync Required**, [reauthenticate the server](#reauthenticate-the-mcp-server).
### The portal URL does not prompt for authentication when it is added to an MCP client.
1. Verify that the portal has an assigned Access policy.
2. Verify that the portal URL does not have any applied [Workers](/workers/configuration/routing/custom-domains/), [Page Rules](/rules/page-rules/manage/), [custom hostname](/cloudflare-for-platforms/cloudflare-for-saas/domain-support/) definitions, or any other configuration that may interfere with its ability to connect to the MCP client.
### The portal returns a `522` error.
A `522` error indicates that Cloudflare cannot reach the portal's origin. This typically means the DNS record for the portal hostname is missing or misconfigured.
1. Verify that a CNAME record exists for your portal subdomain pointing to `gateway.agents.cloudflare.com`.
2. Ensure the CNAME record has **Proxy status** turned on in Cloudflare DNS.
3. If you created the portal using the [API](#manage-portals-via-api) or the [Terraform provider](#configure-via-terraform), you must create the DNS record separately. Unlike the dashboard, the API and Terraform provider do not auto-create DNS records.
### An MCP server is stuck in `Waiting` status.
The `Waiting` status means Cloudflare is attempting to connect to the upstream MCP server and fetch its tools and prompts. If the server stays in this status:
1. Verify that the upstream MCP server URL is correct and the server is reachable.
2. Check that the upstream server supports [Streamable HTTP](https://spec.modelcontextprotocol.io/specification/2025-03-26/basic/transports/#streamable-http) or SSE transport. The portal will attempt multiple connection strategies automatically.
3. If the server requires authentication, verify that the admin credentials are valid by [reauthenticating the server](#reauthenticate-the-mcp-server).
4. Select the three dots > **Sync capabilities** to manually retry the connection.
### An MCP server shows `Stale` status.
A `Stale` status means the admin credential for the server could not be refreshed during the last synchronization attempt. The server's tools may still work for users who have their own OAuth tokens (servers with **Require user auth** turned on), but the admin credential needs to be refreshed.
To resolve this, [reauthenticate the server](#reauthenticate-the-mcp-server) with valid admin credentials.
### Tool calls fail with an `unauthorized` error.
1. If the server uses per-user OAuth (**Require user auth** is turned on), the user's OAuth token may have expired. Ask the user to [reauthenticate the server](#reauthenticate-a-server) from their MCP client.
2. If the server uses admin credentials, check the [server status](#server-status). A status of **Error** or **Sync Required** indicates the admin credential needs to be refreshed.
3. If the user recently changed permissions on the upstream service (for example, revoked OAuth scopes), they will need to reauthenticate.
### OAuth authentication fails with a redirect URI error when connecting to an upstream MCP server.
Errors such as `invalid_redirect_uri`, `invalid_client_metadata`, or `Redirect URI not allowed` indicate that the upstream OAuth provider rejected a redirect URI that Cloudflare used to perform callback. Verify that you added the correct callback URL to the upstream OAuth provider's redirect URI allowlist. For more information, refer to [Upstream OAuth callback URLs](#upstream-oauth-callback-urls).
Contact the upstream MCP server vendor if you do not control the allowlist.
### Tool calls fail when Gateway routing is turned on.
1. Verify that the upstream MCP server supports Streamable HTTP transport. SSE transport is not supported through Gateway.
2. If the upstream server URL ends in `/sse`, the portal automatically attempts to connect using Streamable HTTP on a `/mcp` path instead. If the server does not support this, the connection will fail.
3. Check [Gateway HTTP logs](/cloudflare-one/insights/logs/dashboard-logs/gateway-logs/) for DLP block events. If a DLP policy is blocking the traffic, the portal returns an error to the MCP client with the DLP rule ID.
### Users cannot connect from an MCP client
1. Verify that the client supports Streamable HTTP and OAuth discovery.
2. Configure the portal URL as a remote HTTP server.
3. If authentication fails repeatedly, use the client authentication controls to remove the saved portal credentials and reconnect.
### The portal homepage shows the wrong name or domain.
The portal homepage displays your Access organization name and branding. If the displayed name is incorrect:
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Settings** > **General** > **Team name**.
2. Update your team name. The change will take effect the next time a user visits the portal homepage.
# Secure MCP servers
import {
Render,
GlossaryTooltip,
Tabs,
TabItem,
APIRequest,
DashButton,
} from "~/components";
You can secure [Model Context Protocol (MCP) servers](https://www.cloudflare.com/learning/ai/what-is-model-context-protocol-mcp/) with Cloudflare Access. Choose an approach based on who manages the MCP server code and hostname:
| Approach | Best for | Auth handled by |
| ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
| [Customer-managed third-party MCP server](#customer-managed-third-party-mcp-server) | Third-party MCP server code running on a hostname you control in Cloudflare | The third-party MCP server |
| [SaaS-managed third-party MCP server](#saas-managed-third-party-mcp-server) | Third-party MCP servers hosted by the provider that support customer-provided OAuth or OIDC identity settings | Third-party MCP server, with Access as the OIDC provider |
## Customer-managed third-party MCP server
Use this setup when the MCP server runs on a hostname you control in Cloudflare, but the server code is managed by a third party and already handles its own OAuth flow. In this setup, do not enable Access Managed OAuth. You also do not need to add the MCP server hostname as a public hostname on the generated Access application.
1. Ensure the MCP server hostname has **Proxy status** turned on in Cloudflare DNS.
2. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **AI controls**.
3. Go to the **MCP servers** tab.
4. Select **Add an MCP server**.
5. Enter a name for the server.
6. In **HTTP URL**, enter the MCP server URL, including the MCP path. For example, `https://mcp.example.com/mcp`.
7. Configure [Access policies](/cloudflare-one/access-controls/policies/) to define the users who can use the MCP server.
8. MCP server on [Cloudflare Workers](/workers/) to show the Access for SaaS setup. For a SaaS-managed server, follow your provider's setup instructions and use the Access for SaaS values created in [Step 2](#2-create-an-access-for-saas-app). When users connect to the MCP server using an MCP client , they will be prompted to log in to your [identity provider](/cloudflare-one/integrations/identity-providers/) and are only granted access if they pass your [Access policies](/cloudflare-one/access-controls/policies/#selectors).
### Prerequisites
- Create a [Zero Trust organization](/cloudflare-one/setup/#2-create-a-zero-trust-organization).
- Configure [One-time PIN](/cloudflare-one/integrations/identity-providers/one-time-pin/) or connect a third-party [identity provider](/cloudflare-one/integrations/identity-providers/).
### 1. Deploy an example MCP server
To deploy our [example MCP server](https://github.com/cloudflare/ai/tree/main/demos/remote-mcp-cf-access) to your Cloudflare account:
1. Select the following button to launch the quickstart flow:
[](https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/ai/tree/main/demos/remote-mcp-cf-access)
2. Select the account that contains your Zero Trust organization.
3. On the **Create an application** page, configure the following fields:
- **Git account**: Select an existing account or connect a new GitHub or GitLab account.
- **Create private Git repository**: Choose whether the project repository should be public or private.
- **Project name**: `mcp-server-cf-access`
- **Select KV namespace**: _Create new_
- **Name your KV namespace**: `OAUTH_KV`
We will configure `ACCESS_CLIENT_ID` and the other secret values in a later step.
4. Select **Create and deploy**.
The MCP server will be deployed to your `*.workers.dev` subdomain at `mcp-server-cf-access..workers.dev`. A new git repository will be set up on your GitHub or GitLab account for your MCP server, configured to automatically deploy to Cloudflare each time you push a change or merge a pull request to the main branch of the repository.
You can use the [Wrangler CLI](/workers/wrangler) to create the MCP server on your local machine and deploy it to Cloudflare.
:::note[Prerequisites]
- Install [npm](https://docs.npmjs.com/getting-started)
- Install [Node.js](https://nodejs.org/en/)
:::
1. Open a terminal and clone our example project:
```sh
npm create cloudflare@latest -- mcp-server-cf-access --template=cloudflare/ai/demos/remote-mcp-cf-access
```
During setup, select the following options: - For _Do you want to add an AGENTS.md file to help AI coding tools understand
Cloudflare APIs?_, choose `No`. - For _Do you want to use git for version control?_, choose `No`. - For _Do you want to deploy your application?_, choose `No` (we will be making some changes before deploying).
2. Go to the project directory:
```sh
cd mcp-server-cf-access
```
3. Create a [Workers KV namespace](/kv/concepts/kv-namespaces/) to store the key. The binding name should be `OAUTH_KV` if you want to run the example as written.
```sh
npx wrangler kv namespace create "OAUTH_KV"
```
The command will output the binding name and KV namespace ID:
```sh output
{
"kv_namespaces": [
{
"binding": "OAUTH_KV",
"id": ""
}
]
}
```
4. Open `wrangler.jsonc` in an editor and insert your `OAUTH_KV` namespace ID:
```jsonc
"kv_namespaces": [
{
"binding": "OAUTH_KV",
"id": ""
}
],
```
5. You can now deploy the Worker to Cloudflare's global network:
```sh
npx wrangler deploy
```
The Worker will be deployed to your `*.workers.dev` subdomain at `mcp-server-cf-access..workers.dev`.
### 2. Create an Access for SaaS app
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **Applications**.
2. Select **Create new application**.
3. Select **SaaS application**.
4. In **Application**, enter a custom name (for example, `MCP server`) and select the textbox that appears below.
5. Select **OIDC** as the authentication protocol.
6. Select **Add application**.
7. In **Redirect URLs**, enter the authorization callback URL for your MCP server. The callback URL for our [example MCP server](#1-deploy-an-example-mcp-server) is
`https://mcp-server-cf-access..workers.dev/callback`.
8. Copy the following values to input into our example MCP server. Other MCP servers may require different sets of input values.
- **Client secret**
- **Client ID**
- **Token endpoint**
- **Authorization endpoint**
- **Key endpoint**
9. (Optional) Under **Advanced settings**, turn on [**Refresh tokens**](/cloudflare-one/access-controls/applications/http-apps/saas-apps/generic-oidc-saas/#advanced-settings) if you want to reduce the number of times a user needs to log in to the identity provider.
10. Configure [Access policies](/cloudflare-one/access-controls/policies/) to define the users who can access the MCP server.
11.
1. Make a `POST` request to the [Access applications](/api/resources/zero_trust/subresources/access/subresources/applications/methods/create/) endpoint:
.workers.dev/callback",
],
grant_type: ["authorization_code", "refresh_tokens"],
refresh_token_options: {
lifetime: "90d",
},
},
policies: ["f174e90a-fafe-4643-bbbc-4a0ed4fc8415"],
allowed_idps: [],
}}
/>
2. Copy the `client_id` and `client_secret` returned in the response.
3. Build the OAuth endpoint URLs using your team name and the `client_id` returned in the response:
| Endpoint | URL |
| ---------------------- | -------------------------------------------------------------------------------------------- |
| Token endpoint | `https://.cloudflareaccess.com/cdn-cgi/access/sso/oidc//token` |
| Authorization endpoint | `https://.cloudflareaccess.com/cdn-cgi/access/sso/oidc//authorization` |
| Key endpoint | `https://.cloudflareaccess.com/cdn-cgi/access/sso/oidc//jwks` |
### 3. Configure your MCP server
Your MCP server needs to perform an OAuth 2.0 authorization flow to get an `access_token` from the SaaS app created in [Step 2](#2-create-an-access-for-saas-app). When setting up the OAuth client on your MCP server, you will need to paste in the OAuth endpoints and credentials from the Access for SaaS app.
To add OAuth endpoints and credentials to our [example MCP server](#1-deploy-an-example-mcp-server):
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to the **Workers & Pages** page.
1. Create the following [Workers secrets](/workers/configuration/secrets/):
```sh
npx wrangler secret put ACCESS_CLIENT_ID
npx wrangler secret put ACCESS_CLIENT_SECRET
npx wrangler secret put ACCESS_TOKEN_URL
npx wrangler secret put ACCESS_AUTHORIZATION_URL
npx wrangler secret put ACCESS_JWKS_URL
```
2. When prompted to enter a secret value, paste the corresponding values obtained from the [Access for SaaS app](#2-create-an-access-for-saas-app).
| Workers secret | SaaS app field |
| -------------------------- | ---------------------- |
| `ACCESS_CLIENT_ID` | Client ID |
| `ACCESS_CLIENT_SECRET` | Client secret |
| `ACCESS_TOKEN_URL` | Token endpoint |
| `ACCESS_AUTHORIZATION_URL` | Authorization endpoint |
| `ACCESS_JWKS_URL` | Key endpoint |
:::note
Use the Client ID, Client secret, and OAuth endpoints copied from the Cloudflare One dashboard. Do not use the OAuth values from your [third-party identity provider](/cloudflare-one/integrations/identity-providers/generic-oidc/).
:::
3. Generate a random string for the cookie encryption key:
```sh
openssl rand -hex 32
```
Store the output of this command in a Workers secret:
```sh
npx wrangler secret put COOKIE_ENCRYPTION_KEY
```
### 4. Test the connection
You can now connect to your MCP server at `https://mcp-server-cf-access..workers.dev/mcp` using [Workers AI Playground](https://playground.ai.cloudflare.com/), [MCP inspector](https://github.com/modelcontextprotocol/inspector), or [other MCP clients](/agents/model-context-protocol/guides/remote-mcp-server/#connect-from-an-mcp-client) that support remote MCP servers.
To test in Workers AI Playground:
1. Go to [Workers AI Playground](https://playground.ai.cloudflare.com/).
2. Under **MCP Servers**, enter `https://mcp-server-cf-access..workers.dev/mcp` for the MCP server URL.
3. Select **Connect**.
4. A popup window will appear requesting access to the MCP server. Select **Approve**.
5. Follow the prompts to log in to your identity provider.
Workers AI Playground will show a **Connected** status. The MCP server should successfully obtain an `access_token` from Cloudflare Access.
## Next steps
To allow the MCP server to make authenticated requests to other self-hosted applications on behalf of the user, create a [Linked App Token](/cloudflare-one/access-controls/ai-controls/linked-apps/) policy on the downstream application. The MCP server forwards the `Cf-Access-Jwt-Assertion` header it receives from Access as a `Cf-Access-Token` header to the downstream application.
# Add bookmarks
import { Render } from "~/components";
` from the command line to authenticate through your Access policies without the Cloudflare One Client installed. This is useful for SSH sessions, API calls, and other command-line workflows where a browser-based login flow is impractical.
For more information, refer to [cloudflared authentication](/cloudflare-one/access-controls/applications/non-http/cloudflared-authentication/).
## SaaS applications
SaaS applications are for third-party tools that your organization uses but does not host — services like Salesforce, Atlassian, Slack, or Workday. With a SaaS application, you configure Cloudflare Access as the single sign-on (SSO) provider for the third-party service using SAML or OIDC, the two most common identity federation protocols.
When users sign in to the SaaS application, they are redirected to Cloudflare. Cloudflare redirects to your configured identity provider for authentication, then evaluates your Access policies against the authenticated user. If the user passes both checks, Cloudflare issues a signed credential (a SAML assertion or OIDC token) back to the SaaS application confirming the user's identity.
### When to use SaaS applications
Use a SaaS application when you want to:
- **Enforce consistent Access policies across third-party tools.** Apply the same identity, device posture, and location requirements that you use for your internal applications to external SaaS tools.
- **Aggregate multiple identity providers.** Cloudflare can federate authentication across multiple identity providers (IdPs), which means you can swap or add identity providers without reconfiguring each SaaS application individually. This is not typically possible with direct SSO integrations.
- **Apply Cloudflare-specific controls.** Enforce requirements that your SaaS provider cannot check on its own — for example, requiring the Cloudflare One Client or passing a device posture check before granting access to the SaaS tool.
### Limitations
SaaS applications require that the third-party tool supports SAML or OIDC federation. Not all SaaS tools offer this, and some impose restrictions on the number of SSO integrations or the features available through federated authentication. Check your SaaS vendor's documentation for SSO compatibility.
For setup instructions, refer to [SaaS applications](/cloudflare-one/access-controls/applications/http-apps/saas-apps/).
## Infrastructure applications
Infrastructure applications provide protocol-aware access control for servers and infrastructure targets, whether reachable over a public hostname or a private network. Unlike self-hosted applications, which evaluate whether a user can reach a destination, infrastructure applications also control what a user can do after connecting — which usernames they can authenticate as, which ports they can access, and which commands they can run.
Infrastructure applications require the Cloudflare One Client. For targets on your private network, you must also connect the network to Cloudflare through [Cloudflare Tunnel](/cloudflare-one/networks/connectors/cloudflare-tunnel/) or [Cloudflare Mesh](/mesh/).
### When to use infrastructure applications
Use an infrastructure application when you need:
- **Protocol-level authorization.** Define policies that grant specific users access to specific ports and usernames on a target server.
- **Command logging.** All SSH sessions and commands are logged for compliance and auditing. You can export logs to a storage service or SIEM using [Logpush](/cloudflare-one/insights/logs/logpush/).
- **Short-lived certificates.** Eliminate long-lived SSH keys by authenticating users with certificates that expire quickly. This removes the risk of a stolen or forgotten key granting permanent access to your servers.
Infrastructure applications support SSH. You can still use [self-hosted applications](#self-hosted-applications) to secure access to servers over other protocols (including SSH), but infrastructure applications are the only way to supplementally control user authorization.
For setup instructions, refer to [Add an infrastructure application](/cloudflare-one/access-controls/applications/non-http/infrastructure-apps/).
## Bookmarks
Bookmarks are not secured by Access. A bookmark is a link to any URL that you want to display in the [App Launcher](/cloudflare-one/access-controls/access-settings/app-launcher/) alongside your other applications. You can assign Access policies to bookmarks, but those policies only control whether the bookmark tile is visible in the App Launcher — they do not protect the destination URL.
Use bookmarks to give users a single portal where they can find all of the tools they use, including external applications that are not integrated with Cloudflare.
For setup instructions, refer to [Add bookmarks](/cloudflare-one/access-controls/applications/bookmarks/).
## Private network applications (legacy)
:::note
Not recommended for new deployments. Use a [self-hosted application](#private-applications) to secure private network destinations instead.
:::
The legacy private network application type creates Gateway Network policies to control access to a private IP address. When you add a legacy private network application, Cloudflare generates two Gateway rules — one Allow rule and one Block rule — because Gateway Network policies are not default-deny (unlike Access policies, which require an explicit Allow rule before any user can reach a protected application).
Legacy private network applications do not support per-session management, application tokens, or the full set of features available in Access policies. This application type is deprecated for new customers and remains available to existing customers.
If you are currently using legacy private network applications, we strongly recommend migrating to [self-hosted private network applications](#private-applications) for more comprehensive policy controls and session management.
For more information, refer to [Private network applications (legacy)](/cloudflare-one/access-controls/applications/non-http/legacy-private-network-app/).
# Applications
import { DirectoryListing } from "~/components";
Cloudflare Access protects applications through several application types. Not sure which to use? Refer to [Choose an application type](/cloudflare-one/access-controls/applications/choose-application-type/).
(self-hosted)"]
appA -- "Cf-Access-Token: <JWT>" --> appB["Application B
(self-hosted)"]
idp[Identity provider] <--> appA
```
### Prerequisites
- Two [self-hosted Access applications](/cloudflare-one/access-controls/applications/http-apps/self-hosted-public-app/)
### 1. Create a Linked App Token policy
Create a policy on Application B (the downstream application that will receive forwarded requests):
```
When Access receives the request to Application B, it will:
1. Extract the token from the `Cf-Access-Token` header.
2. Validate that the token was issued for Application A (matching the `app_uid` in the Linked App Token rule).
3. If valid, Access issues a new `Cf-Access-Jwt-Assertion` scoped to Application B's AUD tag, forwards it to Application B's origin, and attributes the request to the original user in the audit log.
## SaaS to self-hosted
In this example an [Access for SaaS application](/cloudflare-one/access-controls/applications/http-apps/saas-apps/) (for example, an MCP server that implements [OAuth](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization)) needs to make requests to a self-hosted Access application. The SaaS app obtains an OAuth access token from Cloudflare Access and sends it to the self-hosted application in the `Authorization: Bearer` header.
```mermaid
flowchart LR
accTitle: SaaS to self-hosted linked app token flow
User --> appA["Application A
(Access for SaaS)"]
appA -- "Authorization: Bearer <token>" --> appB["Application B
(self-hosted)"]
idp[Identity provider] <--> appA
```
### Prerequisites
- A [self-hosted Access application](/cloudflare-one/access-controls/applications/http-apps/self-hosted-public-app/)
- An [Access for SaaS OIDC application](/cloudflare-one/access-controls/applications/http-apps/saas-apps/)
### 1. Create a Linked App Token policy
Create a policy on the self-hosted application (Application B):
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **Applications**.
2. Find the application you want to configure, then select the three dots on the right > **Edit**.
3. Go to the **Advanced settings** tab and turn on **Managed OAuth**.
4. (Optional) Configure [Managed OAuth settings](#managed-oauth-settings).
5. Select **Save**.
1. Get your existing Access application configuration:
To test, open an RFC 8707-compliant OAuth client and make a request to your application. The client should open a browser window prompting you to log in to Access. Refer to the [Authorization flow](#authorization-flow) section for more details.
## Enable managed OAuth on an MCP server application
Managed OAuth is available on [MCP server applications](/cloudflare-one/access-controls/ai-controls/secure-mcp-servers/) and allows MCP clients to authenticate users through Access using a standard OAuth 2.0 flow. Use this flow for MCP servers served through Cloudflare in the same account as your Zero Trust organization. The MCP server must validate the Access JWT sent in the `Cf-Access-Jwt-Assertion` header.
Do not enable Managed OAuth for third-party MCP server code that already handles its own OAuth flow and cannot validate Access JWTs.
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **Applications**.
2. Find the MCP server application you want to configure, then select the three dots on the right > **Edit**.
3. Go to the **Advanced settings** tab and turn on **Managed OAuth**.
4. (Optional) Configure [Managed OAuth settings](#managed-oauth-settings).
5. Select **Save**.
1. Get your existing Access application configuration:
To test, open an MCP client and connect to the protected MCP server. The client should open a browser window prompting you to log in to Access. Refer to the [Authorization flow](#authorization-flow) section for more details.
## Enable managed OAuth on an MCP server portal
Managed OAuth is available on [MCP server portals](/cloudflare-one/access-controls/ai-controls/mcp-portals/) and is the mechanism that allows MCP clients to authenticate users through the portal without a browser cookie flow.
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **AI controls**.
2. Find the portal you want to configure, then select the three dots on the right > **Edit**.
3. Go to the **Advanced settings** tab, turn on **Managed OAuth**.
4. (Optional) Configure [Managed OAuth settings](#managed-oauth-settings).
5. Select **Save**.
1. Get your existing configuration for the portal's underlying Access application:
To test, open an MCP client and [connect to the MCP portal](/cloudflare-one/access-controls/ai-controls/mcp-portals/#connect-to-a-portal). The client should open a browser window prompting you to log in to Access. Refer to the [Authorization flow](#authorization-flow) section for more details.
## Managed OAuth settings
Configure these settings in the **Advanced settings** tab of your [self-hosted app](#enable-managed-oauth-on-a-self-hosted-application), [MCP server application](#enable-managed-oauth-on-an-mcp-server-application), or [MCP server portal](#enable-managed-oauth-on-an-mcp-server-portal).
- **Allow localhost clients**: Allow any client with redirect URIs on `localhost`.
- **Allow loopback clients**: Allow any client with redirect URIs on `127.0.0.1`.
- **Allowed redirect URIs**: Redirect URIs allowed for dynamically registered clients (for example, `https://playground.ai.cloudflare.com/*`). The URL must use `https`. Paths may end in `/*` to match all sub-paths.
- **Grant session duration**: How long the OAuth refresh token remains valid.
- **Access token lifetime**: How long an OIDC Access token can be used to authenticate with your application. Cloudflare recommends configuring a short **Access token lifetime** (default 15 minutes) in conjunction with a longer **Grant session duration**. When the access token expires, Cloudflare uses the refresh token to issue a new one after re-evaluating the user against your Access policies. When the refresh token expires, the user must re-authenticate with the identity provider.
:::note[Recommended configuration for CLI and agent use cases]
For CLI tools, AI agents, and other non-browser clients, set a short access token lifetime (5–15 minutes) with a longer grant session duration (1–2 weeks). With this configuration:
- The client refreshes tokens silently in the background using the refresh token — no user interaction required.
- Access policies are re-evaluated on each token refresh, maintaining continuous identity verification.
- The user only sees the authorization prompt when the grant session (refresh token) expires.
For example, with a 15-minute access token and a 2-week grant session, a user authenticates once via the browser and then works uninterrupted for up to two weeks before needing to re-authenticate.
:::
Configure these settings via the `oauth_configuration` object on the [Access applications](/api/resources/zero_trust/subresources/access/subresources/applications/methods/update/) endpoint.
| Dashboard setting | API field |
| --- | --- |
| Allow localhost clients | `dynamic_client_registration.allow_any_on_localhost` |
| Allow loopback clients | `dynamic_client_registration.allow_any_on_loopback` |
| Allowed redirect URIs | `dynamic_client_registration.allowed_uris` |
| Grant session duration | `grant.session_duration` |
| Access token lifetime | `grant.access_token_lifetime` |
1. Get your existing Access application configuration:
## Authorization flow
When managed OAuth is enabled, Access returns a `401` response instead of a `302` redirect to non-browser clients. The `401` includes a `WWW-Authenticate` header that points the client to Access's OAuth discovery metadata.
The authorization flow proceeds as follows:
1. The client fetches the OAuth authorization server metadata from the `/.well-known/` endpoint:
```txt
https:///.well-known/oauth-authorization-server
```
This endpoint conforms to [RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414) and [RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728) and returns the authorization and token endpoint URLs for the application.
2. The client initiates an authorization code flow. It opens the user's browser to the Access authorization endpoint, where the user logs in to their IdP as usual.
3. Access issues an OAuth access token to the client. The client uses this token in subsequent requests to the protected application.
### Token format
Managed OAuth issues **opaque** access tokens (for example, `oauth:CvNoo...`), not JSON Web Tokens (JWTs). This is by design — the OAuth flow gives clients the ability to make requests on a user's behalf without exposing identity information to the client.
When a client presents an opaque token to your application, Cloudflare resolves the token into the user's identity on the backend and forwards a signed assertion to your origin. From your origin's perspective, the request looks the same as a browser-authenticated request.
Because the token is opaque, the client cannot decode it or forward it directly as a JWT to other applications. To make authenticated requests to downstream Access applications, use the [Linked App Token](/cloudflare-one/access-controls/applications/linked-app-token/) pattern — your origin reads the `Cf-Access-Jwt-Assertion` header and forwards it to downstream apps as `Cf-Access-Token`.
### Multi-domain applications
If your Access application is configured with [multiple domains](/cloudflare-one/access-controls/applications/http-apps/authorization-cookie/#multi-domain-applications), an OAuth token obtained through any one domain is valid for all domains in the same application. The user authenticates once and can use the same token to access all domains without additional prompts.
This is useful when you have multiple internal services that share a common trust boundary. Instead of configuring separate Access applications with [Linked App Token](/cloudflare-one/access-controls/applications/linked-app-token/) policies, you can add all domains to a single application and authenticate once via Managed OAuth.
:::note
Consolidating domains into a single Access application means all domains share the same Access policies. If you need per-domain policy separation, use separate applications with the [Linked App Token](/cloudflare-one/access-controls/applications/linked-app-token/) pattern instead.
:::
## Managed OAuth vs service tokens
Both managed OAuth and [service tokens](/cloudflare-one/access-controls/service-credentials/service-tokens/) allow non-browser clients to authenticate with Access-protected applications, but they serve different use cases:
| | Managed OAuth | Service tokens |
| --- | --- | --- |
| **Authentication model** | User-based — the end user logs in through their identity provider | Machine-based — a shared secret authenticates the service itself |
| **Best for** | Interactive CLI tools, AI agents, SDKs where a human initiates the request | Fully automated systems, cron jobs, CI/CD pipelines, server-to-server communication |
| **User identity** | Access knows which user made the request | No user identity — requests are attributed to the service token |
| **Policy enforcement** | Can use identity-based policies (for example, require specific groups or emails) | Requires a [Service Auth](/cloudflare-one/access-controls/policies/#service-auth) policy action |
| **Credential management** | No shared secrets to distribute — users authenticate with their own credentials | Requires distributing and rotating Client ID and Client Secret |
Use managed OAuth when you want non-browser clients to authenticate users the same way a browser would — the user logs in once, and the client receives an OAuth token to make requests on their behalf.
Use service tokens when no human is involved and you need a machine identity to access your application programmatically.
# Publish a self-hosted application to the Internet
import { Render, Stream } from "~/components";
You can securely publish internal tools and applications by adding Cloudflare Access as an authentication layer between the end user and your origin server.
This page describes how to make a web application accessible to anyone on the Internet via a public hostname. To make the application available over a private IP or hostname, refer to [Add a self-hosted private application](/cloudflare-one/access-controls/applications/non-http/self-hosted-private-app/).
## Prerequisites
- An [active domain on Cloudflare](/fundamentals/manage-domains/add-site/)
- Domain uses either a [full setup](/dns/zone-setups/full-setup/) or a [partial (`CNAME`) setup](/dns/zone-setups/partial-setup/)
:::note
If your domain uses a [partial (`CNAME`) setup](/dns/zone-setups/partial-setup/), refer to [Partial (CNAME) setup](#partial-cname-setup) for additional DNS configuration steps.
:::
## 1. Add your application to Access
.cdn.cloudflare.net` (for example, `app.example.com.cdn.cloudflare.net`)
:::note
The zone apex (for example, `example.com`) cannot use a CNAME record due to [DNS specification restrictions](https://datatracker.ietf.org/doc/html/rfc1912#section-2.4). Some DNS providers work around this with [CNAME flattening](/dns/zone-setups/partial-setup/#cname-flattening), which resolves the CNAME at the provider level. If your provider does not support CNAME flattening, use a subdomain instead.
:::
## Product compatibility
.cloudflareaccess.com/cdn-cgi/access/get-identity`. Your request should be structured as follows:
```sh
curl -H 'cookie: CF_Authorization=' https://.cloudflareaccess.com/cdn-cgi/access/get-identity
```
Access will return a JSON structure containing the following data:
| Field | Description |
| -------------------- | --------------------------------------------------------------------------- |
| email | The email address of the user. |
| idp | Data from your identity provider. |
| geo | The country where the user authenticated from. |
| user_uuid | The ID of the user. |
| devicePosture | The device posture attributes. |
| account_id | The account ID for your organization. |
| iat | The timestamp indicating when the user logged in. |
| ip | The IP address of the user. |
| auth_status | The status if authenticating with mTLS. |
| common_name | The common name on the mTLS client certificate. |
| service_token_id | The Client ID of the service token used for authentication. |
| service_token_status | True if authentication was through a service token instead of an IdP. |
| is_warp | True if the user enabled WARP. |
| is_gateway | True if the user enabled the Cloudflare One Client and authenticated to a Zero Trust team. |
| gateway_account_id | An ID generated by the Cloudflare One Client when authenticated to a Zero Trust team. |
| device_id | The ID of the device used for authentication. |
| version | The version of the `get-identity` object. |
| device_sessions | A list of all sessions initiated by the user. |
### Service token authentication
```json
{
"type": "app",
"aud": ["32eafc7626e974616deaf0dc3ce63d7bcbed58a2731e84d06bc3cdf1b53c4228"],
"exp": 1659474457,
"iss": "https://yourteam.cloudflareaccess.com",
"common_name": "e367826f93b8d71185e03fe518aff3b4.access",
"iat": 1659474397,
"sub": ""
}
```
| Field | Description |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| type | The type of Access token (`app` for application token or `org` for global session token). |
| aud | The [application audience (AUD) tag](/cloudflare-one/access-controls/applications/http-apps/authorization-cookie/validating-json/#get-your-aud-tag) of the Access application. |
| exp | The expiration timestamp of the JWT (Unix time). |
| iss | The Cloudflare Access domain URL for the application. |
| common_name | The Client ID of the service token (`CF-Access-Client-Id`). |
| iat | The issuance timestamp of the JWT (Unix time). |
| sub | Contains an empty string when authentication was through a service token. |
## Signature
Cloudflare generates the signature by signing the encoded header and payload using the SHA-256 algorithm (RS256). In RS256, a private key signs the JWTs and a separate [public key](/cloudflare-one/access-controls/applications/http-apps/authorization-cookie/validating-json/#access-signing-keys) verifies the signature.
For more information on JWTs, refer to [jwt.io](https://jwt.io/).
# CORS
import { Render, PackageManagers, DashButton } from "~/components";
Cross-Origin Resource Sharing ([CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS)) is a mechanism that uses HTTP headers to grant a web application running on one origin permission to reach selected resources in a different origin. The web application executes a cross-origin HTTP request when it requests a resource that has a different origin from its own, including domain, protocol, or port.
For a CORS request to reach a site protected by Access, the request must include a valid `CF-Authorization` cookie. This may require additional configuration depending on the type of request:
- [Simple requests](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#simple_requests) are sent directly to the origin, without triggering a preflight request. For configuration instructions, refer to [Allow simple requests](#allow-simple-requests).
- [Preflighted requests](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#preflighted_requests) cause the browser to send an OPTIONS request before sending the actual request. The OPTIONS request checks which methods and headers are allowed by the origin. For configuration instructions, refer to [Allow preflighted requests](#allow-preflighted-requests).
:::caution[Important]
- Do not troubleshoot CORS in Incognito mode, as this will cause disruptions with Access due to `CF-Authorization` being blocked as a third-party cookie on cross origin requests.
- Safari, in particular Safari 13.1, handles cookies in a unique format. In some cases, this can cause CORS to fail. This will be dependent on Apple releasing a patch for handling cookies. This is known to impact macOS 10.15.4 when running Safari 13.1 (15609.1.20.111.8).
:::
## Allow simple requests
If you make a simple CORS request to an Access-protected domain and have not yet logged in, the request will return a `CORS error`. There are two ways you can resolve this error:
- **Option 1** — [Log in and refresh the page](#authenticate-manually).
- **Option 2** — [Create a Cloudflare Worker which automatically sends an authentication token](#send-authentication-token-with-cloudflare-worker). This method only works if both sites involved in the CORS exchange are behind Access.
### Authenticate manually
1. Visit the target domain in your browser. You will see the Access login page.
2. Log in to the target domain. This generates a `CF-Authorization` cookie.
3. Refresh the page that made the CORS request. The refresh resends the request with the newly generated cookie.
## Allow preflighted requests
If you make a preflighted cross-origin request to an Access-protected domain, the OPTIONS request will return a `403` error. This error occurs regardless of whether you have logged in to the domain. This is because the browser never includes cookies with OPTIONS requests, by design. Cloudflare will therefore block the preflight request, causing the CORS exchange to fail.
There are three ways you can resolve this error:
- **Option 1** — [Bypass OPTIONS requests to origin](#bypass-options-requests-to-origin).
- **Option 2** — [Configure Cloudflare to respond to the OPTIONS request](#configure-response-to-preflight-requests).
- **Option 3** — [Create a Cloudflare Worker which automatically sends an authentication token](#send-authentication-token-with-cloudflare-worker). This method only works if both sites involved in the CORS exchange are behind Access.
### Bypass OPTIONS requests to origin
You can configure Cloudflare to send OPTIONS requests directly to your origin server. To bypass Access for OPTIONS requests:
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **Applications**.
2. Locate the origin that will be receiving OPTIONS requests and select **Configure**.
3. Go to **Advanced settings** > **Cross-Origin Resource Sharing (CORS) settings**.
4. Turn on **Bypass options requests to origin**. This will remove all existing CORS settings for this application.
It is still important to enforce CORS for the Access JWT -- this option should only be used if you have CORS enforcement established in your origin server.
### Configure response to preflight requests
You can configure Cloudflare to respond to the OPTIONS request on your behalf. The OPTIONS request never reaches your origin. After the preflight exchange resolves, the browser will then send the main request which does include the authentication cookie (assuming you have logged into the Access-protected domain).
To configure how Cloudflare responds to preflight requests:
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **Applications**.
2. Locate the origin that will be receiving OPTIONS requests and select **Configure**.
3. Go to **Advanced settings** > **Cross-Origin Resource Sharing (CORS) settings**.
4. Configure these [CORS settings](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#the_http_response_headers) to match the response headers sent by your origin.
For example, if you have configured `api.mysite.com`to return the following headers:
```txt
headers: {
'Access-Control-Allow-Origin': 'https://example.com',
'Access-Control-Allow-Credentials' : true,
'Access-Control-Allow-Methods': 'GET, OPTIONS',
'Access-Control-Allow-Headers': 'office',
'Content-Type': 'application/json',
}
```
then go to `api.mysite.com` in Access and configure **Access-Control-Allow-Origin**, **Access-Control-Allow-Credentials**, **Access-Control-Allow-Methods**, and **Access-Control-Allow-Headers**.
5. Select **Save**.
6. (Optional) You can check your configuration by sending an OPTIONS request to the origin with `curl`. For example,
```bash
curl --head --request OPTIONS https://api.mysite.com \
--header 'origin: https://example.com' \
--header 'access-control-request-method: GET'
```
should return a response similar to:
```txt
HTTP/2 200
date: Tue, 24 May 2022 21:51:21 GMT
vary: Origin, Access-Control-Request-Method, Access-Control-Request-Headers
access-control-allow-origin: https://example.com
access-control-allow-methods: GET
access-control-allow-credentials: true
expect-ct: max-age=604800, report-uri="https://report-uri.cloudflare.com/cdn-cgi/beacon/expect-ct"
report-to: {"endpoints":[{"url":"https:\/\/a.nel.cloudflare.com\/report\/v3?s=A%2FbOOWJio%2B%2FjuJv5NC%2FE3%2Bo1zBl2UdjzJssw8gJLC4lE1lzIUPQKqJoLRTaVtFd21JK1d4g%2BnlEGNpx0mGtsR6jerNfr2H5mlQdO6u2RdOaJ6n%2F%2BS%2BF9%2Fa12UromVLcHsSA5Y%2Fj72tM%3D"}],"group":"cf-nel","max_age":604800}
nel: {"success_fraction":0.01,"report_to":"cf-nel","max_age":604800}
server: cloudflare
cf-ray: 7109408e6b84efe4-EWR
```
## Send authentication token with Cloudflare Worker
If you have two sites protected by Cloudflare Access, `example.com` and `api.mysite.com`, requests made between the two will be subject to CORS checks. Users who log in to `example.com` will be issued a cookie for `example.com`. When the user's browser requests `api.mysite.com`, Cloudflare Access looks for a cookie specific to `api.mysite.com`. The request will fail if the user has not already logged in to `api.mysite.com`.
To avoid having to log in twice, you can create a Cloudflare Worker that automatically sends authentication credentials to `api.mysite.com`.
### Prerequisites
- [Workers account](/workers/get-started/guide/)
- `wrangler` installation
- `example.com` and `api.mysite.com` domains [protected by Access](/cloudflare-one/access-controls/applications/http-apps/)
### 1. Generate a service token
Follow [these instructions](/cloudflare-one/access-controls/service-credentials/service-tokens/) to generate a new Access service token. Copy the `Client ID` and `Client Secret` to a safe place, as you will use them in a later step.
### 2. Add a Service Auth policy
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **Applications**.
2. Find your `api.mysite.com` application and select **Configure**.
3. Select the **Policies** tab.
4. Add the following policy:
| Action | Rule type | Selector |
| ------------ | --------- | ------------- |
| Service Auth | Include | Service Token |
### 3. Create a new Worker
Open a terminal and run the following command:
`
- `CF_ACCESS_CLIENT_SECRET` = ``
The Client ID and Client Secret are copied from your [service token](#1-generate-a-service-token).
6. Enable the **Encrypt** option for each variable and select **Save**.
### 5. Update HTTP request URLs
Modify your `example.com` application to send all requests to `example.com/api/` instead of `api.mysite.com`.
HTTP requests should now work seamlessly between two different Access-protected domains. When a user logs in to `example.com`, the browser makes a request to the Worker instead of to `api.mysite.com`. The Worker adds the Access service token to the request headers and then forwards the request to `api.mysite.com`. Since the service token matches a Service Auth policy, the user no longer needs to log in to `api.mysite.com`.
## Troubleshooting
In general, we recommend the following steps when troubleshooting CORS issues:
1. Capture a HAR file with the issue described, as well as the JS console log output recorded simultaneously. This is because the HAR file alone will not give full visibility on the reason behind cross-origin issues.
2. Ensure that the application has set `credentials: 'same-origin'` in all fetch or XHR requests.
3. If you are using the [cross-origin setting](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin) on script tags, these must be set to "use-credentials".
:::caution[CORS is failing on the same domain]
CORS checks do not occur on the same domain. If this error occurs, it is likely the request is being sent without the `CF-Authorization` cookie.
:::
# Authorization cookie
import { Details, GlossaryTooltip, Render } from "~/components";
When you protect a site with Cloudflare Access, Cloudflare checks every HTTP request bound for that site to ensure that the request has a valid `CF_Authorization` cookie. If a request does not include the cookie, Access will block the request.
## Access JWTs
The `CF_Authorization` cookie contains the user's identity in the form of a [JSON Web Token (JWT)](https://www.cloudflare.com/learning/access-management/token-based-authentication/). Cloudflare securely creates these tokens through the OAUTH or SAML integration between Cloudflare Access and the configured identity provider.
Access generates two separate `CF_Authorization` tokens depending on the domain:
- **Global session token**: Generated when a user logs in to Access. This token is stored as a cookie at your team domain (for example, `https://.cloudflareaccess.com`) and prevents a user from needing to log in to each application.
- [**Application token**](/cloudflare-one/access-controls/applications/http-apps/authorization-cookie/application-token/): Generated for each application that a user reaches. This token is stored as a cookie on the protected domain (for example, `https://jira.site.com`) and may be used to [validate requests](/cloudflare-one/access-controls/applications/http-apps/authorization-cookie/validating-json) on your origin.
### Multi-domain applications
Cloudflare Access allows you to protect and manage multiple domains in a single [self-hosted application](/cloudflare-one/access-controls/applications/http-apps/self-hosted-public-app/). After a user has successfully authenticated to one domain, Access will automatically issue a `CF_Authorization` cookie when they go to another domain in the same Access application. This means that users only need to authenticate once to a multi-domain application.
Access can preemptively set the cookie for every domain through a series of redirects when the user first authenticates. This allows single-page applications (SPAs) to retrieve data from other subdomains before the user visits each subdomain. Wildcarded subdomains (for example, `*.example.com`) cannot receive preemptive cookies because Access does not know which concrete subdomain to redirect to. Wildcarded paths are supported.
Use the [Eager redirect cookie](#eager-redirect-cookie) setting to control this behavior.
:::note
Access previously chose the cookie behavior based on the number of domains. It preemptively set cookies for applications with five or fewer domains and issued cookies as users visited each domain for applications with more than five domains. Applications without a saved setting retain this behavior. Administrators can override it by turning the Eager redirect cookie setting on or off.
:::
## Access cookies
The following Access cookies are essential to Access functionality. Cookies that are marked as required cannot be opted out of. The following cookies are not used for tracking or analytics.
### CF_Authorization (team domain)
| Details | Expiration | HttpOnly | SameSite | Required? |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------- | --------- |
| [JSON web token (JWT)](/cloudflare-one/access-controls/applications/http-apps/authorization-cookie/#access-jwts) set on the `cloudflareaccess.com` [team domain](/cloudflare-one/faq/getting-started-faq/#what-is-a-team-domainteam-name) that contains the user's identity and enables Access to perform single sign-on (SSO) | View
If set, adheres to [global session duration](/cloudflare-one/access-controls/access-settings/session-management/#global-session-duration).
If not, adheres to [application session duration](/cloudflare-one/access-controls/access-settings/session-management/#application-session-duration).
If neither are set, defaults to 24 hours. | Yes | None | Required |
### CF_Authorization (Access application domain)
| Details | Expiration | HttpOnly | SameSite | Required? |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | ---------------------------- | --------- |
| [JSON web token (JWT)](/cloudflare-one/access-controls/applications/http-apps/authorization-cookie/#access-jwts) set on the domain protected by Access that allows Access to confirm that the user has been authenticated and is authorized to reach the origin | View
If set, adheres to [policy session duration](/cloudflare-one/access-controls/access-settings/session-management/#policy-session-duration).
If not, adheres to [application session duration](/cloudflare-one/access-controls/access-settings/session-management/#application-session-duration).
If neither are set, defaults to 24 hours. | Admin choice (Default: None) | Admin choice (Default: None) | Required |
### CF_Binding
| Details | Expiration | HttpOnly | SameSite | Required? |
| ---------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------- | --------- |
| Refer to [Binding cookie](/cloudflare-one/access-controls/applications/http-apps/authorization-cookie/#binding-cookie) | View
If set, adheres to [policy session duration](/cloudflare-one/access-controls/access-settings/session-management/#policy-session-duration).
If not, adheres to [application session duration](/cloudflare-one/access-controls/access-settings/session-management/#application-session-duration).
If neither are set, defaults to 24 hours. | Yes | None | Optional |
### CF_Session
| Details | Expiration | HttpOnly | SameSite | Required? |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- | -------- | -------- | --------- |
| [CSRF](https://www.cloudflare.com/learning/security/threats/cross-site-request-forgery/) token used on the `cloudflareaccess.com` [team domain](/cloudflare-one/faq/getting-started-faq/#what-is-a-team-domainteam-name) | 4 hours | Yes | None | Required |
### CF_AppSession
| Details | Expiration | HttpOnly | SameSite | Required? |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | -------- | -------- | --------- |
| [CSRF](https://www.cloudflare.com/learning/security/threats/cross-site-request-forgery/) token used per application domain, scoped to individual applications behind Access | 24 hours | Yes | None | Required |
### CF_Device
| Details | Expiration | HttpOnly | SameSite | Required? |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | -------- | -------- | --------- |
| Cookie set on the `cloudflareaccess.com` [team domain](/cloudflare-one/faq/getting-started-faq/#what-is-a-team-domainteam-name), used to prevent abuse of [one-time PIN](/cloudflare-one/integrations/identity-providers/one-time-pin/) and [multi-factor authentication](/cloudflare-one/access-controls/access-settings/independent-mfa/) flows | 30 days | Yes | Strict | Required |
## Cookie settings
Cloudflare Access provides optional security settings that can be added to the browser cookies generated by Access for an authenticated user.
- [SameSite](#samesite-attribute)
- [HttpOnly flag](#httponly)
- [Binding cookie](#binding-cookie)
- [Cookie path](#cookie-path-attribute)
- [Eager redirect cookie](#eager-redirect-cookie)
To enable these settings:
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **Applications**.
2. Locate the application you would like to configure and select **Configure**.
3. Select **Advanced settings** and scroll down to **Cookie settings**.
4. Configure the desired cookie settings.
5. Select **Save**.
### SameSite Attribute
The [`SameSite`](https://web.dev/samesite-cookies-explained/) Attribute selector restricts the cookie to only being sent if the cookie's defined site matches the site being requested in the browser. This adds protection against [cross-site request forgery (CSRF)](https://en.wikipedia.org/wiki/Cross-site_request_forgery).
The selector options are:
- **None** - Cookies will be sent in all contexts, including cross-origin requests.
- **Lax** - Cookies are allowed to be sent with top-level navigations and will be sent along with GET requests initiated by third party websites.
- **Strict** - Cookies will only be sent in a first-party context and not be sent along with requests initiated by third party websites.
Refer to the [Mozilla documentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie#samesitesamesite-value) for more information.
:::caution
If you are receiving the `ERR_TOO_MANY_REDIRECTS` errors, make sure your `SameSite` setting is set to None or Lax. Setting the `SameSite` setting to Strict can result in too many redirects.
:::
#### When not to use SameSite
Do not enable `SameSite` restrictions if you have additional sites or applications that rely on a specific application's authorization cookie.
### HttpOnly
The `HttpOnly` flag is a cookie attribute that prevents the cookie from being accessed by any client-side scripts, reducing the likelihood of Cross-Site Scripting (XSS) attacks. This flag is enabled by default.
#### When not to use HttpOnly
Do not enable `HttpOnly` if:
- You are using the Access application for non-browser based tools (such as SSH or RDP).
- You have software that relies on being able to access a user's cookie generated by Access.
### Binding cookie
The binding cookie (`CF_Binding`) is an optional cookie issued when a user successfully authenticates. The binding cookie is sent by the user's browser and tied to a specific application's `CF_Authorization` cookie. This cookie is stripped at Cloudflare's network and never forwarded to the origin server.
The `CF_Authorization` cookie cannot be used without the associated binding cookie, which prevents a stolen `CF_Authorization` cookie from being reused by an attacker. If a request arrives at Cloudflare's network with a valid `CF_Authorization` cookie but without the expected binding cookie, Cloudflare rejects the request.
#### When not to use Binding Cookie
Do not enable Binding Cookie if:
- You are using the Access application for non-browser based tools (such as SSH or RDP).
- You have enabled [incompatible Cloudflare products](/cloudflare-one/access-controls/applications/http-apps/self-hosted-public-app/#product-compatibility) on the application domain, such as [Zaraz](/zaraz) or [Google tag gateway](/google-tag-gateway/). Enabling Binding Cookie alongside these products can cause an authentication redirect loop (`ERR_TOO_MANY_REDIRECTS`).
- You have turned on [Authenticate with Cloudflare One Client](/cloudflare-one/team-and-resources/devices/cloudflare-one-client/configure/client-sessions/) for the application.
### Cookie Path Attribute
The Cookie Path Attribute adds the application's path URL to the `CF_Authorization` cookie. When enabled, a user who logs in to `example.com/path1` must re-authenticate to access `example.com/path2`. When disabled, the `CF_Authorization` cookie is only scoped to the domain and subdomain.
### Eager redirect cookie
When turned on, the Eager redirect cookie setting preemptively sets a `CF_Authorization` cookie for every concrete domain in a multi-domain application. Access redirects the browser through each domain after the user first authenticates. This setting is turned on by default for new applications.
:::caution
Browser behavior can become unreliable when the redirect chain exceeds 10 redirects. If your application has more than 10 domains, turn off this setting or thoroughly test the authentication flow before you deploy it. When turned off, Access sets the cookie as a user visits each domain.
:::
## Allow third-party cookies in the browser
By default, some browsers block all third-party cookies in private browsing mode, including the `CF_Authorization` cookie. For XHR requests to work in private windows, you will need to exempt your application and team domain from the browser's tracking protection system.
To enable third-party cookies for an Access application:
1. Go to **Settings** > **Privacy and security** > **Cookies and other site data**.
2. Under **Sites that can always use cookies**, add the following URLs:
- Hostname of your Access application (for example, `https://jira.site.com`)
- `https://.cloudflareaccess.com`
1. Go to **Safari** > **Settings** > **Privacy**.
2. Deselect **Block all cookies**.
1. Go to **Settings** > **Privacy & Security**.
2. Scroll down to **Cookies and Site Data**.
3. Select **Manage Exceptions**.
4. Enter the URL of your Access application (for example, `https://jira.site.com`) and select **Allow**.
5. Enter `https://.cloudflareaccess.com` and select **Allow**.
6. Select **Save Changes**.
1. Go to `brave://settings/cookies`.
2. Under **Sites that can always use cookies**, add the following URLs:
- Hostname of your Access application (for example, `https://jira.site.com`)
- `https://.cloudflareaccess.com`
# Validate JWTs
import { GlossaryTooltip, TypeScriptExample } from "~/components";
When Cloudflare sends a request to your origin, the request will include an [application token](/cloudflare-one/access-controls/applications/http-apps/authorization-cookie/application-token/) as a `Cf-Access-Jwt-Assertion` request header. Requests made through a browser will also pass the token as a `CF_Authorization` cookie.
Cloudflare signs the token with a key pair unique to your account. You should validate the token with your public key to ensure that the request came from Access and not a malicious third party. We recommend validating the `Cf-Access-Jwt-Assertion` header instead of the `CF_Authorization` cookie, since the cookie is not guaranteed to be passed.
## Access signing keys
The public key for the signing key pair is located at `https://.cloudflareaccess.com/cdn-cgi/access/certs`, where `` is your Cloudflare One team name .
By default, Access rotates the signing key every 6 weeks. This means you will need to programmatically or manually update your keys as they rotate. Previous keys remain valid for 7 days after rotation to allow time for you to make the update.
You can also manually rotate the key using the [API](/api/resources/zero_trust/subresources/access/subresources/keys/methods/rotate/). This can be done for testing or security purposes.
As shown in the example below, `https://.cloudflareaccess.com/cdn-cgi/access/certs` contains two public keys: the current key used to sign all new tokens, and the previous key that has been rotated out.
- `keys`: both keys in JWK format
- `public_cert`: current key in PEM format
- `public_certs`: both keys in PEM format
```txt
{
"keys": [
{
"kid": "1a1c3986a44ce6390be42ec772b031df8f433fdc71716db821dc0c39af3bce49",
"kty": "RSA",
"alg": "RS256",
"use": "sig",
"e": "AQAB",
"n": "5PKw-...-AG7MyQ"
},
{
"kid": "6c3bffef71bb0a90c9cbef3b7c0d4a1c7b4b8b76b80292a623afd9dac45d1c65",
"kty": "RSA",
"alg": "RS256",
"use": "sig",
"e": "AQAB",
"n": "pwVn...AA6Hw"
}
],
"public_cert": {
"kid": "6c3bffef71bb0a90c9cbef3b7c0d4a1c7b4b8b76b80292a623afd9dac45d1c65",
"cert": "-----BEGIN CERTIFICATE----- ... -----END CERTIFICATE----- "
},
"public_certs": [
{
"kid": "1a1c3986a44ce6390be42ec772b031df8f433fdc71716db821dc0c39af3bce49",
"cert": "-----BEGIN CERTIFICATE----- ... -----END CERTIFICATE----- "
},
{
"kid": "6c3bffef71bb0a90c9cbef3b7c0d4a1c7b4b8b76b80292a623afd9dac45d1c65",
"cert": "-----BEGIN CERTIFICATE----- ... -----END CERTIFICATE----- "
}
]
}
```
:::note[Avoid key rotation issues]
- Validate tokens using the external endpoint rather than saving the public key as a hard-coded value.
- Do not fetch the current key from `public_cert`, since your origin may inadvertently read an expired value from an outdated cache. Instead, match the `kid` value in the JWT to the corresponding certificate in `public_certs`.
:::
## Verify the JWT manually
To verify the token manually:
1. Copy the JWT from the `Cf-Access-Jwt-Assertion` request header.
2. Go to [jwt.io](https://jwt.io/).
3. Select the RS256 algorithm.
4. Paste the JWT into the **Encoded** box.
5. In the **Payload** box, ensure that the `iss` field points to your team domain (`https://.cloudflareaccess.com`). `jwt.io` uses the `iss` value to fetch the public key for token validation.
6. Ensure that the page says **Signature Verified**.
You can now trust that this request was sent by Access.
## Programmatic verification
You can run an automated script on your origin server to validate incoming requests. The provided sample code gets the application token from a request and checks its signature against your public key. You will need to insert your own team domain and Application Audience (AUD) tag into the sample code.
### Get your AUD tag
Cloudflare Access assigns a unique AUD tag to each application. The `aud` claim in the token payload specifies which application the JWT is valid for.
To get the AUD tag:
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **Applications**.
2. Select **Configure** for your application.
3. From **Additional settings**, copy the **Application Audience (AUD) Tag**.
You can now paste the AUD tag into your token validation script. The AUD tag will never change unless you delete or recreate the Access application.
### Cloudflare Workers example
When Cloudflare Access is in front of your [Worker](/workers/), use [`ctx.access`](/workers/configuration/cloudflare-access/#read-authenticated-user-identity-with-ctxaccess) to confirm that Access authenticated the request. You can also use it to read the signed-in user's identity. You do not need to parse or validate the JWT. Before using this option, review the [`ctx.access` limitations](/workers/configuration/cloudflare-access/#ctxaccess-limitations) for Static Assets and Service Bindings.
If you need to validate the JWT manually, read it from the `Cf-Access-Jwt-Assertion` header. The following code validates the token using the [jose npm package](https://www.npmjs.com/package/jose):
```ts
import { jwtVerify, createRemoteJWKSet } from "jose";
interface Env {
POLICY_AUD: string;
TEAM_DOMAIN: string;
}
export default {
async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise {
// Verify the POLICY_AUD environment variable is set
if (!env.POLICY_AUD) {
return new Response("Missing required audience", {
status: 403,
headers: { "Content-Type": "text/plain" },
});
}
// Get the JWT from the request headers
const token = request.headers.get("cf-access-jwt-assertion");
// Check if token exists
if (!token) {
return new Response("Missing required CF Access JWT", {
status: 403,
headers: { "Content-Type": "text/plain" },
});
}
try {
// Create JWKS from your team domain
const JWKS = createRemoteJWKSet(
new URL(`${env.TEAM_DOMAIN}/cdn-cgi/access/certs`)
);
// Verify the JWT
const { payload } = await jwtVerify(token, JWKS, {
issuer: env.TEAM_DOMAIN,
audience: env.POLICY_AUD,
});
// Token is valid, proceed with your application logic
return new Response(
`Hello ${payload.email || "authenticated user"}!`,
{
headers: { "Content-Type": "text/plain" },
}
);
} catch (error) {
// Token verification failed
const message = error instanceof Error ? error.message : "Unknown error";
return new Response(`Invalid token: ${message}`, {
status: 403,
headers: { "Content-Type": "text/plain" },
});
}
},
};
```
#### Required environment variables
Add these [environment variables](/workers/configuration/environment-variables/) to your Worker:
- `POLICY_AUD`: Your application's [AUD tag](#get-your-aud-tag)
- `TEAM_DOMAIN`: `https://.cloudflareaccess.com`, where `` is replaced with your actual team name .
You can set these variables by adding them to your Worker's [Wrangler configuration file](/workers/wrangler/configuration/), or via the Cloudflare dashboard under **Workers & Pages** > **your-worker** > **Settings** > **Environment Variables**.
### Golang example
```go
package main
import (
"context"
"fmt"
"net/http"
"github.com/coreos/go-oidc/v3/oidc"
)
var (
ctx = context.TODO()
teamDomain = "https://test.cloudflareaccess.com"
certsURL = fmt.Sprintf("%s/cdn-cgi/access/certs", teamDomain)
// The Application Audience (AUD) tag for your application
policyAUD = "4714c1358e65fe4b408ad6d432a5f878f08194bdb4752441fd56faefa9b2b6f2"
config = &oidc.Config{
ClientID: policyAUD,
}
keySet = oidc.NewRemoteKeySet(ctx, certsURL)
verifier = oidc.NewVerifier(teamDomain, keySet, config)
)
// VerifyToken is a middleware to verify a CF Access token
func VerifyToken(next http.Handler) http.Handler {
fn := func(w http.ResponseWriter, r *http.Request) {
headers := r.Header
// Make sure that the incoming request has our token header
// Could also look in the cookies for CF_AUTHORIZATION
accessJWT := headers.Get("Cf-Access-Jwt-Assertion")
if accessJWT == "" {
w.WriteHeader(http.StatusUnauthorized)
w.Write([]byte("No token on the request"))
return
}
// Verify the access token
ctx := r.Context()
_, err := verifier.Verify(ctx, accessJWT)
if err != nil {
w.WriteHeader(http.StatusUnauthorized)
w.Write([]byte(fmt.Sprintf("Invalid token: %s", err.Error())))
return
}
next.ServeHTTP(w, r)
}
return http.HandlerFunc(fn)
}
func MainHandler() http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
w.Write([]byte("welcome"))
})
}
func main() {
http.Handle("/", VerifyToken(MainHandler()))
http.ListenAndServe(":3000", nil)
}
```
### Python example
`pip` install the following:
- flask
- requests
- PyJWT
- cryptography
```python
from flask import Flask, request
import requests
import jwt
import json
import os
app = Flask(__name__)
# The Application Audience (AUD) tag for your application
POLICY_AUD = os.getenv("POLICY_AUD")
# Your CF Access team domain
TEAM_DOMAIN = os.getenv("TEAM_DOMAIN")
CERTS_URL = "{}/cdn-cgi/access/certs".format(TEAM_DOMAIN)
def _get_public_keys():
"""
Returns:
List of RSA public keys usable by PyJWT.
"""
r = requests.get(CERTS_URL)
public_keys = []
jwk_set = r.json()
for key_dict in jwk_set['keys']:
public_key = jwt.algorithms.RSAAlgorithm.from_jwk(json.dumps(key_dict))
public_keys.append(public_key)
return public_keys
def verify_token(f):
"""
Decorator that wraps a Flask API call to verify the CF Access JWT
"""
def wrapper():
# Check for the POLICY_AUD environment variable
if not POLICY_AUD:
return "missing required audience", 403
token = ''
if 'CF_Authorization' in request.cookies:
token = request.cookies['CF_Authorization']
else:
return "missing required cf authorization token", 403
keys = _get_public_keys()
# Loop through the keys since we can't pass the key set to the decoder
valid_token = False
for key in keys:
try:
# decode returns the claims that has the email when needed
jwt.decode(token, key=key, audience=POLICY_AUD, algorithms=['RS256'])
valid_token = True
break
except:
pass
if not valid_token:
return "invalid token", 403
return f()
return wrapper
@app.route('/')
@verify_token
def hello_world():
return 'Hello, World!'
if __name__ == '__main__':
app.run()
```
### JavaScript (Node.js) example
```javascript
const express = require("express");
const jose = require("jose");
// The Application Audience (AUD) tag for your application
const AUD = process.env.POLICY_AUD;
// Your CF Access team domain
const TEAM_DOMAIN = process.env.TEAM_DOMAIN;
const CERTS_URL = `${TEAM_DOMAIN}/cdn-cgi/access/certs`;
const JWKS = jose.createRemoteJWKSet(new URL(CERTS_URL));
// verifyToken is a middleware to verify a CF authorization token
const verifyToken = async (req, res, next) => {
// Check for the AUD environment variable
if (!AUD) {
return res.status(403).send({
status: false,
message: "missing required audience",
});
}
const token = req.headers["cf-access-jwt-assertion"];
// Make sure that the incoming request has our token header
if (!token) {
return res.status(403).send({
status: false,
message: "missing required cf authorization token",
});
}
try {
const result = await jose.jwtVerify(token, JWKS, {
issuer: TEAM_DOMAIN,
audience: AUD,
});
req.user = result.payload;
next();
} catch (err) {
return res.status(403).send({
status: false,
message: "invalid token",
});
}
};
const app = express();
app.use(verifyToken);
app.get("/", (req, res) => {
res.send("Hello World!");
});
app.listen(3333);
```
# Adobe Acrobat Sign
This guide covers how to configure [Adobe Acrobat Sign](https://helpx.adobe.com/sign/using/enable-saml-single-sign-on.html) as a SAML application in Cloudflare One.
## Prerequisites
- An [identity provider](/cloudflare-one/integrations/identity-providers/) configured in Cloudflare One
- Admin access to a Adobe Acrobat Sign account
- A [claimed domain](https://helpx.adobe.com/sign/using/claim-domain-names.html) in Adobe Acrobat Sign
## 1. Add a SaaS application to Cloudflare One
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **Applications**.
2. Select **Create new application** > **SaaS application**.
3. For **Application**, enter `Adobe Sign` and select the corresponding textbox that appears.
4. For the authentication protocol, select **SAML**.
5. Select **Add application**.
6. Copy the **Access Entity ID or Issuer**, **Public key**, and **SSO endpoint**.
7. Keep this window open without selecting **Select configuration**. You will finish this configuration in step [3. Finish adding a SaaS application to Cloudflare One](#3-finish-adding-a-saas-application-to-cloudflare-one).
## 2. Add a SAML SSO provider to Adobe Sign
1. In Adobe Acrobat Sign, select your profile picture > your name > **Account Settings** > **SAML Settings**.
2. Turn **SAML Allowed** on.
3. Enter a hostname (for example, `yourcompanyname`). Users can use this URL or `https://secure.adobesign.com/public/login` to sign in via SSO.
4. (Optional) For **Single Sign On Login Message**, enter a custom message (for example, `Log in via SSO`). The default message is **Sign in using your corporate credentials**.
5. Fill in the following fields:
- **Entity ID/Issuer URL**: Access Entity ID or Issuer from application configuration in Cloudflare One.
- **Login URL/SSO Endpoint**: SSO endpoint from application configuration in Cloudflare One.
- **IdP Certificate**: Public key from application configuration in Cloudflare One. Wrap the certificate in `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----`.
6. Copy the **Entity ID/SAML Audience** and **Assertion Consumer URL**.
7. Select **Save**.
## 3. Finish adding a SaaS application to Cloudflare One
1. In your open Cloudflare One window, fill in the following fields:
- **Entity ID**: Entity ID/SAML Audience from Adobe Acrobat Sign SAML SSO configuration.
- **Assertion Consumer Service URL**: Assertion Consumer URL from Adobe Acrobat Sign SAML SSO configuration.
- **Name ID format**: _Email_
2. Configure [Access policies](/cloudflare-one/access-controls/policies/) for the application.
3. Save the application.
## 4. Test the integration and finalize configuration
1. Open an incognito browser window and go to your Adobe Sign hostname URL or `https://secure.adobesign.com/public/login`. Select the option to sign in via SSO (**Sign in using your corporate credentials** if you have not configured a custom message). You will be redirected to the Cloudflare Access login screen and prompted to sign in with your identity provider.
:::note
If you receive an error while testing SSO integration, go to your profile picture > your name > **Account Settings** > **SAML Errors** for more information.
:::
2. Once this is successful, you can make sign in via SSO mandatory. Select your profile picture > your name > **Account Settings** > **SAML Settings**, and then turn on **SAML Mandatory**. Keeping **Allow Acrobat Sign Account Administrators to log in using their Acrobat Sign Credentials** turned on will allow administrators to log in even if your account experiences SSO issues.
# Area 1
import { Render } from "~/components";
.cloudflareaccess.com`.
5. Get your Metadata XML file:
1. In Cloudflare One, copy the **SSO Endpoint** for your application.
2. In a new browser tab, paste the **SSO Endpoint** and append `/saml-metadata` to the end of the URL. For example, `https://.cloudflareaccess.com/cdn-cgi/access/sso/saml//saml-metadata`.
3. Copy the resulting metadata.
6. Return to the Area 1 portal and paste the metadata into **Metadata XML**.
7. Select **Update Settings**.
If you added the application to your App Launcher, you can test the integration by going to `.cloudflareaccess.com`.
# Asana
This guide covers how to configure [Asana](https://help.asana.com/hc/en-us/articles/14075208738587-Authentication-and-access-management-options-for-paid-plans#gl-saml) as a SAML application in Cloudflare One.
## Prerequisites
- An [identity provider](/cloudflare-one/integrations/identity-providers/) configured in Cloudflare One
- Super admin access to an Asana Enterprise, Enterprise+, or Legacy Enterprise account
## 1. Add a SaaS application to Cloudflare One
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **Applications**.
2. Select **Create new application** > **SaaS application**.
3. For **Application**, select _Asana_.
4. For the authentication protocol, select **SAML**.
5. Select **Add application**.
6. Fill in the following fields:
- **Entity ID**: `https://app.asana.com/`
- **Assertion Consumer Service URL**: `https://app.asana.com/-/saml/consume`
- **Name ID format**: _Email_
7. Copy the **SSO endpoint** and **Public key**.
8. Configure [Access policies](/cloudflare-one/access-controls/policies/) for the application.
9. Save the application.
## 2. Add a SAML SSO provider to Asana
1. In Asana, select your profile picture > **Admin console** > **Security** > **SAML authentication**.
2. Under **SAML options**, select _Optional_.
3. Fill in the following fields:
- Sign-in page URL: SSO endpoint from application configuration in Cloudflare One.
- X.509 certificate: Public key from application configuration in Cloudflare One. Wrap the public key in `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----`.
4. Select **Save changes**.
## 3. Test the integration and require SSO
1. Open an incognito browser window and go to your Asana URL. You will be redirected to the Cloudflare Access login screen and prompted to sign in with your identity provider.
2. After this is successful, you may want to require users to log in via SSO. In Asana, select your profile picture > **Admin console** > **Security** > **SAML authentication**. Under **SAML options**, select **Required for all members, except guest accounts**.
# Atlassian Cloud
This guide covers how to configure [Atlassian Cloud](https://support.atlassian.com/security-and-access-policies/docs/configure-saml-single-sign-on-with-an-identity-provider/) as a SAML application in Cloudflare One.
## Prerequisites
- An [identity provider](/cloudflare-one/integrations/identity-providers/) configured in Cloudflare One
- Admin access to an Atlassian Cloud account
- Atlassian Guard Standard subscription
- A [domain](https://support.atlassian.com/user-management/docs/verify-a-domain-to-manage-accounts/) verified in Atlassian Cloud
## 1. Add a SaaS application to Cloudflare One
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **Applications**.
2. Select **Create new application** > **SaaS application**.
3. For **Application**, select _Atlassian_.
4. For the authentication protocol, select **SAML**.
5. Select **Add application**.
6. Copy the **Access Entity ID or Issuer**, **Public key**, and **SSO endpoint**.
7. Keep this window open. You will finish this configuration in step [4. Finish adding a SaaS application to Cloudflare One](#4-finish-adding-a-saas-application-to-cloudflare-one).
## 2. Create a x.509 certificate
1. Paste the **Public key** in a text editor.
2. Wrap the certificate in `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----`.
## 3. Configure an identity provider and SAML SSO in Atlassian Cloud
1. In Atlassian Cloud, go to **Security** > **Identity providers**.
2. Select **Other provider** > **Choose**.
3. For **Directory name**, enter your desired name. For example, you could enter `Cloudflare Access`.
4. Select **Add** > **Set up SAML single sign-on** > **Next**.
:::note
This screen will advise you to create an authentication policy before proceeding. You will do this in step [5. Create an application policy to test integration](#5-create-an-authentication-policy-to-test-integration).
:::
5. Fill in the following fields:
- **Identity provider Entity ID**: Access Entity ID or Issuer from application configuration in Cloudflare One.
- **Identity provider SSO URL**: SSO endpoint from application configuration in Cloudflare One.
- **Public x509 certificate**: Paste the entire x.509 certificate from step [2. Create a x.509 certificate](#2-create-a-x509-certificate).
6. Select **Next**.
7. Copy the **Service provider entity URL** and **Service provider assertion consumer service URL**.
8. Select **Next**.
9. Under **Link domain**, select the domain you want to use with SAML SSO.
10. Select **Next** > **Stop and save SAML**.
## 4. Finish adding a SaaS application to Cloudflare One
1. In your open Cloudflare One window, fill in the following fields:
- **Entity ID**: Service provider entity URL from Atlassian Cloud SAML SSO set-up.
- **Assertion Consumer Service URL**: Service provider assertion consumer service URL from Atlassian Cloud SAML SSO set-up.
- **Name ID format**: _Email_
2. Configure [Access policies](/cloudflare-one/access-controls/policies/) for the application.
3. Save the application.
## 5. Create an authentication policy to test integration
To enable SSO for users in Atlassian Cloud, create an [Atlassian authentication policy](https://support.atlassian.com/security-and-access-policies/docs/configure-authentication-policies-for-your-organization/):
1. In Atlassian Cloud, go to **Security** > **Authentication policies**.
2. Select **Add policy**.
3. Under **Directory**, select the identity provider you used to configure SAML SSO.
4. For **Policy name**, enter your desired name.
5. Select **Add**.
6. In **Settings**, turn on **Enforce single sign-on**.
7. In **Members**, select **Add members**.
8. In **Individual Users**, select your desired test user(s) in the dropdown, and select **Add members**.
9. In **Settings**, select **Update** > **Update**.
## 6. Test the integration
Open an incognito browser window and log in with the credentials of the test user you added to the test authentication policy. You will be redirected to the Cloudflare Access login screen and prompted to sign in with your identity provider. When this is successful, turn on **Enforce single sign-on** in your desired authentication policy, or add the desired users to the application policy created in step [5. Create an Application Policy to test Integration](#5-create-an-authentication-policy-to-test-integration).
# AWS
This guide covers how to configure [AWS](https://docs.aws.amazon.com/singlesignon/latest/userguide/manage-your-identity-source-idp.html) as a SAML application in Cloudflare One.
## Prerequisites
- An [identity provider](/cloudflare-one/integrations/identity-providers/) configured in Cloudflare One
- Admin access to an AWS account
## 1. Get AWS URLs
1. In the AWS admin panel, search for `IAM Identity Center`.
2. Go to **IAM Identity Center** > **Settings**.
3. In the **Identity source** tab, select the **Actions** dropdown and select _Change identity source_.
4. Change the identity source to **External identity provider**.
5. Copy the values shown in **Service provider metadata**. You will need these values when configuring the SaaS application in Cloudflare One.
Next, we will obtain **Identity provider metadata** from Cloudflare One.
## 2. Add a SaaS application to Cloudflare One
1. In a separate tab or window, open the [Cloudflare dashboard](https://dash.cloudflare.com/) and go to **Zero Trust** > **Access controls** > **Applications**.
2. Select **Create new application** > **SaaS application**.
3. For **Application**, select _Amazon AWS_.
4. For the authentication protocol, select **SAML**.
5. Select **Add application**.
6. Fill in the following fields:
- **Entity ID**: IAM Identity Center issuer URL
- **Assertion Consumer Service URL**: IAM Identity Center Assertion Consumer Service (ACS) URL
- **Name ID format**: _Email_
7. (Optional) Additional SAML attribute statements can be passed from your IdP to AWS SSO. To learn more about AWS Attribute mapping, refer to [Attribute mappings - AWS Single Sign-On](https://docs.aws.amazon.com/singlesignon/latest/userguide/attributemappingsconcept.html#supportedidpattributes).
8. AWS supports uploading a metadata XML file. To download your SAML metadata from Access:
1. Copy the **SAML Metadata endpoint**.
2. In a separate browser window, go to the SAML Metadata endpoint (`https://.cloudflareaccess.com/cdn-cgi/access/sso/saml/xxx/saml-metadata`).
3. Save the page as `access_saml_metadata.xml`.
9. Configure [Access policies](/cloudflare-one/access-controls/policies/) for the application.
10. Save the application.
## 3. Complete AWS configuration
1. Return to the **IAM Identity Center** > **Settings** > **Change identity source** tab.
2. Under **IdP SAML metadata**, upload your `access_saml_metadata.xml` file.
3. Select **Next** to review settings, type **ACCEPT** and select **Change identity source** to confirm changes.
4. Confirm that **Provisioning** is set to _Manual_.
:::caution[Important]
Access for SaaS does not currently support [SCIM provisioning](/cloudflare-one/team-and-resources/users/scim/). Make sure that:
1. Users are created in both your identity provider and AWS.
2. Users have matching usernames in your identity provider and AWS.
3. Usernames are email addresses. This is the only format AWS supports with third-party SSO providers.
:::
## 4. Test the integration
To test the connection, go to your **AWS access portal URL**. You will be redirected to the Cloudflare Access login screen and prompted to sign in with your identity provider.
# Braintree
This guide covers how to configure [Braintree](https://developer.paypal.com/braintree/articles/guides/single-sign-on-sso) as a SAML application in Cloudflare One.
## Prerequisites
- An [identity provider](/cloudflare-one/integrations/identity-providers/) configured in Cloudflare One
- Admin access to a Braintree production or sandbox account
## 1. Add a SaaS application to Cloudflare One
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **Applications**.
2. Select **Create new application** > **SaaS application**.
3. For **Application**, enter `Braintree` and select the textbox that appears below.
4. For the authentication protocol, select **SAML**.
5. Select **Add application**.
6. Fill in the following fields with temporary values:
- **Entity ID**: `placeholder`
- **Assertion Consumer Service URL**: `https://www.placeholder.com`
- **Name ID format**: _Email_
7. Copy the **SSO endpoint** and **Public key**.
8. Configure [Access policies](/cloudflare-one/access-controls/policies/) for the application.
9. Save the application.
## 2. Enable SSO Configuration in Braintree
1. In Braintree, create a [support ticket](https://developer.paypal.com/braintree/help).
2. In **Search Issues**, enter `Login and password issues` and select the corresponding value.
3. In **Issue Details**, fill in the following:
- **Merchant ID**: Your Braintree Merchant ID. This is the 16-digit value that follows `/merchants/`in your Braintree Control Panel URL.
- **Email domain(s) to be used in user IDs**: The email domain(s) that should be allowed to sign in to your account via SSO.
- **Single Sign-on HTTP POST Binding URL**: SSO endpoint from application configuration in Cloudflare One
- **Certificate for validation**: Public key from application configuration in Cloudflare One.
4. Select whether you are using a **Production** or **Sandbox** account.
5. Fill out the **Your contact information** fields and select **Submit a help request**.
6. When you receive an email stating SSO has been successfully configured for your account, you can proceed to the next step.
## 3. Finish adding a SaaS application to Cloudflare One
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **Applications**.
2. Select **Braintree** > **Edit** > **Overview**.
3. Replace the temporary values for **Entity ID** and **Assertion Consumer Service URL** with the link provided in the successful SSO configuration email from Braintree support. You will use the same link for both values.
4. Select **Save Application**.
## 4. Test the integration and add SSO users
1. In your Braintree Control Panel, select the **settings** icon > **Team**.
2. Select your desired test user.
3. Under **Single Sign-On**, select **Enable**.
4. Open an incognito browser window. In the address bar, paste `https://id.sandbox.braintreegateway.com` for a sandbox account or
`https://id.braintreegateway.com` for a production account.
5. In **Your corporate email address** field, type your test user's email. You will be redirected to the Cloudflare Access login screen and prompted to sign in with your identity provider.
6. Upon successful sign-in, you can enable SSO for other users using steps 4.1 - 4.3.
# Coupa
This guide covers how to configure [Coupa](https://compass.coupa.com/en-us/products/product-documentation/integration-technical-documentation/coupa-core-user-authentication/coupa-saml-sso-setup) as a SAML application in Cloudflare One.
## Prerequisites
- An [identity provider](/cloudflare-one/integrations/identity-providers/) configured in Cloudflare One
- Admin access to a Coupa Stage or Production account
## 1. Add a SaaS application to Cloudflare One
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **Applications**.
2. Select **Create new application** > **SaaS application**.
3. For **Application**, enter `Coupa` and select the corresponding textbox that appears.
4. For the authentication protocol, select **SAML**.
5. Select **Add application**.
6. Fill in the following fields:
- **Entity ID**:
`sso-stg1.coupahost.com` for a stage account or `sso-prd1.coupahost.com` for a production account
- **Assertion Consumer Service URL**: `https://sso-stg1.coupahost.com/sp/ACS.saml2` for a stage account or `https://sso-prd1.coupahost.com/sp/ACS.saml2` for a production account
- **Name ID format**: _Email_
7. Copy the **Access Entity ID or Issuer** and **SAML Metadata Endpoint**.
8. In **Default relay state**, enter `https://.coupahost.com/sessions/saml_post`.
9. Configure [Access policies](/cloudflare-one/access-controls/policies/) for the application.
10. Save the application.
## 2. Download the metadata file
1. Paste the SAML metadata endpoint from application configuration in Cloudflare One in a web browser.
2. Follow your browser-specific steps to download the URL's contents as an `.xml` file.
## 3. Add a SAML SSO provider in Coupa
1. In Coupa, go to **Setup** > **Company Setup** > **Security Controls**.
2. Under **Sign in using SAML**, turn on **Sign in using SAML**.
3. In **Upload IdP metadata**, select **Choose File**, and upload the `.xml` file you downloaded in step [2. Download the metadata file](#2-download-the-metadata-file).
4. Turn on **Advanced Options**.
5. For **Sign in page URL** and **Timeout URL**, enter `https://sso-stg1.coupahost.com/sp/startSSO.ping?PartnerIdpId=&TARGET=https://.coupahost.com/sessions/saml_post` using the Access Entity ID or Issuer from application configuration in Cloudflare One.
6. Select **Save**.
## 3. Create a test user and test the integration
1. In Coupa, go to **Setup** > **Company Setup** > **Users**.
2. Select **Create**, then enter the user details for your test user. For **Login** and **Single Sign-On ID**, enter the user's email address.
3. Select **Save**.
4. Open an incognito browser window and go to your Coupa URL. You will be redirected to the Cloudflare Access login screen and prompted to sign in with your identity provider.
5. Once the login is successful, you can configure other users for SSO by adding their email to the **Single Sign-On ID** field in **Setup** > **Company Setup** > **Users** > user's name.
:::note
You can use the following URL to bypass SSO and login via a username and password: `https://.coupahost.com/sessions/support_login`.
:::
# Digicert
This guide covers how to configure [Digicert](https://docs.digicert.com/en/certcentral/manage-account/saml-admin-single-sign-on-guide/configure-saml-single-sign-on.html) as a SAML application in Cloudflare One.
## Prerequisites
- An [identity provider](/cloudflare-one/integrations/identity-providers/) configured in Cloudflare One
- Admin access to a Digicert account
- [SAML](https://docs.digicert.com/en/certcentral/manage-account/saml-admin-single-sign-on-guide/saml-single-sign-on-prerequisites.html) enabled in your Digicert account
## 1. Add a SaaS application to Cloudflare One
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **Applications**.
2. Select **Create new application** > **SaaS application**.
3. For **Application**, enter `Digicert` and select the corresponding textbox that appears.
4. For the authentication protocol, select **SAML**.
5. Select **Add application**.
6. Fill in the following fields:
- **Entity ID**: `https://www.digicert.com/account/sso/metadata`
- **Assertion Consumer Service URL**: `https://www.digicert.com/account/sso/`
- **Name ID format**: _Email_
7. Copy the **SAML Metadata endpoint**.
8. Configure [Access policies](/cloudflare-one/access-controls/policies/) for the application.
9. Save the application.
## 2. Add a SAML SSO provider in Digicert
1. In Digicert, select **Settings** > **Single Sign-On** > **Set up SAML**.
2. Under **How will you send data from your IDP?**, turn on **Use a dynamic URL**.
3. Under **Use a dynamic URL**, paste the SAML Metadata endpoint from application configuration in Cloudflare One.
4. Under **How will you identify a user?**, turn on **NameID**.
5. Under **Federation Name**, enter a name (for example, `Cloudflare Access`). Your users will select this name when signing in.
6. Select **Save SAML Settings**.
## 3. Test and Enable SSO in Digicert
1. In Digicert, select **Settings** > **Single Sign-On**.
2. Copy the **SP Initiated Custom SSO URL**.
3. Paste the URL into an incognito browser window and sign in. Upon successful sign in, SAML SSO is fully enabled.
4. (Optional) By default, users can choose to sign in directly or with SSO. To require SSO sign in, go to **Account** > **Users**. Turn on **Only allow this user to log in through SAML/OIDC SSO** in the user details of the desired user.
:::note
Users can sign in using service provider initiated SSO by using the **SP Initiated Custom SSO URL**. Alternatively, users can go to `www.digicert.com/account`, select **Sign in with SSO**, and enter the name of the identity provider configured in step [2. Add a SAML SSO provider in Digicert](#2-add-a-saml-sso-provider-in-digicert).
:::
# DocuSign
This guide covers how to configure [Docusign](https://support.docusign.com/s/document-item?bundleId=rrf1583359212854&topicId=ozd1583359139126.html) as a SAML application in Cloudflare One.
## Prerequisites
- An [identity provider](/cloudflare-one/integrations/identity-providers/) configured in Cloudflare One
- Admin access to a Docusign account that has Single Sign-On available
- A [domain](https://support.docusign.com/s/document-item?bundleId=rrf1583359212854&topicId=gso1583359141256.html) verified in Docusign
## 1. Create the Access for SaaS application
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **Applications**.
2. Select **Create new application**.
3. Select **SaaS application**.
4. Use the following configuration:
- Set the **Application** to _DocuSign_.
- Put placeholder values in **EntityID** and **Assertion Consumer Service URL** (for example, `https://example.com`). We'll come back and update these.
- Set **Name ID Format** to: _Unique ID_.
5. DocuSign requires SAML attributes to do Just In Time user provisioning. Ensure you are collecting SAML attributes from your IdP:
- Group
- username
- department
- firstName
- lastName
- phone
6. These IdP SAML values can then be mapped to the following DocuSign SAML attributes:
- Email
- Surname
- Givenname
7. Set an Access policy (for example, create a policy based on _Emails ending in @example.com_).
8. Copy and save the **SSO Endpoint**, **Entity ID** and **Public Key**.
9. Transform the **Public Key** into a fingerprint:
1. Copy the **Public Key** Value.
2. Paste the **Public Key** into VIM or another code editor.
3. Wrap the value in `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----`.
4. Set the file extension to `.crt` and save.
## 2. Configure your DocuSign SSO instance
1. Ensure you have a domain claimed in DocuSign.
2. From the DocuSign Admin dashboard, select **Identity Providers**.
3. On the Identity Providers page, select **ADD IDENTITY PROVIDER**. Use the following mappings from the saved Access Application values:
- **Name**: Pick your desired name.
- **Identity Provider Issuer**: Entity ID.
- **Identity Provider Login URL**: Assertion Consumer Service URL.
4. Save the Identity Provider.
5. Upload your certificate to the _DocuSign Identity Provider_ menu.
6. Configure your SAML Attribute mappings. The Attribute Names should match the values in **IdP Value** in your Access application.
7. Go back to the Identity Provider's screen and select **Actions** > **Endpoints**. Copy and save the following:
- Service Provider Issuer URL.
- Service Provider Assertion Consumer Service URL.
## 3. Finalize your Cloudflare configuration
1. Go back to your DocuSign application under **Access controls** > **Applications**.
2. Select **Edit**.
3. Use the following mappings:
- EntityID->Service Provider Issuer URL.
- Assertion Consumer Service URL -> Service Provider Assertion Consumer Service URL.
4. Save the application.
When ready, enable the SSO for your DocuSign account and you will be able to login to DocuSign via Cloudflare SSO and your Identity Provider.
# Dropbox
This guide covers how to configure [Dropbox](https://help.dropbox.com/security/sso-admin) as a SAML application in Cloudflare One.
## Prerequisites
- An [identity provider](/cloudflare-one/integrations/identity-providers/) configured in Cloudflare One
- Admin access to a Dropbox Advanced, Business Plus, or Enterprise account
## 1. Add a SaaS application to Cloudflare One
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **Applications**.
2. Select **Create new application** > **SaaS application**.
3. For **Application**, select `Dropbox`.
4. For the authentication protocol, select **SAML**.
5. Select **Add application**.
6. Fill in the following fields:
- **Entity ID**: `Dropbox`
- **Assertion Consumer Service URL**: `https://www.dropbox.com/saml_login`
- **Name ID format**: _Email_
7. Copy the **SSO endpoint** and **Public key**.
8. Configure [Access policies](/cloudflare-one/access-controls/policies/) for the application.
9. Save the application.
## 2. Create a certificate file
1. Paste the **Public key** in a text editor.
2. Wrap the certificate in `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----`.
3. Set the file extension as `.pem` and save.
## 3. Add a SAML SSO provider to Dropbox
1. In Dropbox, go to your profile picture > **Settings** > **Admin Console** > **Security** > **Single sign-on**.
2. For **Single sign-on**, select _Optional_.
3. Select **Add Identity provider sign-in URL**.
4. Paste the SSO endpoint from application configuration in Cloudflare One and select **Done**.
5. Select **Add X.509 certificate** and upload the `.pem` file from step [2. Create a certificate file](#2-create-a-certificate-file).
6. Copy **SSO sign-in URL**. This is your custom Dropbox SSO URL.
7. Select **Save**.
## 3. Test the integration and require SSO
1. Open an incognito browser window and go to your custom Dropbox SSO URL. You will be redirected to the Cloudflare Access login screen and prompted to sign in with your identity provider.
2. After this is successful, you may want to require users to log in via SSO. Go to your profile picture > **Settings** > **Admin Console** > **Security** > **Single sign-on**. For **Single sign-on**, select _Required_. Dropbox will send an email to your users notifying them of the change.
# Generic OIDC application
import { Render } from "~/components";
This page provides generic instructions for setting up a SaaS application in Cloudflare Access using the OpenID Connect (OIDC) authentication protocol.
## Prerequisites
- An [identity provider](/cloudflare-one/integrations/identity-providers/) configured in Cloudflare One
- Admin access to the account of the SaaS application
## 1. Get SaaS application URL
In your SaaS application account, obtain the **Redirect URL** (also known as the callback URL). This is the SaaS endpoint where users are redirected to after they authenticate with Cloudflare Access.
Some SaaS applications provide the Redirect URL after you [configure the SSO provider](#3-configure-sso-in-your-saas-application).
## 2. Add your application to Access
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **Applications**.
2. Select **Create new application**.
3. Select **SaaS application**.
4. Select your **Application** from the drop-down menu. If your application is not listed, enter a custom name in the **Application** field and select the textbox that appears below.
5. Select **OIDC**.
6. Select **Add application**.
7. In **Scopes**, select the user attributes that you want Access to send in the ID token. For more information about configuring OIDC scopes and claims, refer to [OIDC claims](#oidc-claims).
8. In **Redirect URLs**, enter the callback URL obtained from the SaaS application.
9. (Optional) Enable [Proof of Key Exchange (PKCE)](https://www.oauth.com/oauth2-servers/pkce/) if the protocol is supported by your IdP. PKCE will be performed on all login attempts.
10. Copy the following values to input into your SaaS application. Different SaaS applications may require different sets of input values.
| Field | Description |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Client secret | Credential used to authorize Access as an SSO provider |
| Client ID | Unique identifier for this Access application |
| Configuration endpoint | If supported by your SaaS application, you can configure OIDC using this endpoint instead of manually entering the URLs listed below.
`https://.cloudflareaccess.com/cdn-cgi/access/sso/oidc//.well-known/openid-configuration` |
| Issuer | Base URL for this OIDC integration
`https://.cloudflareaccess.com/cdn-cgi/access/sso/oidc/` |
| Token endpoint | Returns the user's ID token
`https://.cloudflareaccess.com/cdn-cgi/access/sso/oidc//token` |
| Authorization endpoint | URL where users authenticate with Access
`https://.cloudflareaccess.com/cdn-cgi/access/sso/oidc//authorization` |
| Key endpoint | Returns the current public keys used to [verify the Access JWT](/cloudflare-one/access-controls/applications/http-apps/authorization-cookie/validating-json/)
`https://.cloudflareaccess.com/cdn-cgi/access/sso/oidc//jwks` |
| User info endpoint | Returns all user claims in JSON format
`https://.cloudflareaccess.com/cdn-cgi/access/sso/oidc//userinfo` |
11. .example-app.com`) but could be a different value.
- .my.salesforce.com`.
- **Assertion Consumer Service URL**: The service provider's endpoint for receiving and parsing SAML assertions.
## 2. Add your application to Access
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **Applications**.
2. Select **Create new application**.
3. Select **SaaS application**.
4. Select your **Application** from the drop-down menu. If your application is not listed, enter a custom name in the **Application** field and select the textbox that appears below.
5. Select **SAML**.
6. Select **Add application**.
7. Enter the **Entity ID** and **Assertion Consumer Service URL** obtained from your SaaS application account.
8. Select the **Name ID Format** expected by your SaaS application (usually _Email_).
9. (Optional) Configure any additional [SAML attribute statements](#saml-attributes) required by your SaaS application.
10. Copy the **SSO endpoint**, **Access Entity ID or Issuer**, and **Public key**.
:::note[IdP groups]
If you are using Okta, Microsoft Entra ID (formerly Azure AD), Google Workspace, or GitHub as your IdP, Access will automatically send a SAML attribute titled `groups` with all of the user's associated groups as attribute values.
:::
11. /saml-metadata`.
### Validate SAML Response
When acting as a SAML identity provider, Cloudflare will sign both the SAML Response and the SAML Assertion using the SHA-256 algorithm. The SaaS application can validate this signature using the **Public key** that you upload to the SaaS application.
## 4. Test the integration
Open an incognito browser window and go to the SaaS application's login URL. You will be redirected to the Cloudflare Access login screen and prompted to sign in with your identity provider.
## SAML attributes
[SAML attributes](/cloudflare-one/integrations/identity-providers/generic-saml/#saml-headers-and-attributes) refer to the user identity characteristics that Cloudflare Access shares with your SAML SaaS application upon successful authentication. By default, Cloudflare Access passes the following attributes (if available) to the SaaS application:
- `id` - UUID of the user's Access identity
- `name` - Full name of the user (for example, `John Doe`)
- `email` - User's email address
- `groups` - Identity provider group membership
In Access for SaaS, you can add additional SAML attributes or customize the SAML statement sent to the SaaS application. This allows you to integrate SaaS applications which have specific SAML attribute requirements.
### SAML attribute statements
To send additional SAML attributes to your SaaS application, configure the following fields for each attribute:
- **Name**: SAML attribute name
- **SAML friendly name**: (Optional) A human readable name for the SAML attribute
- **Name format**: Specify the **Name** format expected by the SaaS application:
- `Unspecified`: (default) No specific format required.
- `URI`: Name is in a format such as `urn:ietf:params:scim:schemas:core:2.0:User:userName` or `urn:oid:2.5.4.42`.
- `Basic`: Name is a normal string such as `userName`.
- **IdP claim**: The identity provider value that should map to this SAML attribute. You can select any [SAML attribute](/cloudflare-one/integrations/identity-providers/generic-saml/#saml-headers-and-attributes) or [OIDC claim](/cloudflare-one/integrations/identity-providers/generic-oidc/#custom-oidc-claims) that was configured in a Cloudflare One IdP integration.
- **Required**: If an attribute is marked as required but is not provided by an IdP, Cloudflare will fail the authentication request and show an error page.
- **Add per IdP claim**: (Optional) If you turned on multiple identity providers for the SaaS application, you can choose different attribute mappings for each IdP. These values will override the parent **IdP claim**.
### JSONata attribute transforms
In **Advanced settings** > **Transformation**, you can enter a [JSONata](https://jsonata.org/) script that modifies a copy of the [User Registry identity](/cloudflare-one/team-and-resources/users/users/). This is useful for setting default values, excluding email addresses, or ensuring usernames meet arbitrary criteria. Access will send the modified user identity to the SaaS application as SAML attributes.
This corresponds to the `saml_attribute_transform_jsonata` field in the [Access applications API](/api/resources/zero_trust/subresources/access/subresources/applications/methods/create/).
:::note
JSONata transformations are not compatible with [SAML attribute statements](#saml-attribute-statements). JSONata transformations will override any specified SAML attributes.
:::
For example, the following JSONata script merges group names into a list and adds an `eduPersonPrincipalName` field which maps to the user email.
```txt title = "JSONata expression"
$merge([$, {"groups": groups.name, 'eduPersonPrincipalName': email}])
```
Here is an example of a user identity before applying the JSONata transform:
```json title= "User identity before JSONata transform"
{
"account_id": "699d98642c564d2e855e9661899b7252",
"amr": [
"pwd"
],
"auth_status": "NONE",
"common_name": "",
"device_id": "c1744f8b-faa1-48a4-9e5c-02ac921467fa",
"device_sessions": {
"49e653db-991e-11ee-af26-2243bf8c3428": {
"last_authenticated": 1703004275
}
},
"devicePosture": {
"8534a230-e85e-4183-8964-a4b7dcf72986": {
"rule_name": "Warp",
"success": true,
"type": "warp"
}
},
"email": "jdoe@company.com",
"gateway_account_id": "bTSquyUGwLQjYJn8cI8S1h6M6wU",
"geo": {
"country": "US"
},
"groups": [
{
"id": "12fdf91a-fb23-41b3-995a-de2f72c61d0e",
"name": "IdentityProtection-RiskyUser-RiskLevel-low"
},
{
"id": "12348f47-8234-4860-a03f-c2a1513f267b",
"name": "Global Administrator"
},
{
"id": "11235980-87d7-4917-b0aa-74c01914c40e",
"name": "Application Administrator"
}
],
"iat": 1659474397,
"id": "OidHvkPt-I-13IBSnd77UJ8cHgsrUpjs3W6_4t6ES7M",
"idp": {
"id": "b08e8c0c-a75d-4b3f-8e7b-cd427b7c7b47",
"type": "azureAD"
}
}
```
Result after applying the example JSONata script:
```json output
{
"account_id": "699d98642c564d2e855e9661899b7252",
"amr": [
"pwd"
],
"auth_status": "NONE",
"common_name": "",
"device_id": "c1744f8b-faa1-48a4-9e5c-02ac921467fa",
"device_sessions": {
"49e653db-991e-11ee-af26-2243bf8c3428": {
"last_authenticated": 1703004275
}
},
"devicePosture": {
"8534a230-e85e-4183-8964-a4b7dcf72986": {
"rule_name": "Warp",
"success": true,
"type": "warp"
}
},
"email": "jdoe@company.com",
"gateway_account_id": "bTSquyUGwLQjYJn8cI8S1h6M6wU",
"geo": {
"country": "US"
},
"groups": [
"IdentityProtection-RiskyUser-RiskLevel-low",
"Global Administrator",
"Application Administrator"
],
"iat": 1659474397,
"id": "OidHvkPt-I-13IBSnd77UJ8cHgsrUpjs3W6_4t6ES7M",
"idp": {
"id": "b08e8c0c-a75d-4b3f-8e7b-cd427b7c7b47",
"type": "azureAD"
},
"eduPersonPrincipalName": "jdoe@company.com"
}
```
For more JSONata transform use cases, refer to the following examples.
The following JSONata script removes the `groups` SAML attribute. This can be useful if your SaaS application does not need to receive user group information.
```txt title="JSONata expression"
$ ~> |$|{}, ['groups']|
```
Result after applying the JSONata transform:
```json output
{
"account_id": "699d98642c564d2e855e9661899b7252",
"amr": [
"pwd"
],
"auth_status": "NONE",
"common_name": "",
"device_id": "c1744f8b-faa1-48a4-9e5c-02ac921467fa",
"device_sessions": {
"49e653db-991e-11ee-af26-2243bf8c3428": {
"last_authenticated": 1703004275
}
},
"devicePosture": {
"8534a230-e85e-4183-8964-a4b7dcf72986": {
"rule_name": "Warp",
"success": true,
"type": "warp"
}
},
"email": "jdoe@company.com",
"gateway_account_id": "bTSquyUGwLQjYJn8cI8S1h6M6wU",
"geo": {
"country": "US"
},
"iat": 1659474397,
"id": "OidHvkPt-I-13IBSnd77UJ8cHgsrUpjs3W6_4t6ES7M",
"idp": {
"id": "b08e8c0c-a75d-4b3f-8e7b-cd427b7c7b47",
"type": "azureAD"
}
}
```
The following JSONata script changes the `groups.name` field from `name` to `group_name` and removes the `groups.id` field:
```txt title="JSONata expression"
{
"account_id": account_id,
"amr": amr,
"auth_status": auth_status,
"common_name": common_name,
"devicePosture": devicePosture,
"device_id": device_id,
"device_sessions": device_sessions,
"email": email,
"gateway_account_id": gateway_account_id,
"geo": geo,
"groups": $map($.groups, function($group) {
{"group_name": $group.name}}),
"iat": iat,
"id": id,
"idp": idp
}
```
Result after applying the JSONata transform:
```json output
{
"account_id": "699d98642c564d2e855e9661899b7252",
"amr": [
"pwd"
],
"auth_status": "NONE",
"common_name": "",
"devicePosture": {
"8534a230-e85e-4183-8964-a4b7dcf72986": {
"rule_name": "Warp",
"success": true,
"type": "warp"
}
},
"device_id": "c1744f8b-faa1-48a4-9e5c-02ac921467fa",
"device_sessions": {
"49e653db-991e-11ee-af26-2210bf8c3428": {
"last_authenticated": 1703004275
}
},
"email": "jdoe@company.com",
"gateway_account_id": "bTSquyUGwLQjYJn8cI8S1h6M6wU",
"geo": {
"country": "US"
},
"groups": [
{
"group_name": "IdentityProtection-RiskyUser-RiskLevel-low"
},
{
"group_name": "Global Administrator"
},
{
"group_name": "Application Administrator"
}
],
"iat": 1659474397,
"id": "OidHvkPt-I-13IBSnd77UJ8cHgsrUpjs3W6_4t6ES7M",
"idp": {
"id": "b08e8c0c-a75d-4b3f-8e7b-cd427b7c7b47",
"type": "azureAD"
}
}
```
The following JSONata script filters groups to those that match a regular expression.
```txt title="JSONata expression"
$merge([$, { "groups": $filter(groups, function($v) { $contains($v.name, /Administrator/) }) }])
```
Result after applying the JSONata transform:
```json output
{
"account_id": "699d98642c564d2e855e9661899b7252",
"amr": [
"pwd"
],
"auth_status": "NONE",
"common_name": "",
"device_id": "c1744f8b-faa1-48a4-9e5c-02ac921467fa",
"device_sessions": {
"49e653db-991e-11ee-af26-2243bf8c3428": {
"last_authenticated": 1703004275
}
},
"devicePosture": {
"8534a230-e85e-4183-8964-a4b7dcf72986": {
"rule_name": "Warp",
"success": true,
"type": "warp"
}
},
"email": "jdoe@company.com",
"gateway_account_id": "bTSquyUGwLQjYJn8cI8S1h6M6wU",
"geo": {
"country": "US"
},
"groups": [
{
"id": "12348f47-8234-4860-a03f-c2a1513f267b",
"name": "Global Administrator"
},
{
"id": "11235980-87d7-4917-b0aa-74c01914c40e",
"name": "Application Administrator"
}
],
"iat": 1659474397,
"id": "OidHvkPt-I-13IBSnd77UJ8cHgsrUpjs3W6_4t6ES7M",
"idp": {
"id": "b08e8c0c-a75d-4b3f-8e7b-cd427b7c7b47",
"type": "azureAD"
}
}
```
### NameID transform
By default, Access sends the user's email address as the SAML `NameID`. Some SaaS applications require a different value, such as an employee ID, a modified email address, or a username from a legacy system.
You can customize the `NameID` by setting the `name_id_transform_jsonata` field on the SaaS application via the [Access applications API](/api/resources/zero_trust/subresources/access/subresources/applications/methods/create/). This field accepts a [JSONata](https://jsonata.org/) expression that evaluates against the user's identity and must return a single string value. The result replaces the default `NameID` in the SAML assertion.
:::note
The NameID transform is only available through the API. To configure it, update the `saas_app.name_id_transform_jsonata` field on your Access application.
:::
For example, to modify the user's email so that it includes a `+sandbox` suffix (useful when connecting multiple instances of the same SaaS app):
```bash title="Set a NameID transform via the API"
curl --request PUT \
https://api.cloudflare.com/client/v4/accounts/{account_id}/access/apps/{app_id} \
--header "Authorization: Bearer {api_token}" \
--header "Content-Type: application/json" \
--data '{
"saas_app": {
"auth_type": "saml",
"name_id_transform_jsonata": "$substringBefore(email, '\''@'\'') & '\''+sandbox@'\'' & $substringAfter(email, '\''@'\'')"
}
}'
```
Given a user with the email `jdoe@company.com`, this expression produces a `NameID` of `jdoe+sandbox@company.com`.
To send a non-email attribute such as an employee ID, reference the attribute name directly in the JSONata expression. The attribute must be available in the user's identity from the IdP.
```bash title="Set employee_id as NameID"
curl --request PUT \
https://api.cloudflare.com/client/v4/accounts/{account_id}/access/apps/{app_id} \
--header "Authorization: Bearer {api_token}" \
--header "Content-Type: application/json" \
--data '{
"saas_app": {
"auth_type": "saml",
"name_id_transform_jsonata": "employee_id"
}
}'
```
Given a user identity that contains `"employee_id": "efgh5678"`, the `NameID` sent in the SAML assertion will be `efgh5678`.
To revert to the default behavior (sending the user's email as the `NameID`), set the field to an empty string:
```bash title="Remove NameID transform"
curl --request PUT \
https://api.cloudflare.com/client/v4/accounts/{account_id}/access/apps/{app_id} \
--header "Authorization: Bearer {api_token}" \
--header "Content-Type: application/json" \
--data '{
"saas_app": {
"auth_type": "saml",
"name_id_transform_jsonata": ""
}
}'
```
# GitHub Enterprise Cloud
This guide covers how to configure [GitHub Enterprise Cloud](https://docs.github.com/en/enterprise-cloud@latest/admin/managing-iam/using-saml-for-enterprise-iam/configuring-saml-single-sign-on-for-your-enterprise) as a SAML application in Cloudflare One.
## Prerequisites
- An [identity provider](/cloudflare-one/integrations/identity-providers/) configured in Cloudflare One
- A GitHub Enterprise Cloud subscription
- Access to a GitHub account as an organization owner
## 1. Add a SaaS application to Cloudflare One
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **Applications**.
2. Select **Create new application** > **SaaS application**.
3. For **Application**, select _GitHub_.
4. For the authentication protocol, select **SAML**.
5. Select **Add application**.
6. Fill in the following fields:
- **Entity ID**: `https://github.com/orgs/`
- **Assertion Consumer Service URL**: `https://github.com/orgs//saml/consume`
- **Name ID format**: _Email_
7. Copy the **SSO endpoint**, **Access Entity ID or Issuer**, and **Public key**.
8. Configure [Access policies](/cloudflare-one/access-controls/policies/) for the application.
9. Save the application.
## 2. Create an X.509 certificate
1. Paste the **Public key** in a text editor.
2. Wrap the certificate in `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----`.
## 3. Configure an identity provider and SAML SSO in GitHub Enterprise Cloud
1. In your GitHub organization page, go to **Settings** > **Authentication security**.
2. Under **SAML single sign-on**, turn on **Enable SAML authentication**.
3. Fill in the following fields:
- **Sign on URL**: SSO endpoint from application configuration in Cloudflare One.
- **Issuer**: Access Entity ID or Issuer from application configuration in Cloudflare One.
- **Public certificate**: Paste the entire x.509 certificate from step [2. Create a x.509 certificate](#2-create-a-x509-certificate).
## 4. Test the integration
Select **Test SAML configuration**. You will be redirected to the Cloudflare Access login screen and prompted to sign in with your identity provider.
When this is successful, select **Save**.
You can also turn on **Require SAML SSO authentication for all members of your organization** if you want to enforce SSO login with Cloudflare Access.
# Google Cloud
import { GlossaryTooltip } from "~/components";
This guide covers how to configure [Google Cloud](https://support.google.com/cloudidentity/topic/7558767) as a SAML application in Cloudflare One.
:::caution
When configuring Google Cloud with Access, the following limitations apply:
- Users will not be able to log in using [Google](/cloudflare-one/integrations/identity-providers/google/) or [Google Workspace](/cloudflare-one/integrations/identity-providers/google-workspace/) as an identity provider after Google Cloud is configured with Access.
- The integration of Access as a single sign-on provider for your Google Cloud account does not work for Google super admins. It will work for other users.
:::
## Prerequisites
- An [identity provider](/cloudflare-one/integrations/identity-providers/) configured in Cloudflare One
- Admin access to a Google Workspace account
- [Cloud Identity Free or Premium](https://support.google.com/cloudidentity/answer/7389973) set up in your organization's Google Cloud account
## 1. Add a SaaS application to Cloudflare One
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **Applications**.
2. Select **Create new application** > **SaaS application**.
3. For **Application**, select _Google Cloud_.
4. For the authentication protocol, select **SAML**.
5. Select **Add application**.
6. Fill in the following fields:
- **Entity ID**: `google.com`
- **Assertion Consumer Service URL**: `https://www.google.com/a//acs`
- **Name ID format**: _Email_
7. Copy the **SSO endpoint**, **Access Entity ID or Issuer**, and **Public key**.
8. Configure [Access policies](/cloudflare-one/access-controls/policies/) for the application.
9. Save the application.
## 2. Create a x.509 certificate
1. Paste the Public key from application configuration in Cloudflare One into a text editor.
2. Wrap the certificate in `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----`.
3. Set the file extension as `.crt` and save.
## 3. Create an SSO provider in Google Cloud
1. In your [Google Admin console](https://admin.google.com/), go to **Security** > **Authentication** > **SSO with third party IdP**.
2. Select **Third-party SSO profile for your organization** > **Add SSO Profile**.
3. Turn on **Set up SSO with third-party identity provider**.
4. Fill in the following information:
- **Sign-in page URL**: SSO endpoint from application configuration in Cloudflare One.
- **Sign-out page URL**: `https://.cloudflareaccess.com/cdn-cgi/access/logout`, where `` is your Cloudflare One team name .
- **Verification certificate**: Upload the `.crt` certificate file from step [2. Create a x.509 certificate](#2-create-a-x509-certificate).
5. (Optional) Turn on **Use a domain specific issuer**. If you select this option, Google will send an issuer specific to your Google Cloud domain (`google.com/a/` instead of the standard `google.com`).
## 4. Test the integration
Open an incognito browser window and go to your Google Cloud URL (`https://console.cloud.google.com/a/`). Sign in using credentials that do not belong to a super admin account.
## Troubleshooting
`Error: "G Suite - This account cannot be accessed because the login credentials could not be verified."`
If you see this error, it is likely that the public key and private key do not match. Confirm that your certificate file includes the correct public key.
# Google Workspace
import { GlossaryTooltip } from "~/components";
This guide covers how to configure [Google Workspace](https://support.google.com/a/topic/7579248?ref_topic=7556686&sjid=14539485562330725560-NA) as a SAML application in Cloudflare One.
:::note
The integration of Access as a single sign-on provider for your Google Workspace account does not work for Google super admins. It will work for other users.
:::
## Prerequisites
- An [identity provider](/cloudflare-one/integrations/identity-providers/) configured in Cloudflare One
- Admin access to a Google Workspace account
## 1. Create an application in Cloudflare One
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **Applications**.
2. Select **Create new application**.
3. Select **SaaS application**.
4. Fill in the following information:
- **Application**: _Google_.
- **Entity ID**: Use the value provided to you by Google when [configuring your SAML SSO provider](https://saml-doc.okta.com/SAML_Docs/How-to-Enable-SAML-2.0-in-Google-Apps.html).
- **Assertion Consumer Service URL**: `https://www.google.com/a//acs`, where `` is your Google Workspace domain.
- **Name ID Format**: _Email_.
:::caution
When you put your Google Workspace behind Access, users will not be able to log in using [Google](/cloudflare-one/integrations/identity-providers/google/) or [Google Workspace](/cloudflare-one/integrations/identity-providers/google-workspace/) as an identity provider. To secure Google Workspace behind Access and avoid an [authentication loop](/cloudflare-one/access-controls/troubleshooting/#google-workspace-redirect-loop), you must configure a different identity provider (not Google or Google Workspace) for authentication.
:::
5. [Create an Access policy](/cloudflare-one/access-controls/policies/) for your application. For example, you could allow users with an `@your_domain.com` email address.
6. Copy the **SSO endpoint**, **Access Entity ID or Issuer**, and **Public key**. These values will be used to configure Google Workspace.
7. Save the application.
## 2. Create a certificate from your public key
1. Copy and then paste your **Public key** into a text editor.
2. Wrap the certificate in `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----`. For example,
```txt
-----BEGIN CERTIFICATE-----
-----END CERTIFICATE-----
```
3. Set the file extension as `.crt` and save.
## 3. Create an SSO provider in Google Workspace
1. Log in to your [Google Admin console](https://admin.google.com/).
2. Go to **Security** > **Authentication** > **SSO with third party IdP**.
3. Select **Third-party SSO profile for your organization**.
4. Enable **Set up SSO with third-party identity provider**.
5. Fill in the following information:
- **Sign-in page URL**: Copy and then paste your **SSO endpoint** from Cloudflare One.
- **Sign-out page URL**: `https://.cloudflareaccess.com/cdn-cgi/access/logout`, where `` is your Cloudflare One team name .
- **Verification certificate**: Upload the certificate file containing your public key.
6. (Optional) Enable **Use a domain specific issuer**. If you select this option, Google will send an issuer specific to your Google Workspace domain (`google.com/a/` instead of the standard `google.com`).
## 4. Test the integration
1. In your [Google Admin console](https://admin.google.com/), go to **Apps** > **Google Workspace** > **Gmail** > **Setup**.
2. Copy your Gmail **Web address**.
3. Open an incognito browser window and go to your Gmail web address (for example, `https://mail.google.com/a/`).
An Access login screen should appear.
## Troubleshooting
`Error: "G Suite - This account cannot be accessed because the login credentials could not be verified."`
If you see this error, it is likely that the public key and private key do not match. Confirm that your certificate file includes the correct public key.
# Grafana Cloud
This guide covers how to configure [Grafana Cloud](https://grafana.com/docs/grafana-cloud/account-management/authentication-and-permissions/authorization/#configure-oauth-20-with-generic-oauth) as an OIDC application in Cloudflare One.
## Prerequisites
- An [identity provider](/cloudflare-one/integrations/identity-providers/) configured in Cloudflare One
- Admin access to a Grafana Cloud account
## 1. Add a SaaS application to Cloudflare One
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **Applications**.
2. Select **Create new application**.
3. Select **SaaS application**.
4. For **Application**, enter `Grafana Cloud` and select the corresponding textbox that appears.
5. For the authentication protocol, select **OIDC**.
6. Select **Add application**.
7. In **Scopes**, select the attributes that you want Access to send in the ID token.
8. In **Redirect URLs**, enter `https:///login/generic_oauth`.
9. (Optional) Enable [Proof of Key Exchange (PKCE)](https://www.oauth.com/oauth2-servers/pkce/) if the protocol is supported by your IdP. PKCE will be performed on all login attempts.
10. Copy the **Client secret**, **Client ID**, **Token endpoint**, and **Authorization endpoint**.
11. Configure [Access policies](/cloudflare-one/access-controls/policies/) for the application.
12. (Optional) In **Experience settings**, configure [App Launcher settings](/cloudflare-one/access-controls/access-settings/app-launcher/) by turning on **Enable App in App Launcher** and, in **App Launcher URL**, entering `https:///login`.
13. Save the application.
## 2. Add a SSO provider to Grafana Cloud
1. In Grafana Cloud, select the **menu** icon > **Administration** > **Authentication** > **Generic OAuth**.
2. (Optional) For **Display name**, enter a new display name (for example, `Cloudflare Access`). Users will select **Sign in with (display name)** when signing in via SSO.
3. Fill in the following fields:
- **Client Id**: Client ID from application configuration in Cloudflare One
- **Client secret**: Client secret from application configuration in Cloudflare One
- **Scopes**: Delete `user:email` and enter the scopes configured in Cloudflare One
- **Auth URL**: Authorization endpoint from application configuration in Cloudflare One
- **Token URL**: Token endpoint from application configuration in Cloudflare One
4. Select **Save**.
## 3. Test the integration
Open an incognito browser window and go to your Grafana domain (`https:///login`). Select **Sign in with (display name)**. You will be redirected to the Cloudflare Access login screen and prompted to sign in with your identity provider.
# Grafana
This guide covers how to configure [Grafana](https://grafana.com/docs/grafana/latest/setup-grafana/configure-security/configure-authentication/generic-oauth/) as an OIDC application in Cloudflare One.
## Prerequisites
- An [identity provider](/cloudflare-one/integrations/identity-providers/) configured in Cloudflare One
- Admin access to a Grafana account
:::note
You can also configure OIDC SSO for Grafana using a [configuration file](https://grafana.com/docs/grafana/latest/setup-grafana/configure-security/configure-authentication/generic-oauth/#configure-generic-oauth-authentication-client-using-the-grafana-configuration-file) instead of using Grafana's user interface (UI), as documented in this guide.
:::
## 1. Add a SaaS application to Cloudflare One
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **Applications**.
2. Select **Create new application**.
3. Select **SaaS application**.
4. For **Application**, select _Grafana_.
5. For the authentication protocol, select **OIDC**.
6. Select **Add application**.
7. In **Scopes**, select the attributes that you want Access to send in the ID token.
8. In **Redirect URLs**, enter `https:///login/generic_oauth`.
9. (Optional) Enable [Proof of Key Exchange (PKCE)](https://www.oauth.com/oauth2-servers/pkce/) if the protocol is supported by your IdP. PKCE will be performed on all login attempts.
10. Copy the **Client secret**, **Client ID**, **Token endpoint**, and **Authorization endpoint**.
11. Configure [Access policies](/cloudflare-one/access-controls/policies/) for the application.
12. (Optional) In **Experience settings**, configure [App Launcher settings](/cloudflare-one/access-controls/access-settings/app-launcher/) by turning on **Enable App in App Launcher** and, in **App Launcher URL**, entering `https:///login`.
13. Save the application.
## 2. Add a SSO provider to Grafana
1. In Grafana, select the **menu** icon > **Administration** > **Authentication** > **Generic OAuth**.
2. (Optional) For **Display name**, enter a new display name (for example, `Cloudflare Access`). Users will select **Sign in with (display name)** when signing in via SSO.
3. Fill in the following fields:
- **Client Id**: Client ID from application configuration in Cloudflare One
- **Client secret**: Client secret from application configuration in Cloudflare One
- **Scopes**: Delete `user:email` and enter the scopes configured in Cloudflare One
- **Auth URL**: Authorization endpoint from application configuration in Cloudflare One
- **Token URL**: Token endpoint from application configuration in Cloudflare One
4. Select **Save**.
## 3. Test the integration
Log out, then select **Sign in with (display name)**. You will be redirected to the Cloudflare Access login screen and prompted to sign in with your identity provider.
# Greenhouse Recruiting
This guide covers how to configure [Greenhouse Recruiting](https://support.greenhouse.io/hc/en-us/articles/360040753811-Configure-single-sign-on-SSO-for-Greenhouse-Recruiting) as a SAML application in Cloudflare One.
## Prerequisites
- An [identity provider](/cloudflare-one/integrations/identity-providers/) configured in Cloudflare One
- Admin access to an Advanced or Expert Greenhouse Recruiting site
## 1. Add a SaaS application to Cloudflare One
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **Applications**.
2. Select **Create new application** > **SaaS application**.
3. For **Application**, enter `Greenhouse` and select the corresponding textbox that appears.
4. For the authentication protocol, select **SAML**.
5. Select **Add application**.
6. Copy the **SAML Metadata endpoint**.
7. Keep this window open. You will finish this configuration in step [4. Finish adding a SaaS application to Cloudflare One](#4-finish-adding-a-saas-application-to-cloudflare-one).
## 2. Download the metadata file
1. Paste the SAML Metadata endpoint from application configuration in Cloudflare One in a web browser.
2. Follow your browser-specific steps to download the URL's contents as an `.xml` file.
## 3. Add a SAML SSO provider to Greenhouse
1. In Greenhouse Recruiting, go to the **Configure** icon > **Dev Center** > **Single sign-on**.
2. Copy the **SSO Assertion Consumer URL**.
3. Under **Upload XML file**, select **Choose a file**, and upload the `.xml` file created in step [2. Download the metadata file](#2-download-the-metadata-file).
4. Change the **Entity ID** to `greenhouse.io`.
5. Keep this window open without selecting **Begin testing**. You will finish this configuration in step [5. Test the integration and finalize configuration](#5-test-the-integration-and-finalize-configuration).
## 4. Finish adding a SaaS application to Cloudflare One
1. In your open Cloudflare One window, fill in the following fields:
- **Entity ID**: `greenhouse.io`
- **Assertion Consumer Service URL**: SSO Assertion Consumer URL from SSO configuration in Greenhouse Recruiting.
- **Name ID format**: _Email_
2. Configure [Access policies](/cloudflare-one/access-controls/policies/) for the application.
3. Save the application.
## 5. Test the integration and finalize configuration
1. In your open Greenhouse Recruiting window, select **Begin Testing** > **Proceed**.
2. Open an incognito browser window and go to your Greenhouse Recruiting URL. Choose the SSO login option. You will be redirected to the Cloudflare Access login screen and prompted to sign in with your identity provider.
3. Once SSO sign in is successful, go to the **Configure** icon > **Dev Center** > **Single sign-on**.
4. Select **Finalize Configuration**.
5. In the text field, enter `CONFIGURE`.
6. Select **Finalize**. Now, users will only be able to sign in with SSO.
# Hubspot
This guide covers how to configure [Hubspot](https://knowledge.hubspot.com/account-security/set-up-single-sign-on-sso) as a SAML application in Cloudflare One.
## Prerequisites
- An [identity provider](/cloudflare-one/integrations/identity-providers/) configured in Cloudflare One
- Admin access to a Hubspot Enterprise plan account
## 1. Configure Hubspot
1. Go to **Settings** > **Account**, then go to **Defaults** > **Security**.
2. Select _Single Sign-on_.
3. Copy the values for _Audience URI_ and _Sign on URL_.
## 2. Configure Cloudflare Access
1. In Cloudflare One, go to **Access controls** > **Applications**, select **Create new application**, and select **SaaS application**.
2. Set the **Application type** to _Hubspot_.
3. Use the following Hubspot field mappings:
| Hubspot values | Cloudflare values |
| -------------- | ------------------------------ |
| Audience URI | Entity ID |
| Sign On URL | Assertion Consumer Service URL |
4. Set **NameID** to _Email_.
5. Add any desired [Access policies](/cloudflare-one/access-controls/policies/) to your application.
6. Copy the **SSO endpoint** and **Access Entity ID**.
7. Save the application.
## 3. Create a x.509 certificate
1. Paste the **Public key** in a text editor.
2. Wrap the certificate in `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----`.
## 4. Finalize Hubspot configuration
1. Use the following field mappings:
| Cloudflare value | Hubspot value |
| ---------------- | ------------------------------------ |
| SSO endpoint | Identity Provider Single Sign-on URL |
| Entity ID | Identity Provider Identifier |
| Public key | Certificate |
2. Select **Verify** to validate the integration.
Your configuration is now complete. Hubspot SSO can be switched on for specific users or the entire account.
# SaaS applications
import { DirectoryListing } from "~/components"
Cloudflare Access allows you to add an additional authentication layer to your SaaS applications. When you integrate a SaaS application with Access, users log in to the application with Cloudflare as the Single Sign-On provider. The user is then redirected to the configured identity providers for that application and are only granted access if they pass your Access policies.
Cloudflare integrates with the majority of SaaS applications that support the SAML or OIDC authentication protocol. If you do not see your application listed below, refer to our [generic SAML](/cloudflare-one/access-controls/applications/http-apps/saas-apps/generic-saml-saas/) or [generic OIDC](/cloudflare-one/access-controls/applications/http-apps/saas-apps/generic-oidc-saas/) guide and consult your SaaS application's documentation.
**Authentication** > **Single sign-on**",
two: "If you have not previously [verified the domain](https://help.miro.com/hc/articles/360034831793-Domain-control), enter",
}}
/>
## 3. Test the integration
In the Miro SAML/SSO configuration page, select **Test SSO Configuration**. You will be redirected to the Cloudflare Access login screen and prompted to sign in with your identity provider. If the login is successful, you will receive a **SSO configuration test was successful** message.
:::note
When testing the integration, you do not have to use an email from a domain you have configured for SSO or a user configured in Miro. The only requirement is that the user is already configured in your identity provider.
:::
# PagerDuty
This guide covers how to configure [PagerDuty](https://support.pagerduty.com/docs/sso) as a SAML application in Cloudflare One.
## Prerequisites
- An [identity provider](/cloudflare-one/integrations/identity-providers/) configured in Cloudflare One
- Admin access to a PagerDuty site
## 1. Add a SaaS application to Cloudflare One
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **Applications**.
2. Select **Create new application** > **SaaS application**.
3. For **Application**, select _PagerDuty_.
4. For the authentication protocol, select **SAML**.
5. Select **Add application**.
6. Fill in the following fields:
- **Entity ID**: `https://.pagerduty.com`
- **Assertion Consumer Service URL**: ` https://.pagerduty.com/sso/saml/consume`
- **Name ID format**: _Email_
7. Copy the **SSO endpoint** and **Public key**.
8. Configure [Access policies](/cloudflare-one/access-controls/policies/) for the application.
9. Save the application.
## 2. Create a x.509 certificate
1. Paste the **Public key** in a text editor.
2. Amend the public key so each row is a maximum of 64 characters long. Originally, each full row of the public key is 65 characters long.
3. Wrap the certificate in `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----`.
## 3. Add a SAML SSO provider to PagerDuty
1. In PagerDuty, select your profile picture and go to **Account Settings** > **Single Sign-on**.
2. Turn on **SAML**.
3. In **X.509 Certificate**, paste the entire x.509 certificate from step [2. Create a x.509 certificate](#2-create-a-x509-certificate).
4. In **Login URL**, paste the SSO endpoint from application configuration in Cloudflare One.
5. Select **Save Changes**.
## 4. Test the integration and finalize SSO configuration
1. Open an incognito window and paste your PagerDuty URL into the address bar. Select **Sign In With Single Sign-On**. You will be redirected to the Cloudflare Access login screen and prompted to sign in with your identity provider.
2. In an incognito window, paste your PagerDuty URL and select **Sign In With Single Sign-On**. You will be redirected to the Cloudflare Access login screen and prompted to sign in with your identity provider.
3. Once SSO sign in is successful, select your profile picture and go to **Account Settings** > **Single Sign-on**.
4. Turn off **Allow username/password login** and select **Save Changes**. Now, users will only be able to sign in with SSO.
# Pingboard
This guide covers how to configure [Pingboard](https://support.pingboard.com/hc/en-us/articles/360046585994-Set-Up-a-Custom-SSO-Solution) as a SAML application in Cloudflare One.
## Prerequisites
- An [identity provider](/cloudflare-one/integrations/identity-providers/) configured in Cloudflare One
- Admin access to a Pingboard account
## 1. Add a SaaS application to Cloudflare One
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **Applications**.
2. Select **Create new application** > **SaaS application**.
3. For **Application**, enter `Pingboard` and select the corresponding textbox that appears.
4. For the authentication protocol, select **SAML**.
5. Select **Add application**.
6. Fill in the following fields:
- **Entity ID**: `http://app.pingboard.com/sp`
- **Assertion Consumer Service URL**: `https://sso-demo.pingboard.com/auth/saml/consume`
- **Name ID format**: _Email_
7. Copy the **SAML Metadata endpoint**.
8. Configure [Access policies](/cloudflare-one/access-controls/policies/) for the application.
9. Save the application.
## 2. Add a SAML SSO provider to Pingboard
1. In Pingboard, go to **Account** > **Add-Ons**.
2. Under **Third-Party Integrations**, select **Custom SSO**.
3. In a web browser, paste the SAML Metadata endpoint you copied from the application configuration in Cloudflare One. Next, copy the contents of the displayed page.
4. In Pingboard, under **IdP Metadata**, paste the contents from the SAML Metadata endpoint.
5. (Optional) Under **Sign in with**, enter a name (for example, `Cloudflare Access`). Your users will select this name when signing in.
## 3. Test the integration
Open an incognito browser window and go to your Pingboard URL. You will be redirected to the Cloudflare Access login screen and prompted to sign in with your identity provider.
# Salesforce (OIDC)
import { Render } from "~/components";
This guide covers how to configure [Salesforce](https://help.salesforce.com/s/articleView?id=sf.sso_provider_openid_connect.htm&type=5) as an OpenID Connect (OIDC) application in Cloudflare One.
## Prerequisites
- An [identity provider](/cloudflare-one/integrations/identity-providers/) configured in Cloudflare One
- Admin access to a Salesforce account
## 1. Add a SaaS application to Cloudflare One
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **Applications**.
2. Select **Create new application** > **SaaS application**.
3. For **Application**, select _Salesforce_.
4. For the authentication protocol, select **OIDC**.
5. Select **Add application**.
6. In **Scopes**, select the attributes that you want Access to send in the ID token.
7. In **Redirect URLs**, enter the callback URL obtained from Salesforce (`https://.my.salesforce.com/services/authcallback/`). Refer to [Add a SSO provider to Salesforce](#2-add-a-sso-provider-to-salesforce) for instructions on obtaining this value.
8. (Optional) Enable [Proof of Key Exchange (PKCE)](https://www.oauth.com/oauth2-servers/pkce/) if the protocol is supported by your IdP. PKCE will be performed on all login attempts.
9. Copy the following values:
- **Client ID**
- **Client Secret**
- **Authorization endpoint**
- **Token endpoint**
- **User info endpoint**
10. Configure [Access policies](/cloudflare-one/access-controls/policies/) for the application.
11. (Optional) In **Experience settings**, configure [App Launcher settings](/cloudflare-one/access-controls/access-settings/app-launcher/) by turning on **Enable App in App Launcher** and, in **App Launcher URL**, entering `https://.my.salesforce.com`.
12. Save the application.
## 2. Add a SSO provider to Salesforce
1. In Salesforce, go to **Setup**.
2. In the **Quick Find** box, enter `auth` and select **Auth providers**.
3. Select **New**.
4. For the provider type, select **OpenID Connect**.
5. Enter a name for the SSO provider (for example, `Cloudflare Access`).
6. Fill in the following fields with values obtained from Cloudflare Access:
- **Consumer Key**: Client ID
- **Consumer Secret**: Client Secret
- **Authorize Endpoint URL**: Authorization endpoint
- **Token endpoint URL**: Token endpoint
- **User Info Endpoint URL**: User info endpoint
- **Token Issuer**: Issuer
7. (Optional) Enable **Use Proof Key for Code Exchange** if you enabled it in Access.
8. In **Default Scopes**, enter a space-separated list of the scopes you configured in Access (for example, `openid email profile groups`).
9. Select **Save**.
10. Copy the **Callback URL**:
```txt
https://.my.salesforce.com/services/authcallback/
```
11. In Cloudflare One, paste the Callback URL into the **Redirect URL** field.
To test the integration, open an incognito browser window and go to the **Test-Only Initialization URL** ( `https://.my.salesforce.com/services/auth/test/`)
## 3. Enable Single Sign-On in Salesforce
1. .my.salesforce.com`).
# Salesforce (SAML)
import { Details, Render } from "~/components";
This guide covers how to configure [Salesforce](https://help.salesforce.com/s/articleView?id=sf.sso_saml.htm&type=5) as a SAML application in Cloudflare One.
## Prerequisites
- An [identity provider](/cloudflare-one/integrations/identity-providers/) configured in Cloudflare One
- Admin access to a Salesforce account
## 1. Add a SaaS application to Cloudflare One
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **Applications**.
2. Select **Create new application** > **SaaS application**.
3. For **Application**, select _Salesforce_.
4. For the authentication protocol, select **SAML**.
5. Select **Add application**.
6. Fill in the following fields:
- **Entity ID**: `https://.my.salesforce.com` or `https://.my.salesforce.com?so=`, if your account was created before summer 2019 or does not have a My Domain subdomain.
- **Assertion Consumer Service URL**: `https://.my.salesforce.com` or `https://.my.salesforce.com?so=`, if your account was created before summer 2019 or does not have a My Domain subdomain.
- **Name ID format**: _Email_
:::note
If you are unsure of which URL to use in the **Entity ID** and **Assertion Consumer Service URL** fields, you can check your Salesforce account's metadata. In Salesforce, go to the **Single Sign-On Settings** page and select **Download Metadata**. In this file, you will find the correct URLs to use.
:::
7. Copy the **SSO endpoint**, **Public key**, and **Access Entity ID or Issuer**.
8. Configure [Access policies](/cloudflare-one/access-controls/policies/) for the application.
9. Save the application.
## 2. Create a certificate file
1. Paste the **Public key** in a text editor.
2. Wrap the certificate in `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----`.
3. Set the file extension as `.crt` and save.
## 3. Add a SAML SSO provider to Salesforce
1. In Salesforce, go to **Setup**.
2. In the **Quick Find** box, enter `single sign-on` and select **Single Sign-On Settings**.
3. In **SAML Single Sign-On Settings**, select **New**.
4. Fill in the following fields:
- **Name:** Name of the SSO provider (for example, `Cloudflare Access`). Users will select this name when signing in to Salesforce.
- **API name:** (this will pre-populate)
- **Issuer:** Paste the Access Entity ID or Issuer from application configuration in Cloudflare One.
- **Identity Provider Certificate**: Upload the `.crt` certificate file from [2. Create a certificate file](#2-create-a-certificate-file).
- **Entity ID**: `https://.my.salesforce.com`
- **SAML Identity type:** If the user's Salesforce username is their email address, select _Assertion contains the User's Salesforce username_. Otherwise, select _Assertion contains the Federation ID from the User object_ and make sure the user's Federation ID matches their email address.
1. In the **Quick Find** box, enter `users` and select **Users**. 2. Select
the user. 3. Verify that the user's **Federation ID** matches the email
address used to authenticate to Cloudflare Access.
- **Identity Provider Login URL**: SSO endpoint provided in Cloudflare One
for this application.
5. Select **Save**.
## 4. Enable Single Sign-On in Salesforce
1. Configure Single Sign-On settings:
1. In the **Quick Find** box, enter `single sign-on` and select **Single Sign-On Settings**.
2. (Optional) To require users to login with Cloudflare Access, turn on **Disable login with Salesforce credentials**.
3. Turn on **SAML Enabled**.
4. Turn on **Make federation ID case-insensitive**.
2. .my.salesforce.com`).
# ServiceNow (OIDC)
This guide covers how to configure [ServiceNow](https://docs.servicenow.com/bundle/washingtondc-platform-security/page/integrate/single-sign-on/task/create-OIDC-configuration-SSO.html) as an OIDC application in Cloudflare One.
## Prerequisites
- An [identity provider](/cloudflare-one/integrations/identity-providers/) configured in Cloudflare One
- Admin access to a ServiceNow account
## 1. Add a SaaS application to Cloudflare One
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **Applications**.
2. Select **Create new application** > **SaaS application**.
3. For **Application**, enter `ServiceNow` and select the corresponding textbox that appears.
4. For the authentication protocol, select **OIDC**.
5. Select **Add application**.
6. In **Scopes**, select the attributes that you want Access to send in the ID token.
7. In **Redirect URLs**, enter `https://.service-now.com/navpage.do`.
8. (Optional) Enable [Proof of Key Exchange (PKCE)](https://www.oauth.com/oauth2-servers/pkce/) if the protocol is supported by your IdP. PKCE will be performed on all login attempts.
9. Copy the **Client secret** and **Client ID**.
10. Configure [Access policies](/cloudflare-one/access-controls/policies/) for the application.
11. (Optional) In **Experience settings**, configure [App Launcher settings](/cloudflare-one/access-controls/access-settings/app-launcher/) by turning on **Enable App in App Launcher** and, in **App Launcher URL**, entering `https://.service-now.com`.
12. Save the application.
## 2. Add the Multiple Provider Single Sign-On Installer Plugin to ServiceNow
1. In ServiceNow, select **All**.
2. In the search bar, enter `System Applications`, and under **All Available Applications**, select **All**.
3. In the search bar, enter `Integration - Multiple Provider Single Sign-On Installer`.
4. Select **Install**.
5. Ensure that **Install now** is selected, and select **Install**.
## 3. Add and Test an OIDC SSO provider in ServiceNow
1. Select **All**.
2. In the search bar enter `Multi-Provider SSO`, and select **Identity Providers**.
3. Select **New** > **OpenID Connect**.
4. In the pop-up, fill in the following fields:
- **Name**: Name of the SSO (for example, `Cloudflare Access`). Unless otherwise configured, users will select this name when signing in to ServiceNow.
- **Client ID**: **Client ID** from application configuration in Cloudflare One.
- **Client Secret**: **Client Secret** from application configuration in Cloudflare One.
- **Well Known Configuration URL**: `https://.cloudflareaccess.com/cdn-cgi/access/sso/oidc//.well-known/openid-configuration`.
5. Select **Import**.
6. Ensure **Active** is turned on
7. Turn on **Show as Login option**, and for **SSO label** enter a label for the user login screen, if desired.
8. Select **Update**.
## 4. Test the integration
For SSO to appear on the login screen, you must have [account recovery](https://docs.servicenow.com/bundle/washingtondc-platform-security/page/integrate/single-sign-on/concept/sso-acct-recovery.html) enabled and configured for at least one admin account. After account recovery is configured, log out of ServiceNow and open an incognito browser window. Go to your ServiceNow URL. Select the SSO name you just configured, which will prompt you to sign in with your identity provider. When the integration is successful, you can go back to the OIDC configuration screen to turn on **Default** and/or **Auto Redirect IDP**.
# ServiceNow (SAML)
This guide covers how to configure [ServiceNow](https://docs.servicenow.com/bundle/washingtondc-platform-security/page/integrate/single-sign-on/task/t_CreateASAML2Upd1SSOConfigMultiSSO.html) as a SAML application in Cloudflare One.
## Prerequisites
- An [identity provider](/cloudflare-one/integrations/identity-providers/) configured in Cloudflare One
- Admin access to a ServiceNow account
## 1. Add a SaaS application to Cloudflare One
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **Applications**.
2. Select **Create new application** > **SaaS application**.
3. For **Application**, enter `ServiceNow` and select the corresponding textbox that appears.
4. For the authentication protocol, select **SAML**.
5. Select **Add application**.
6. Fill in the following fields:
- **Entity ID**: `https://.service-now.com`
- **Assertion Consumer Service URL**: `https://.service-now.com/navpage.do`
- **Name ID format**: _Email_
7. Copy the **SAML Metadata endpoint**.
8. Configure [Access policies](/cloudflare-one/access-controls/policies/) for the application.
9. Save the application.
## 2. Add the Multiple Provider Single Sign-On Installer Plugin to ServiceNow
1. In ServiceNow, select **All**.
2. In the search bar, enter `System Applications`, and under **All Available Applications**, select **All**.
3. In the search bar, enter `Integration - Multiple Provider Single Sign-On Installer`.
4. Select **Install**.
5. Ensure that **Install now** is selected, and select **Install**.
## 3. Add and Test a SAML SSO provider in ServiceNow
1. Select **All**.
2. In the search bar enter `Multi-Provider SSO`, and select **Identity Providers**.
3. Select **New** > **SAML**.
4. In the pop-up, ensure that **URL** is selected.
5. Paste the **SAML Metadata endpoint** from application configuration in Cloudflare One in the empty field.
6. Select **Import**.
7. (Optional) Change the **Name** field to a more recognizable name.
8. Turn off **Sign AuthnRequest**.
9. Select **Update**.
10. In the pop-up, select **Cancel** and then **>**.
11. Select the **Name** of the configuration you just completed.
12. Select **Test Connection**.
13. If the test succeeds, select **Activate**.
# Slack
import { TabItem, Tabs } from "~/components";
This guide covers how to configure [Slack](https://slack.com/help/articles/203772216-SAML-single-sign-on) as a SAML application in Cloudflare One.
## Prerequisites
- An [identity provider](/cloudflare-one/integrations/identity-providers/) configured in Cloudflare One
- Admin access to a Slack Business+ or Enterprise Grid plan account
## 1. Add a SaaS application to Cloudflare One
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **Applications**.
2. Select **Create new application** > **SaaS application**.
3. For **Application**, select _Slack_.
4. For the authentication protocol, select **SAML**.
5. Select **Add application**.
6. Fill in the following fields:
- **Entity ID**: `https://slack.com`
- **Assertion Consumer Service URL**: `https://.slack.com/sso/saml`
- **Name ID format**: The format expected by Slack, usually _Email_
7. Copy the **SSO endpoint**, **Access Entity ID or Issuer**, and **Public key**.
8. Configure [Access policies](/cloudflare-one/access-controls/policies/) for the application.
9. Save the application.
## 2. Create a x.509 certificate
1. Paste the **Public key** in a text editor.
2. Wrap the certificate in `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----`.
## 3. Add a SAML SSO provider to Slack
1. In Slack, go to **Settings & administrations** > **Workspace settings** > **Authentication**.
2. Select **Configure**.
3. Turn on **Test**. Configuration changes will not apply until **Configure** is turned on.
4. Fill in the following fields:
- **Service Provider Issuer URL**: Ensure set to `https://slack.com`.
- **SAML SSO URL**: SSO endpoint from application configuration in Cloudflare One.
- **Identity Provider Issuer**: Access Entity ID or Issuer from application configuration in Cloudflare One.
- **Public Certificate**: Paste the entire x.509 certificate from step [2. Create a x.509 certificate](#2-create-a-x509-certificate).
5. Under **Advanced Options**, select **Expand**.
6. For **AuthnContextClassRef**, ensure _urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport_ is selected.
7. Ensure **Sign the AuthnRequest** is turned off.
8. For **SAML Response Signing**, turn on **Sign the Response** and **Sign the Assertion**.
9. In the main configuration page under **Settings**, choose whether SSO is _required_, _partially required_, or _optional_ for workspace members.
10. (Optional) Under **Customize**, enter a **Sign in Button Label**.
11. Test your set-up. If all works well, turn **Test** to **Configure**.
1. In Slack, go to **Settings & administration** > **Organization settings** > **Security** > **SSO Settings**.
2. For **SSO name**, enter your desired name.
3. Fill in the following fields:
- **SAML 2.0 Endpoint URL**: SSO endpoint from application configuration in Cloudflare One.
- **Identity Provider Issuer URL**: Access Entity ID or Issuer from application configuration in Cloudflare One.
- **Service Provider Issuer URL**: Ensure set to `https://slack.com`.
- **x.509 Certificate**: Paste the entire x.509 certificate from step [2. Create a x.509 certificate](#2-create-a-x509-certificate).
4. For **AuthnContextClassRef**, ensure _urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport_ is selected.
5. Ensure **Sign the AuthnRequest** is turned off.
6. For **SAML Response Signing**, turn on **Sign the Response** and **Sign the Assertion**.
7. Select **Test Configuration**.
8. If all works well, select **Turn on SSO** or **Add SSO**.
# Smartsheet
This guide covers how to configure [Smartsheet](https://help.smartsheet.com/articles/2483123-domain-level-saml-configuration) as a SAML application in Cloudflare One.
## Prerequisites
- An [identity provider](/cloudflare-one/integrations/identity-providers/) configured in Cloudflare One
- Admin access to a Smartsheet Enterprise account
- A [domain](https://help.smartsheet.com/articles/2483051-domain-management) verified in Smartsheet
:::note
In Smartsheet, SSO is configured for a domain. If you have multiple plans using the same domain, the SSO configuration will apply to all Smartsheet users in that domain, regardless of their plan type.
:::
## 1. Add a SaaS application to Cloudflare One
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **Applications**.
2. Select **Create new application** > **SaaS application**.
3. For **Application**, enter `Smartsheet` and select the corresponding textbox that appears.
4. For the authentication protocol, select **SAML**.
5. Select **Add application**.
6. Fill in the following fields:
- **Entity ID**: `urn:amazon:cognito:sp:us-east-1_xww1cbP43`
- **Assertion Consumer Service URL**: `https://saml.authn.smartsheet.com/saml2/idpresponse`
- **Name ID format**: _Unique ID_
7. Copy the **SAML Metadata endpoint**.
8. Configure [Access policies](/cloudflare-one/access-controls/policies/) for the application.
9. Save the application.
## 2. Create and test a SAML SSO provider in Smartsheet
1. In your Smartsheet Admin Center, go to **Settings** > **Authentication** > **Add a SAML IdP**.
2. In **Other IdP (Customize)**, select **Configure**.
3. Select **Next**.
4. Under **XML URL**, paste the SAML Metadata endpoint from application configuration in Cloudflare One.
5. Under **Name SAML IdP**, enter a name (for example, `Cloudflare Access`).
6. Select **Save & Next**.
7. Select **Verify connection** and sign in via Access. If validation is successful, you will see a **SAML IdP Successfully Connected!** message. Close the configuration verification page.
8. Turn on **I have successfully verified the connection**.
9. Select **Save & Next**.
10. Under **Assign domains to SAML IdP**, select your desired domain.
11. Select **Save and Next** and then **Finish**.
# SparkPost
This guide covers how to configure [SparkPost or SparkPost EU](https://support.sparkpost.com/docs/my-account-and-profile/sso) as a SAML application in Cloudflare Zero Trust.
## Prerequisites
- An [identity provider](/cloudflare-one/integrations/identity-providers/) configured in Cloudflare One
- Admin access to a SparkPost or SparkPost EU account
## 1. Add a SaaS application to Cloudflare One
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **Applications**.
2. Select **Create new application** > **SaaS application**.
3. For **Application**, enter `SparkPost` and select the corresponding textbox that appears.
4. For the authentication protocol, select **SAML**.
5. Select **Add application**.
6. Fill in the following fields:
- **Entity ID**:
- `https://api.sparkpost.com` for SparkPost accounts
- `https://api.eu.sparkpost.com` for SparkPost EU accounts
- `https://` for SparkPost accounts with dedicated tenants
- **Assertion Consumer Service URL**:
- `https://api.sparkpost.com/api/v1/users/saml/consume` for SparkPost accounts
- `https://api.eu.sparkpost.com/api/v1/users/saml/consume` for SparkPost EU accounts
- `https:///api/v1/users/saml/consume` for SparkPost accounts with dedicated tenants
- **Name ID format**: _Email_
7. Copy the **SAML Metadata endpoint**.
8. Configure [Access policies](/cloudflare-one/access-controls/policies/) for the application.
9. Save the application.
## 2. Download the metadata file
1. Paste the SAML metadata endpoint from application configuration in Cloudflare One in a web browser.
2. Follow your browser-specific steps to download the URL's contents as an `.xml` file.
## 3. Add a SAML SSO provider to SparkPost
1. In SparkPost, select your profile picture > **Account Settings**.
2. Under **Single Sign-On**, select **Provision SSO**.
3. Under **Upload your Security Assertion Markup Language (SAML)**, select **select a file** and upload the `.xml` file you created in step [2. Download the metadata file](#2-download-the-metadata-file).
4. Select **Provision SSO**.
5. Select **Enable SSO**.
## 4. Add a test user and test the integration
1. In SparkPost, current users must be deleted and re-invited to use SSO. To create a test user, select your profile picture > **Users** > name of the user > **Delete User**. Then, select **Invite User** and fill in the necessary information. Alternatively, invite a new user. An invitation email will be sent.
2. Go to the link sent in the invitation email. You will be redirected to the Cloudflare Access login screen and prompted to sign in with your identity provider.
3. Once SSO is successful, you can turn on SSO for the rest of your current users by deleting and then re-inviting them.
:::note
The SparkPost SSO login link is `https://app.sparkpost.com/auth/sso`. Alternatively, you can go to the usual sign in page and select **Log in with Single Sign-On**.
:::
# Tableau Cloud
This guide covers how to configure [Tableau Cloud](https://help.tableau.com/current/online/en-us/saml_config_site.htm) as a SAML application in Cloudflare One.
## Prerequisites
- An [identity provider](/cloudflare-one/integrations/identity-providers/) configured in Cloudflare One
- Admin access to a Tableau Cloud site
## 1. Add a SaaS application to Cloudflare One
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **Applications**.
2. Select **Create new application** > **SaaS application**.
3. For **Application**, select _Tableau_.
4. For the authentication protocol, select **SAML**.
5. Select **Add application**.
6. Copy the **SAML Metadata endpoint**.
7. Keep this window open. You will finish this configuration in step [4. Finish adding a SaaS application to Cloudflare One](#4-finish-adding-a-saas-application-to-cloudflare-one).
## 2. Download the metadata file
1. Paste the SAML Metadata endpoint from application configuration in Cloudflare One in a web browser.
2. Follow your browser-specific steps to download the URL's contents as an `.xml` file.
## 3. Add a SAML SSO provider to Tableau Cloud
1. In Tableau Cloud, go to **Settings** > **Authentication**.
2. Turn on **Enable an additional authentication method**. For **select authentication type**, select _SAML_.
3. Under **1. Get Tableau Cloud metadata**, copy the **Tableau Cloud entity ID** and **Tableau Cloud ACS URL**.
4. Under **4. Upload metadata to Tableau**, select **Choose a file**, and upload the `.xml` file created in step [2. Download the metadata file](#2-download-the-metadata-file)
5. Under **5. Map attributes**, turn on **Full name**. For **Name (full name)**, enter `name`.
6. (Optional) Choose whether users who are accessing embedded views will **Authenticate in a separate pop-up window** or **Authenticate using an inline frame**.
7. Select **Save Changes**.
## 4. Finish adding a SaaS application to Cloudflare One
1. In your open Cloudflare One window, fill in the following fields:
- **Entity ID**: Tableau Cloud entity ID from Tableau Cloud SAML SSO set-up.
- **Assertion Consumer Service URL**: Tableau Cloud ACS URL from Tableau Cloud SAML SSO set-up.
- **Name ID format**: _Email_
2. Configure [Access policies](/cloudflare-one/access-controls/policies/) for the application.
3. Save the application.
## 5. Test the integration and set default authentication type
1. In Tableau Cloud, go to **Settings** > **Authentication**.
2. Under **7. Test Configuration**, select **Test Configuration**.
3. Sign in. If your sign-in is successful, **You are now signed in as (username)** will appear at the top of the page.
4. Close the pop-up window.
5. (Optional) Under **Default Authentication Type for Embedded Views**, turn on **cloudflareaccess.com (SAML)**. You can also configure the default authentication type for individual users under **Users** > **Actions** > **Authentication**.
# Workday
This guide covers how to configure [Workday](https://doc.workday.com/admin-guide/en-us/authentication-and-security/authentication/saml/dan1370796470811.html?toc=1.5.1) as a SAML application in Cloudflare One.
## Prerequisites
- An [identity provider](/cloudflare-one/integrations/identity-providers/) configured in Cloudflare One
- Admin access to a Workday account
## 1. Add a SaaS application to Cloudflare One
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **Applications**.
2. Select **Create new application** > **SaaS application**.
3. For **Application**, enter `Workday` and select the corresponding textbox that appears.
4. For the authentication protocol, select **SAML**.
5. Select **Add application**.
6. Fill in the following fields:
- **Entity ID**: `http://www.workday.com`
- **Assertion Consumer Service URL**: `https://.myworkday.com//login-saml.flex` for a production account or `https://-impl.myworkday.com//login-saml.flex` for a preview sandbox account
- **Name ID format**: _Email_
7. Copy the **SSO endpoint**, **Access Entity ID or Issuer**, and **Public key**.
8. Configure [Access policies](/cloudflare-one/access-controls/policies/) for the application.
9. Save the application.
## 2. Download the metadata file
1. Paste the SAML Metadata endpoint from application configuration in Cloudflare One in a web browser.
2. Follow your browser-specific steps to download the URL's contents as an `.xml` file.
## 3. Add a SAML SSO provider to Workday
1. In Workday, go to **Account Administration** > **Actions** > **Edit Tenant Setup - Security**.
2. Under **SAML Setup**, turn on **Enable SAML Authentication**.
3. In the **SAML Identity Providers** table, select **+**.
4. Fill in the following fields:
- **Identity Provider Name**: Your desired name for the identity provider (for example, `Cloudflare Access`)
- **Issuer**: Access Entity ID or Issuer from application configuration in Cloudflare One
- **IdP SSO Service URL**: SSO endpoint from application configuration in Cloudflare One
5. Under **x509 Certificate**, select the menu icon > **Create x509 Public Key**.
6. Under **Name**, enter a unique name (for example, `access`).
7. Under **Certificate**, paste the Public key from application configuration in Cloudflare One.
8. Select **OK**.
9. If you want to enable SP-initiated login (login initiated by going to your Workday URL), fill in the following fields:
- **SP Initiated**: Turn on.
- **Service Provider ID**: `http://www.workday.com`
- **Sign SP-initiated request**: Turn off.
10. Under **Single Sign-On**, add one or both of the following entries to the **Redirection URLs** grid. For each entry, if your user groups will use the same authentication option to sign in, select **Single URL**. If they will use different authentication options, select **Authentication selector**.
- IdP-initiated SSO: Under **Login Redirect URL**, enter `.cloudflareaccess.com`.
- SP-initiated SSO: Under **Login Redirect URL**, enter `https:////login.flex?redirect=n`.
:::
1. In Workday, create an [authentication rule](https://doc.workday.com/admin-guide/en-us/authentication-and-security/authentication/authentication-policies/dan1370796466772.html).
2. Under **Authentication Conditions**, add conditions that will apply only to your test user.
3. Under **Allowed Authentication Types**, select **Specific**, then **SAML**.
4. Select **Done**.
5. Complete the following step:
- **If you have enabled SP-initiated login**: Open an incognito browser window, go to your Workday URL, and enter your test user's email. You will be redirected to the Cloudflare Access login screen and prompted to sign in with your identity provider.
- **If you have not enabled SP-initiated login**: Go to your App Launcher at `https://.cloudflareaccess.com`. Select the **Workday** tile. You will be redirected to the Cloudflare Access login screen and prompted to sign in with your identity provider.
6. Once login is successful, you can configure your security settings further, such as adding [user groups](https://doc.workday.com/admin-guide/en-us/authentication-and-security/configurable-security/security-groups/user-based-security-groups/dan1370796695367.html?toc=2.2.12.0) or [authentication rules](https://doc.workday.com/admin-guide/en-us/authentication-and-security/authentication/authentication-policies/dan1370796466772.html) to configure different login rules for different groups of users.
# Zendesk
This guide covers how to configure [Zendesk](https://support.zendesk.com/hc/en-us/articles/4408887505690-Enabling-SAML-single-sign-on#topic_u54_wc3_z2b) as a SAML application in Cloudflare One.
## Prerequisites
- An [identity provider](/cloudflare-one/integrations/identity-providers/) configured in Cloudflare One
- Admin access to your Zendesk account
## Configure Zendesk and Cloudflare
1. Go to your Zendesk administrator dashboard, typically available at `.zendesk.com/admin/security/sso`.
2. In a separate tab or window, open the [Cloudflare dashboard](https://dash.cloudflare.com/), select your account, and go to **Zero Trust** > **Access controls** > **Applications**.
3. Select **Create new application**, then choose **SaaS application**.
4. Input the following values in the Cloudflare One application configuration:
| Cloudflare One field | Value |
| ---------------------------------- | ----------------------------------------------- |
| **Entity ID** | `https://.zendesk.com` |
| **Assertion Consumer Service URL** | contents of **SAML SSO URL** in Zendesk account |
| **Name ID Format** | _Email_ |
5. (Optional) Configure these Attribute Statements to include a user's first and last name:
| Cloudflare attribute name | IdP attribute value |
| ------------------------- | ----------------------------------------------------------------- |
| `` | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname` |
| `` | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname` |
Zendesk will [use the user's email address as their name](https://support.zendesk.com/hc/en-us/articles/203663676#topic_dzb_gl5_2v) if the name is not provided.
6. To determine who can access Zendesk, [create an Access policy](/cloudflare-one/access-controls/policies/).
7. Copy the **SSO Endpoint** and **Public Key**.
8. Transform the public key into a fingerprint:
1. Open a [fingerprint calculator](https://www.samltool.com/fingerprint.php).
2. Paste the **Public Key** into **X.509 cert**.
3. Wrap the value with `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----`.
4. Set **Algorithm** to _SHA256_ and select **Calculate Fingerprint**.
5. Copy the **Formatted FingerPrint** value.
9. Add the Cloudflare values to the following Zendesk fields:
| Cloudflare IdP field | Zendesk field |
| ------------------------------------------- | --------------------------- |
| **SSO Endpoint** | **SAML SSO URL** |
| **Public Key** (transformed to fingerprint) | **Certificate Fingerprint** |
10. Go to `https://.zendesk.com/admin/security/staff_members` and enable **External Authentication** > **Single Sign On**.
Users should now be able to log in to Zendesk if their Email address exists in the Zendesk user list.
# Zoom
This guide covers how to configure [Zoom](https://support.zoom.com/hc/en/article?id=zm_kb&sysparm_article=KB0060673) as a SAML application in Cloudflare One.
## Prerequisites
- An [identity provider](/cloudflare-one/integrations/identity-providers/) configured in Cloudflare One
- Admin access to a Zoom Business, Education, or Enterprise account
- An [associated domain](https://support.zoom.com/hc/en/article?id=zm_kb&sysparm_article=KB0066259) configured in your Zoom account
- A [vanity URL](https://support.zoom.com/hc/en/article?id=zm_kb&sysparm_article=KB0061540) configured in your Zoom account
## 1. Add a SaaS application to Cloudflare One
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **Applications**.
2. Select **Create new application** > **SaaS application**.
3. For **Application**, select _Zoom_.
4. For the authentication protocol, select **SAML**.
5. Select **Add application**.
6. Fill in the following fields:
- **Entity ID**: ` https://.zoom.us`
- **Assertion Consumer Service URL**: `https://.zoom.us/saml/SSO`
- **Name ID format**: _Email_
7. Copy the **Access Entity ID or Issuer**, **Public key**, and **SSO endpoint**.
8. Configure [Access policies](/cloudflare-one/access-controls/policies/) for the application.
9. Save the application.
## 2. Add a SAML SSO provider in Zoom
1. In Zoom, go to **Advanced** > **Single Sign-On**.
2. For **Vanity URL**, select the vanity URL you want to configure SSO for.
3. Fill out the following fields:
- **Sign in page URL**: SSO endpoint from application configuration in Cloudflare One
- **Identity Provider Certificate**: Public key from application configuration in Cloudflare One
- **Service Provider (SP) Entity ID**: `yourvanityurl.zoom.us` (no `https://`)
- **Issuer (DP Entity ID)**: Access Entity ID or Issuer from application configuration in Cloudflare One
4. For **Binding**, select _http-redirect_.
5. For **Signature Hash Algorithm**, ensure **SHA-256** is selected.
6. Under **Security**, turn off **Sign SAML request** and **Sign SAML logout request**.
7. Select **Save Changes**.
8. Go to **Advanced** > **Security**.
9. Under **Sign-in Methods**, ensure **Allow users to sign in with Single Sign-On (SSO)** is turned on.
## 3. Test the integration
Open an incognito browser window, go to your Zoom vanity URL, and select **Sign in**. You will be redirected to the Cloudflare Access login screen and prompted to sign in with your identity provider.
Once this is successful, you can require SSO for users in your associated domain(s) by completing the following steps:
1. In Zoom, go to **Advanced** > **Security**.
2. Under **Sign-in Methods**, turn on **Require users to sign in with SSO if their e-mail address belongs to one of the domains below**.
3. Under **Select Domains**, turn on the domains that you want to require SSO for.
4. (Optional) Under **Specify users who can bypass SSO sign-in**, add your desired users.
5. Select **Save**.
# Browser-rendered terminal
import { Render } from "~/components";
Cloudflare can render SSH, VNC, and RDP applications in a browser without the need for client software or end-user configuration changes. For SSH and VNC, user email prefixes must match their username on the server. RDP leverages your existing Windows usernames and passwords for authenticating to the Windows server; Cloudflare does not manage any credentials on the Windows server.
## Limitations
- Browser rendering is only supported for [self-hosted public applications](/cloudflare-one/access-controls/applications/http-apps/self-hosted-public-app/), not private IPs or hostnames.
- You can only render a browser-rendered terminal on domains and subdomains, not on specific paths.
- - Traffic and DNS mode
- Traffic only mode
| All plans |
| System | Availability |
| -------- | ------------ |
| Windows | ✅ |
| macOS | ✅ |
| Linux | ✅ |
| iOS | ✅ |
| Android | ✅ |
| ChromeOS | ✅ |
Access for Infrastructure gives you granular control over how users access individual servers, clusters, or databases. You can configure how users authenticate to the resource and control the ports, protocols, and usernames they can use.
You can also organize targets with tags and define applications that match targets by hostname, tag, or both. Access logs and command logs help you audit access and support compliance workflows.
:::note
Access for Infrastructure currently supports [SSH](/cloudflare-one/networks/connectors/cloudflare-tunnel/use-cases/ssh/ssh-infrastructure-access/). To connect using other protocols, [add a self-hosted private application](/cloudflare-one/access-controls/applications/non-http/self-hosted-private-app/). For browser-based SSH, RDP, or VNC, refer to [browser-rendered terminal](/cloudflare-one/access-controls/applications/non-http/browser-rendering/).
:::
## Prerequisites
- [Connect your infrastructure](/cloudflare-one/networks/connectors/cloudflare-tunnel/private-net/) to Cloudflare using `cloudflared` or Cloudflare Mesh.
- [Deploy the Cloudflare One Client](/cloudflare-one/team-and-resources/devices/cloudflare-one-client/deployment/) on user devices in Traffic and DNS mode.
## 1. Add a target
In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **Targets**. Use the filter and sort controls to narrow the list by tag key or value.
To filter targets by tag, add one or more `tag` query parameters:
```bash
curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/infrastructure/targets?tag=environment:production&tag=team:platform" \
-H "Authorization: Bearer $API_TOKEN"
```
Use `:` between the tag key and value in each filter. If you add multiple `tag` parameters, Cloudflare applies AND logic.
To sort by tag key, use the `order` and `direction` parameters:
```bash
curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/infrastructure/targets?order=tag:environment&direction=asc" \
-H "Authorization: Bearer $API_TOKEN"
```
The sort parameter also uses `:` in `order=tag:` because it identifies the tag field to sort by.
## 2. Add an infrastructure application
initial resolved IP . Ensure that the following IP addresses are not blocked by any firewalls or excluded from Gateway traffic:
-
Select the [identity providers](/cloudflare-one/integrations/identity-providers/) you want to enable for your application.
-
(Recommended) If you plan to only allow access via a single IdP, turn on **Apply instant authentication**. End users will not be shown the [Cloudflare Access login page](/cloudflare-one/reusable-components/custom-pages/access-login-page/). Instead, Cloudflare will redirect users directly to your SSO login event.
- (Recommended) Turn on Authenticate with Cloudflare One Client to allow users to authenticate to the application using their Cloudflare One Client session identity. Turn this on if your application is not in the browser and cannot handle a
302 redirect.
8. .cloudflareaccess.com/browser/https://wiki.internal.local/`. The link will route traffic to the application through [Clientless Web Isolation](/cloudflare-one/remote-browser-isolation/setup/clientless-browser-isolation/). This setting is useful for users on unmanaged devices or contractors who cannot install a device client.
:::note
Ensure your [remote browser permissions](/cloudflare-one/remote-browser-isolation/setup/clientless-browser-isolation/) allow users of this application to open Clientless Web Isolation links.
:::
-
-
In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Traffic policies** > **Firewall policies**. In **Network**, [create a Network policy](/cloudflare-one/traffic-controls/network-policies/) with the following configuration:
| Selector | Operator | Value | Action |
| ------------------------------------------- | -------- | --------- | ------ |
| Self-hosted Access App with Private Address | is | _Present_ | Allow |
-
Update the policy's [order of
precedence](/cloudflare-one/traffic-controls/order-of-enforcement/#order-of-precedence)
using the dashboard or API.
:::note
Users must pass the policies in your Access application before they are granted access. The Gateway Allow policy is strictly for routing and connectivity purposes.
:::
### Private hostname vs private IP
An Access application defined by a private hostname takes precedence over an Access application defined by a private IP. For example, assume App-1 points to `wiki.internal.local` and App-2 points to `10.0.0.1`, but `wiki.internal.local` resolves to `10.0.0.1`. Users who go to `wiki.internal.local` will never match App-2; they will be allowed or blocked strictly based on App-1 Access policies (and [Gateway policies](#access-vs-gateway-policies)).
### Overlapping private application destinations
When a request matches destinations in multiple self-hosted private applications, Access selects the application with the most specific matching destination. The application creation order and the order shown in the dashboard do not affect which application is selected.
Access compares destination attributes in the following order:
1. **Hostname or IP specificity:** A matching private hostname takes precedence over any private IP or CIDR. Between matching hostnames, a hostname with more labels takes precedence. For hostnames with the same number of labels, exact labels take precedence over wildcard labels, and partial wildcards take precedence over a full `*` label. Between matching IPs and CIDRs, the destination with fewer IP addresses takes precedence. An exact IPv4 or IPv6 address is the most specific IP destination.
2. **Port specificity:** For otherwise equal destinations, a single port takes precedence over a port range. A smaller port range takes precedence over a larger range, and any port restriction takes precedence over a destination that applies to all ports.
3. **Virtual network specificity:** A destination restricted to a virtual network takes precedence over an otherwise equal destination that applies to all virtual networks. For example, assume App-1 matches `10.0.0.0/24` on all virtual networks and App-2 matches the same CIDR only on the `staging` virtual network. A user connected to `staging` matches App-2, while a user connected to a different virtual network matches App-1.
4. **Protocol specificity:** A destination restricted to TCP or UDP takes precedence over an otherwise equal destination that applies to both protocols.
Destination specificity is evaluated before port specificity. For example, `10.0.1.0/24` on all ports takes precedence over `10.0.0.0/16` on a single port. Access evaluates policies only for the application selected by this matching order.
:::note
This matching order applies to destinations configured on **Self-hosted and private** applications. It does not apply to [legacy private network applications](/cloudflare-one/access-controls/applications/non-http/legacy-private-network-app/).
:::
## Limitations
### Browser Isolation is not compatible with apps on non-`443` ports
`beta.example.com` | `example.com`
`foo.bar.example.com` |
#### Match all paths of an apex domain
To protect an apex domain and all of the paths under it, leave the **Path** field empty. Alternatively, use a wildcard in the **Path** field.
| Application | Covers | Does not cover |
| -------------------------------------- | ---------------------------------------------------------------- | ------------------- |
| `example.com`
or `example.com/*` | `example.com`
`example.com/alpha`
`example.com/beta` | `alpha.example.com` |
#### Match multi-level subdomains
Using a wildcard in the **Subdomain** field does not cover the parent subdomain nor the apex domain.
| Application | Covers | Does not cover |
| -------------------- | ------------------------------------------------------ | --------------------------------------- |
| `*.test.example.com` | `alpha.test.example.com`
`beta.test.example.com` | `test.example.com`
`example.com` |
#### Partially match subdomains
Using a wildcard at the beginning or end of the **Subdomain** field does not cover multiple levels of the subdomain.
| Application | Covers | Does not cover |
| ------------------- | ------------------------------------------------ | ----------------------- |
| `*test.example.com` | `test.example.com`
`alphatest.example.com` | `beta.test.example.com` |
#### Match multi-level paths
Using a wildcard in the **Path** field does not cover the parent path nor the apex domain.
| Application | Covers | Does not cover |
| --------------------- | ----------------------------------------------------- | --------------------------------------- |
| `example.com/alpha/*` | `example.com/alpha/one`
`example.com/alpha/two` | `example.com/alpha`
`example.com` |
#### Partially match paths
Using a wildcard in the middle of the **Path** field covers multiple segments of the URL.
| Application | Covers |
| ---------------------- | ------------------------------------------------------------------------------------ |
| `example.com/foo*/bar` | `example.com/foo/bar`
`example.com/food/bar`
`example.com/food/stuff/bar` |
### Limitations
* At most one wildcard in between each dot in the **Subdomain**. For example, `foo*bar*baz.example.com` is not allowed.
* At most one wildcard in between each slash in the **Path**. For example, `example.com/foo*bar*baz` is not allowed.
## Subdomain setups
[Subdomain setups](/dns/zone-setups/subdomain-setup/) allow you to manage a child domain separately from its parent domain. In Access application paths, your configured child domains will appear in the **Domain** dropdown menu. If you [split out a subdomain](/dns/zone-setups/subdomain-setup/setup/) which already has an Access application, you will need to re-save the Access application to associate it with the new child domain.
## Unsupported URLs
### Port numbers
Port numbers are not supported in Access application paths. If a request includes a port number in the URL, Access will strip the port number and redirect the request to the default HTTP/HTTPS port.
### Query strings
Query strings (such as`?foo=bar`) are not supported in Access application paths.
### Anchor links
Since anchor links are processed by the browser and not the server, Access applications do not support `#` characters in the URL. For example, requests to `dashboard.com/#settings` will redirect to `dashboard.com`.
# Common policies
import { Details, Render, Tabs, TabItem, APIRequest } from "~/components";
The following Cloudflare Access policies are commonly used to secure applications.
Refer to the [Access policies page](/cloudflare-one/access-controls/policies/) for a comprehensive list of available actions, rule types, and selectors. To learn how to create and manage policies, refer to [Manage Access policies](/cloudflare-one/access-controls/policies/policy-management/).
## Allow employees by email domain
The most basic Access policy grants access to anyone who authenticates with an email address belonging to your organization. This is a good starting point when you first protect an application with Access and want to restrict it to employees using your corporate [identity provider](/cloudflare-one/integrations/identity-providers/).
At least one of the following [token permissions](/fundamentals/api/reference/permissions/) is required:
- `Access: Apps and Policies Write`
Configure the [`cloudflare_zero_trust_access_policy`](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/zero_trust_access_policy) resource:
```tf
resource "cloudflare_zero_trust_access_policy" "allow_employees_by_email_domain" {
account_id = var.cloudflare_account_id
name = "Allow employees by email domain"
decision = "allow"
include = [{
email_domain = {
domain = "example.com"
}
}]
}
```
You can add multiple email domains to the Include rule if your organization uses more than one domain (for example, `@example.com` and `@example.co.uk`).
## Allow employees from specific countries
Organizations that operate in specific regions or need to comply with data residency requirements can restrict application access to users in approved countries. This policy is useful when you want to limit where employees can connect from, while still allowing exceptions for individual users such as traveling executives.
Because Require rules use AND logic, you cannot add multiple countries directly to a single Require rule — that would require the user to be in all countries simultaneously. Instead, first create a [rule group](/cloudflare-one/access-controls/policies/groups/) that lists the approved countries:
| Rule type | Selector | Value |
| --------- | -------- | --------------------------- |
| Include | Country | `United States`, `Portugal` |
At least one of the following [token permissions](/fundamentals/api/reference/permissions/) is required:
- `Access: Apps and Policies Write`
Configure the [`cloudflare_zero_trust_access_group`](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/zero_trust_access_group) resource:
```tf
resource "cloudflare_zero_trust_access_group" "approved_countries" {
account_id = var.cloudflare_account_id
name = "Approved countries"
include = [
{
geo = {
country_code = "US"
}
},
{
geo = {
country_code = "PT"
}
},
]
}
```
Then reference the rule group in your Access policy:
| Action | Rule type | Selector | Value |
| ------ | --------- | ---------------- | ------------------------------------------ |
| Allow | Include | Emails ending in | `@example.com` |
| | Require | Rule group | `Approved countries` |
| | Exclude | Email | `user-1@example.com`, `user-2@example.com` |
",
},
},
],
exclude: [
{
email: {
email: "user-1@example.com",
},
},
{
email: {
email: "user-2@example.com",
},
},
],
}}
/>
Replace `` with the `id` returned when you created the rule group above. To look up existing groups, use the [List Access groups](/api/resources/zero_trust/subresources/access/subresources/groups/methods/list/) endpoint.
At least one of the following [token permissions](/fundamentals/api/reference/permissions/) is required:
- `Access: Apps and Policies Write`
Configure the [`cloudflare_zero_trust_access_policy`](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/zero_trust_access_policy) resource:
```tf
resource "cloudflare_zero_trust_access_policy" "allow_employees_from_specific_countries" {
account_id = var.cloudflare_account_id
name = "Allow employees from specific countries"
decision = "allow"
include = [{
email_domain = {
domain = "example.com"
}
}]
require = [{
group = {
id = cloudflare_zero_trust_access_group.approved_countries.id
}
}]
exclude = [
{
email = {
email = "user-1@example.com"
}
},
{
email = {
email = "user-2@example.com"
}
},
]
}
```
The `cloudflare_zero_trust_access_group.approved_countries` reference points to the [`cloudflare_zero_trust_access_group`](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/zero_trust_access_group) resource created above.
## Require device posture for sensitive applications
For applications that contain sensitive data, you can verify that users connect from managed devices that meet your organization's security baseline. The following example combines identity verification with [device posture checks](/cloudflare-one/reusable-components/posture-checks/) to ensure that the device is running a supported [OS version](/cloudflare-one/reusable-components/posture-checks/client-checks/os-version/) and is connected through the [Cloudflare One Client](/cloudflare-one/team-and-resources/devices/cloudflare-one-client/), which is enforced by the [Require Gateway check](/cloudflare-one/reusable-components/posture-checks/client-checks/require-gateway/).
:::note
Before creating this policy, [create device posture checks](/cloudflare-one/reusable-components/posture-checks/) for each requirement and [enable the Require Gateway posture check](/cloudflare-one/reusable-components/posture-checks/client-checks/require-gateway/).
:::
| Action | Rule type | Selector | Value |
| ------ | --------- | -------------- | -------------------------------------------------------- |
| Allow | Include | Okta Groups | `Full-Time Employees` |
| | Require | Gateway | `Gateway` |
| | Require | OS Version | `Latest version of Windows` |
",
},
},
],
require: [
{
device_posture: {
integration_uid: "",
},
},
{
device_posture: {
integration_uid: "",
},
},
],
}}
/>
Replace the `okta` rule with the [appropriate rule for your identity provider](/api/resources/zero_trust/subresources/access/subresources/policies/methods/create/). To get your identity provider ID, use the [List Access identity providers](/api/resources/zero_trust/subresources/access/subresources/identity_providers/methods/list/) endpoint. To get the integration UIDs for your device posture checks, use the [List device posture checks](/api/resources/zero_trust/subresources/devices/subresources/posture/methods/list/) endpoint.
At least one of the following [token permissions](/fundamentals/api/reference/permissions/) is required:
- `Access: Apps and Policies Write`
Configure the [`cloudflare_zero_trust_access_policy`](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/zero_trust_access_policy) resource:
```tf
resource "cloudflare_zero_trust_access_policy" "require_device_posture" {
account_id = var.cloudflare_account_id
name = "Require device posture for sensitive apps"
decision = "allow"
include = [{
okta = {
name = "Full-Time Employees"
identity_provider_id = cloudflare_zero_trust_access_identity_provider.okta.id
}
}]
require = [
{
device_posture = {
integration_uid = cloudflare_zero_trust_device_posture_rule.gateway_check.id
}
},
{
device_posture = {
integration_uid = cloudflare_zero_trust_device_posture_rule.os_version_check.id
}
},
]
}
```
- Replace the `okta` rule with the appropriate [`cloudflare_zero_trust_access_identity_provider`](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/zero_trust_access_identity_provider) resource for your identity provider. To configure the identity provider resource, refer to [Identity providers](/cloudflare-one/integrations/identity-providers/).
- To configure the [`cloudflare_zero_trust_device_posture_rule`](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/zero_trust_device_posture_rule) resources referenced above, refer to [Device posture checks](/cloudflare-one/reusable-components/posture-checks/).
To reuse these device requirements across multiple applications, create a [rule group](/cloudflare-one/access-controls/policies/groups/) called "Corporate device requirements" that contains the posture checks. You can then reference this rule group in the Require field of any policy.
## Require MFA for high-security applications
For applications that handle financial data, production infrastructure, or other high-value resources, you can require that users authenticate with multi-factor authentication (MFA) in addition to their identity provider credentials. This ensures that a compromised password alone is not sufficient to gain access.
Access supports two approaches to enforcing MFA:
### Identity provider-based MFA
If your identity provider reports the authentication method used during login, you can add an **Authentication method** selector to require a specific MFA method such as a hardware security key.
| Action | Rule type | Selector | Value |
| ------ | --------- | --------------------- | -------------- |
| Allow | Include | Okta Groups | `Employees` |
| | Require | Authentication method | `Security key` |
| | Require | Gateway | _(enabled)_ |
",
},
},
],
require: [
{
auth_method: {
auth_method: "swk",
},
},
{
device_posture: {
integration_uid: "",
},
},
],
}}
/>
The `auth_method` value uses [RFC 8176](https://datatracker.ietf.org/doc/html/rfc8176#section-2) authentication method reference values. For example, `swk` represents a software-secured key (security key). Replace the `okta` rule with the [appropriate rule for your identity provider](/api/resources/zero_trust/subresources/access/subresources/policies/methods/create/). To get your identity provider ID, use the [List Access identity providers](/api/resources/zero_trust/subresources/access/subresources/identity_providers/methods/list/) endpoint. To get ``, use the [List device posture checks](/api/resources/zero_trust/subresources/devices/subresources/posture/methods/list/) endpoint.
At least one of the following [token permissions](/fundamentals/api/reference/permissions/) is required:
- `Access: Apps and Policies Write`
Configure the [`cloudflare_zero_trust_access_policy`](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/zero_trust_access_policy) resource:
```tf
resource "cloudflare_zero_trust_access_policy" "require_mfa" {
account_id = var.cloudflare_account_id
name = "Require MFA for high-security apps"
decision = "allow"
include = [{
okta = {
name = "Employees"
identity_provider_id = cloudflare_zero_trust_access_identity_provider.okta.id
}
}]
require = [
{
auth_method = {
auth_method = "swk"
}
},
{
device_posture = {
integration_uid = cloudflare_zero_trust_device_posture_rule.gateway_check.id
}
},
]
}
```
The `auth_method` value uses [RFC 8176](https://datatracker.ietf.org/doc/html/rfc8176#section-2) authentication method reference values. For example, `swk` represents a software-secured key (security key).
- Replace the `okta` rule with the appropriate [`cloudflare_zero_trust_access_identity_provider`](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/zero_trust_access_identity_provider) resource for your identity provider. To configure the identity provider resource, refer to [Identity providers](/cloudflare-one/integrations/identity-providers/).
- To configure the [`cloudflare_zero_trust_device_posture_rule`](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/zero_trust_device_posture_rule) resource referenced above, refer to [Device posture checks](/cloudflare-one/reusable-components/posture-checks/).
### Independent MFA
If you want to enforce MFA directly in Access without relying on your IdP, you can use [independent MFA](/cloudflare-one/access-controls/access-settings/independent-mfa/). Independent MFA is not configured through policy selectors. Instead, you first [turn on independent MFA](/cloudflare-one/access-controls/access-settings/independent-mfa/#turn-on-independent-mfa) at the organization level, then enable it for specific applications or policies through a settings panel. Access will prompt users for a second factor (such as a security key, authenticator app, or biometrics) after they authenticate with your IdP.
For the full details on both approaches, refer to [Enforce MFA](/cloudflare-one/access-controls/policies/mfa-requirements/).
## Allow contractor access with email-based authentication
When you collaborate with external contractors or partners who are not part of your corporate identity provider, you can grant them access using a [one-time PIN (OTP)](/cloudflare-one/integrations/identity-providers/one-time-pin/). OTP sends a short-lived code to the contractor's email address, allowing them to authenticate without needing an account in your IdP.
:::note
Before creating this policy, [enable OTP as a login method](/cloudflare-one/integrations/identity-providers/one-time-pin/#set-up-otp) in your identity provider settings.
:::
| Action | Rule type | Selector | Value |
| ------ | --------- | ---------------- | ---------------------------------------- |
| Allow | Include | Emails ending in | `@contractor-a.com`, `@contractor-b.com` |
| | Require | Login methods | `One-time PIN` |
",
},
},
],
}}
/>
To get the ID of your OTP identity provider, use the [List Access identity providers](/api/resources/zero_trust/subresources/access/subresources/identity_providers/methods/list/) endpoint.
At least one of the following [token permissions](/fundamentals/api/reference/permissions/) is required:
- `Access: Apps and Policies Write`
Configure the [`cloudflare_zero_trust_access_policy`](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/zero_trust_access_policy) resource:
```tf
resource "cloudflare_zero_trust_access_policy" "allow_contractor_access_with_otp" {
account_id = var.cloudflare_account_id
name = "Allow contractor access with OTP"
decision = "allow"
include = [
{
email_domain = {
domain = "contractor-a.com"
}
},
{
email_domain = {
domain = "contractor-b.com"
}
},
]
require = [{
login_method = {
id = cloudflare_zero_trust_access_identity_provider.otp.id
}
}]
}
```
To configure the [`cloudflare_zero_trust_access_identity_provider`](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/zero_trust_access_identity_provider) resource for OTP (configured with `type = "onetimepin"`), refer to [One-time PIN](/cloudflare-one/integrations/identity-providers/one-time-pin/).
:::caution
Adding `Login Methods: One-time PIN` as an Include rule without restricting email domains allows anyone with any email address to receive a code and access the application. Always pair OTP with specific email domains or an email list in the Include rule.
:::
## Isolate contractor access to internal applications
When contractors or other external users need to view internal applications but should not be able to download, copy, or transfer data to their unmanaged devices, you can serve the application in a [remote browser](/cloudflare-one/remote-browser-isolation/). This gives external users read-only visibility into the application while keeping sensitive data from leaving your environment.
:::note
Before creating this policy, you must turn on [Clientless Web Isolation](/cloudflare-one/remote-browser-isolation/setup/clientless-browser-isolation/).
:::
| Action | Rule type | Selector | Value |
| ------ | --------- | ---------------- | ---------------------------------------- |
| Allow | Include | Emails ending in | `@contractor-a.com`, `@contractor-b.com` |
**Additional settings**: Turn on **Isolate application**.
First, enable Clientless Web Isolation on your account if you have not already:
First, configure the [`cloudflare_zero_trust_gateway_settings`](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/zero_trust_gateway_settings) resource to enable Clientless Web Isolation on your account if you have not already:
At least one of the following [token permissions](/fundamentals/api/reference/permissions/) is required:
- `Zero Trust Write`
```tf
resource "cloudflare_zero_trust_gateway_settings" "gateway_settings" {
account_id = var.cloudflare_account_id
settings = {
browser_isolation = {
url_browser_isolation_enabled = true
}
}
}
```
Then, configure the [`cloudflare_zero_trust_access_policy`](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/zero_trust_access_policy) resource with `isolation_required` set to `true`:
At least one of the following [token permissions](/fundamentals/api/reference/permissions/) is required:
- `Access: Apps and Policies Write`
```tf
resource "cloudflare_zero_trust_access_policy" "isolate_contractor_access" {
account_id = var.cloudflare_account_id
name = "Isolate contractor access"
decision = "allow"
isolation_required = true
include = [
{
email_domain = {
domain = "contractor-a.com"
}
},
{
email_domain = {
domain = "contractor-b.com"
}
},
]
}
```
To restrict what users can do inside the isolated session, create a companion [Gateway HTTP policy](/cloudflare-one/traffic-controls/http-policies/) that matches traffic to the application domain. Set the action to **Isolate** and disable interactive controls in the [policy settings](/cloudflare-one/remote-browser-isolation/isolation-policies/#policy-settings).
| Selector | Operator | Value | Action |
| -------- | -------- | ------------------ | ------- |
| Domain | in | `wiki.example.com` | Isolate |
**Policy settings**:
| Setting | Value |
| -------------- | ------------ |
| Copy | Do not allow |
| Paste | Do not allow |
| Keyboard | Do not allow |
| File downloads | Do not allow |
| File uploads | Do not allow |
| Printing | Do not allow |
For more information, refer to [Isolate self-hosted application](/cloudflare-one/access-controls/policies/isolate-application/).
## Block requests from high-risk countries
If your organization restricts access from certain countries due to internal policy or regulatory requirements such as [OFAC sanctions](https://orpa.princeton.edu/export-controls/sanctioned-countries) or [ITAR regulations](https://www.tradecompliance.pitt.edu/embargoed-and-sanctioned-countries), you can create a Block policy that denies access from those regions. Adding a corporate IP allowlist as an Exclude rule ensures that employees connecting through trusted office networks are not inadvertently blocked.
:::note
Before creating this policy, [create a list](/cloudflare-one/reusable-components/lists/) with your approved IP ranges.
:::
",
},
},
],
}}
/>
To get the ID of your IP list, use the [List Zero Trust lists](/api/resources/zero_trust/subresources/gateway/subresources/lists/methods/list/) endpoint.
At least one of the following [token permissions](/fundamentals/api/reference/permissions/) is required:
- `Access: Apps and Policies Write`
Configure the [`cloudflare_zero_trust_access_policy`](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/zero_trust_access_policy) resource:
```tf
resource "cloudflare_zero_trust_access_policy" "block_high_risk_countries" {
account_id = var.cloudflare_account_id
name = "Block requests from high-risk countries"
decision = "deny"
include = [{
geo = {
country_code = "RU"
}
}]
exclude = [{
ip_list = {
id = cloudflare_zero_trust_list.corporate_ip_allowlist.id
}
}]
}
```
To configure the [`cloudflare_zero_trust_list`](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/zero_trust_list) resource referenced above (configured with `type = "IP"`), refer to [Lists](/cloudflare-one/reusable-components/lists/).
Block policies are best used together with [Allow policies](#allow-employees-by-email-domain) to carve out exceptions. Because Access denies all requests by default, users who do not match a Block policy are still denied unless they match an Allow policy.
## Exclude high-risk users
If your organization uses [Cloudflare User Risk Scores](/cloudflare-one/team-and-resources/users/risk-score/) to flag users with anomalous behavior, you can exclude high-risk users from accessing sensitive applications. This is useful as a dynamic safeguard that automatically restricts access when a user's behavior triggers a risk level change, without requiring manual intervention.
At least one of the following [token permissions](/fundamentals/api/reference/permissions/) is required:
- `Access: Apps and Policies Write`
Configure the [`cloudflare_zero_trust_access_policy`](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/zero_trust_access_policy) resource:
```tf
resource "cloudflare_zero_trust_access_policy" "exclude_high_risk_users" {
account_id = var.cloudflare_account_id
name = "Exclude high-risk users"
decision = "allow"
include = [{
email_domain = {
domain = "example.com"
}
}]
exclude = [{
user_risk_score = {
user_risk_score = ["high"]
}
}]
}
```
In this example, any user scored as high risk is excluded even if they match the Include rule. To learn how risk scores are calculated and how to configure risk behaviors, refer to [User risk score](/cloudflare-one/team-and-resources/users/risk-score/).
## Authenticate a service using a service token
Automated services such as CI/CD pipelines, monitoring systems, and backend APIs need to access protected applications without an interactive login. Service Auth policies allow machine-to-machine communication by authenticating requests that present valid [service token](/cloudflare-one/access-controls/service-credentials/service-tokens/) headers. For additional security, you can restrict the token to requests from specific IP ranges, ensuring the token can only be used from known infrastructure.
:::note
Before creating this policy, [create a service token](/cloudflare-one/access-controls/service-credentials/service-tokens/#create-a-service-token).
:::
| Action | Rule type | Selector | Value |
| ------------ | --------- | ------------- | ------------------ |
| Service Auth | Include | Service Token | `My service token` |
| | Require | IP ranges | `192.0.2.0/24` |
",
},
},
],
require: [
{
ip: {
ip: "192.0.2.0/24",
},
},
],
}}
/>
To get the ID of your service token, use the [List service tokens](/api/resources/zero_trust/subresources/access/subresources/service_tokens/methods/list/) endpoint.
At least one of the following [token permissions](/fundamentals/api/reference/permissions/) is required:
- `Access: Apps and Policies Write`
Configure the [`cloudflare_zero_trust_access_policy`](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/zero_trust_access_policy) resource:
```tf
resource "cloudflare_zero_trust_access_policy" "authenticate_service_with_token" {
account_id = var.cloudflare_account_id
name = "Authenticate service with service token"
decision = "non_identity"
include = [{
service_token = {
token_id = cloudflare_zero_trust_access_service_token.my_service_token.id
}
}]
require = [{
ip = {
ip = "192.0.2.0/24"
}
}]
}
```
To configure the [`cloudflare_zero_trust_access_service_token`](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/zero_trust_access_service_token) resource referenced above, refer to [Service tokens](/cloudflare-one/access-controls/service-credentials/service-tokens/).
## Authenticate a service using mutual TLS
For environments that require certificate-based authentication, you can use [mutual TLS (mTLS)](/cloudflare-one/access-controls/service-credentials/mutual-tls-authentication/) to verify that a connecting client presents a valid certificate with an expected identity. mTLS is useful for authenticating automated systems and IoT devices that do not use an identity provider, or as an additional authentication factor for team members who also log in through an IdP.
:::note
Before creating this policy, [upload a certificate authority (CA)](/cloudflare-one/access-controls/service-credentials/mutual-tls-authentication/#add-mtls-authentication-to-your-access-configuration) to your Access configuration.
:::
To restrict access to a specific client, use the **Common Name** selector to match the identity in the client certificate:
At least one of the following [token permissions](/fundamentals/api/reference/permissions/) is required:
- `Access: Apps and Policies Write`
Configure the [`cloudflare_zero_trust_access_policy`](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/zero_trust_access_policy) resource:
```tf
resource "cloudflare_zero_trust_access_policy" "authenticate_service_with_mtls" {
account_id = var.cloudflare_account_id
name = "Authenticate service with mTLS"
decision = "non_identity"
include = [{
common_name = {
common_name = "John Doe"
}
}]
}
```
To allow any client presenting a valid certificate signed by your CA, use the **Valid Certificate** selector. This selector is useful when you trust all certificates issued by your CA and do not need to check a specific Common Name.
| Action | Rule type | Selector |
| ------------ | --------- | ----------------- |
| Service Auth | Include | Valid Certificate |
At least one of the following [token permissions](/fundamentals/api/reference/permissions/) is required:
- `Access: Apps and Policies Write`
Configure the [`cloudflare_zero_trust_access_policy`](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/zero_trust_access_policy) resource:
```tf
resource "cloudflare_zero_trust_access_policy" "authenticate_service_with_valid_certificate" {
account_id = var.cloudflare_account_id
name = "Authenticate service with valid certificate"
decision = "non_identity"
include = [{
certificate = {}
}]
}
```
## Require purpose justification for sensitive applications
For applications such as database admin tools, production consoles, or HR systems, you can require users to provide a written reason each time they access the application. This creates an audit trail that helps security teams understand why access was requested. The justification prompt appears after the user authenticates and before they reach the application. For more information, refer to [Require purpose justification](/cloudflare-one/access-controls/policies/require-purpose-justification/).
| Action | Rule type | Selector | Value |
| ------ | --------- | -------------- | ----------------------------------------------------- |
| Allow | Include | Okta Groups | `IT Administrators` |
| | Require | Gateway | `Gateway` |
| | Require | OS Version | `Latest version of Windows` |
**Additional settings**: Turn on **Purpose justification**.
",
},
},
],
require: [
{
device_posture: {
integration_uid: "",
},
},
{
device_posture: {
integration_uid: "",
},
},
],
purpose_justification_required: true,
purpose_justification_prompt: "Please enter a justification for accessing this application.",
}}
/>
Replace the `okta` rule with the [appropriate rule for your identity provider](/api/resources/zero_trust/subresources/access/subresources/policies/methods/create/). To get your identity provider ID, use the [List Access identity providers](/api/resources/zero_trust/subresources/access/subresources/identity_providers/methods/list/) endpoint. To get the integration UIDs for your device posture checks, use the [List device posture checks](/api/resources/zero_trust/subresources/devices/subresources/posture/methods/list/) endpoint.
At least one of the following [token permissions](/fundamentals/api/reference/permissions/) is required:
- `Access: Apps and Policies Write`
Configure the [`cloudflare_zero_trust_access_policy`](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/zero_trust_access_policy) resource:
```tf
resource "cloudflare_zero_trust_access_policy" "require_purpose_justification" {
account_id = var.cloudflare_account_id
name = "Require purpose justification for sensitive apps"
decision = "allow"
purpose_justification_required = true
purpose_justification_prompt = "Please enter a justification for accessing this application."
include = [{
okta = {
name = "IT Administrators"
identity_provider_id = cloudflare_zero_trust_access_identity_provider.okta.id
}
}]
require = [
{
device_posture = {
integration_uid = cloudflare_zero_trust_device_posture_rule.gateway_check.id
}
},
{
device_posture = {
integration_uid = cloudflare_zero_trust_device_posture_rule.windows_version.id
}
},
]
}
```
- Replace the `okta` rule with the appropriate [`cloudflare_zero_trust_access_identity_provider`](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/zero_trust_access_identity_provider) resource for your identity provider. To configure the identity provider resource, refer to [Identity providers](/cloudflare-one/integrations/identity-providers/).
- To configure the [`cloudflare_zero_trust_device_posture_rule`](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/zero_trust_device_posture_rule) resources referenced above, refer to [Device posture checks](/cloudflare-one/reusable-components/posture-checks/).
You can combine purpose justification with [temporary authentication](/cloudflare-one/access-controls/policies/temporary-auth/) to additionally require approval from a designated reviewer before granting access.
## Bypass a public endpoint
Some applications have endpoints that must be publicly reachable, such as OAuth callback URLs, webhook receivers, or health check paths. You can create a Bypass policy scoped to a specific [application path](/cloudflare-one/access-controls/policies/app-paths/) to disable Access enforcement for that endpoint only. For example, if your application is `app.example.com`, you could create a separate Access application for `app.example.com/oauth/callback` and apply the following Bypass policy:
At least one of the following [token permissions](/fundamentals/api/reference/permissions/) is required:
- `Access: Apps and Policies Write`
Configure the [`cloudflare_zero_trust_access_policy`](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/zero_trust_access_policy) resource:
```tf
resource "cloudflare_zero_trust_access_policy" "bypass_public_endpoint" {
account_id = var.cloudflare_account_id
name = "Bypass public endpoint"
decision = "bypass"
include = [{
everyone = {}
}]
}
```
:::caution
Bypass disables all Access security controls and request logging for matching traffic. Scope Bypass policies as narrowly as possible and never use them as a persistent access mechanism for users or services. If you need to allow automated traffic while maintaining authentication and logging, use a [Service Auth](#authenticate-a-service-using-a-service-token) policy instead.
:::
# External Evaluation rules
import { GlossaryTooltip, Example, WranglerConfig, DashButton } from "~/components";
With Cloudflare Access, you can create Allow or Block policies which evaluate the user based on custom criteria. This is done by adding an **External Evaluation** rule to your policy. The **External Evaluation** selector requires two values:
- **Evaluate URL** — the API endpoint containing your business logic.
- **Keys URL** — the key that Access uses to verify that the response came from your API
After the user authenticates with your identity provider, Access sends the user's identity to the external API at **Evaluate URL**. The external API returns a True or False response to Access, which will then allow or deny access to the user. To protect against man-in-the-middle attacks, Access signs all requests with your Access account key and checks that responses are signed by the key at **Keys URL**.
You can set up External Evaluation rules using any API service, but to get started quickly we recommend using [Cloudflare Workers](/workers/).
## Set up external API and key with Cloudflare Workers
### Prerequisites
- [Workers account](/workers/get-started/guide/)
- Install [npm](https://docs.npmjs.com/getting-started)
- Install [Node.js](https://nodejs.org/en/)
- Application protected by Access
### 1. Create a new Worker
1. Open a terminal and clone our example project.
```sh
npm create cloudflare@latest my-worker -- --template https://github.com/cloudflare/workers-access-external-auth-example
```
2. Go to the project directory.
```sh
cd my-worker
```
3. Create a [Workers KV namespace](/kv/concepts/kv-namespaces/) to store the key. The binding name should be `KV` if you want to run the example as written.
```sh
npx wrangler kv namespace create "KV"
```
The command will output the binding name and KV namespace ID, for example
```txt
[[kv_namespaces]]
binding = "KV"
id = "YOUR_KV_NAMESPACE_ID"
```
4. Open the [Wrangler configuration file](/workers/wrangler/configuration/) in an editor and insert the following:
- `[[kv_namespaces]]`: Add the output generated in the previous step.
- ``: your Cloudflare One team name .
```jsonc
{
"$schema": "./node_modules/wrangler/config-schema.json",
"name": "my-worker",
"workers_dev": true,
"compatibility_date": "$today",
"main": "index.js",
"upload_source_maps": true,
"kv_namespaces": [
{
"binding": "KV",
"id": "YOUR_KV_NAMESPACE_ID"
}
],
"vars": {
"TEAM_DOMAIN": ".cloudflareaccess.com",
"DEBUG": false
}
}
```
### 2. Program your business logic
1. Open `index.js` and modify the `externalEvaluation` function to perform logic on any identity-based data sent by Access.
:::note
- Sample code is available in our [GitHub repository](https://github.com/cloudflare/workers-access-external-auth-example).
- To view a list of identity-based data fields, log in to your Access application and append `/cdn-cgi/access/get-identity` to the URL. For example, if `www.example.com` is behind Access, visit `https://www.example.com/cdn-cgi/access/get-identity`.
:::
2. Deploy the Worker to Cloudflare's global network.
```sh
npx wrangler deploy
```
The Worker will be deployed to your `*.workers.dev` subdomain at `my-worker..workers.dev`.
### 3. Generate a key
To generate an RSA private/public key pair:
1. Open a browser and go to `https://my-worker..workers.dev/keys`.
2. (Optional) Verify that the key has been stored in the `KV` namespace:
1. In the Cloudflare dashboard, go to the **Workers KV** page.
.workers.dev/` | `https://my-worker..workers.dev/keys/` |
4. Save the policy.
5. Go to **Access controls** > **Applications** and edit the application for which you want to apply the External Evaluation rule.
6. In the **Policies** tab, add the policy that contains the External Evaluation rule.
7. Select **Save**.
When a user logs in to your application, Access will now check their email, device, location, and other identity-based data against your business logic.
### Troubleshooting the Worker
To debug your External Evaluation rule:
1. Go to your Worker directory.
```sh
cd my-worker
```
2. Open the [Wrangler configuration file](/workers/wrangler/configuration/) in an editor and set the `debug` variable to `TRUE`.
3. Deploy your changes.
```sh
npx wrangler deploy
```
4. Next, start a session to output realtime logs from your Worker.
```sh
wrangler tail -f pretty
```
5. Log in to your Access application.
The session logs should show an incoming and outgoing JWT. The incoming JWT was sent by Access to the Worker API, while the outgoing JWT was sent by the Worker back to Access.
6. To decode the contents of a JWT, you can copy the token into [jwt.io](https://jwt.io/).
The incoming JWT should contain the user's identity data. The outgoing JWT should look similar to:
```js
{
"success": true,
"iat": 1655409315,
"exp": 1655409375,
"nonce": "9J2E9Xg6wYj8tlnA5MV4Zgp6t8rzmS0Q"
}
```
Access checks the outgoing JWT for all of the following criteria:
- Token was signed by **Keys URL**.
- Expiration date has not elapsed.
- API returns `"success": true`.
- `nonce` is unchanged from the incoming JWT. The `nonce` value is unique per request.
If any condition fails, the External Evaluation rule evaluates to false.
# Rule groups
import { Render } from "~/components";
A rule group is a collection of Access rules that can be configured once and then quickly applied across many Access policies. Rule groups use the same [rule types](/cloudflare-one/access-controls/policies/#rule-types) and [selectors](/cloudflare-one/access-controls/policies/#selectors) shown in the Access policy builder.
:::note
Rule groups are distinct from groups in your identity provider, like Okta groups. Rule groups can contain a mix of individual users, groups from identity providers, and service authentication options like service tokens.
:::
## Create a rule group
` and add the Bypass policy shown in the following table:
JSON Web Token (JWT) generated for the user.
Certain identity providers also share the MFA method presented by the user. Access can add these values into the JWT. For example, if the user authenticated with their password and a security key, the IdP can send a confirmation to Cloudflare Access. Access then stores that method in the JWT issued to the user.
Cloudflare Access follows [RFC 8176](https://tools.ietf.org/html/rfc8176), Authentication Method Reference Values, to define authentication methods.
## Independent MFA
Independent MFA prompts users for a second factor directly in Access. This allows you to enforce MFA requirements without relying on your IdP's MFA configuration.
You can configure MFA requirements at three levels:
| Level | Description |
| -------------------------------------------------------------------------------- | -------------------------------------------------------------- |
| [Organization](/cloudflare-one/access-controls/access-settings/independent-mfa/) | Enforce MFA by default for all applications in your account. |
| [Application](#configure-independent-mfa-for-an-application) | Require or turn off MFA for a specific application. |
| [Policy](#configure-independent-mfa-for-a-policy) | Require or turn off MFA for users who match a specific policy. |
MFA settings use this precedence: **Policy** > **Application** > **Organization**.
### Prerequisites
Before you configure independent MFA on applications or policies, you must [turn on independent MFA](/cloudflare-one/access-controls/access-settings/independent-mfa/) at the organization level.
:::tip
At the organization level, you can also [restrict which authenticators can be enrolled using AAGUIDs](/cloudflare-one/access-controls/access-settings/independent-mfa/#restrict-authenticators-by-aaguid) and [skip independent MFA when the identity provider already performed MFA](/cloudflare-one/access-controls/access-settings/independent-mfa/#use-identity-provider-mfa.
:::
### Configure independent MFA for an application
Each application has three MFA options:
| Option | Behavior |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Respect global enforcement setting** | Uses the [organization-level](/cloudflare-one/access-controls/access-settings/independent-mfa/) MFA configuration. If MFA is required globally, users must complete MFA. If MFA is not required globally, users are not prompted. This is the default. |
| **Custom MFA settings** | Overrides the organization setting with application-specific allowed authenticators and session duration. |
| **Disable MFA** | Users are not prompted for independent MFA when accessing this application, even if MFA is required globally. |
To configure MFA for an application:
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **Applications**.
2. Find the application you want to configure and select **Configure**.
3. Scroll down to **Authentication** and select the **MFA**.tab.
4. Select one of the following options:
- To inherit the organization setting, select **Respect global enforcement setting**.
- To set custom requirements, select **Custom MFA settings**, then configure the [allowed MFA methods](/cloudflare-one/access-controls/access-settings/independent-mfa/#supported-mfa-methods) and [authentication duration](#mfa-session-duration).
- To exempt the application from MFA, select **Disable MFA**.
5. Select **Save**.
To configure MFA for an infrastructure application, refer to [Infrastructure applications](#infrastructure-applications).
### Configure independent MFA for a policy
Each policy has the same three MFA options described in [Configure independent MFA for an application](#configure-independent-mfa-for-an-application). Policy-level settings override application-level settings.
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **Policies**.
2. Choose an **Allow** policy and select **Configure**.
3. Under **Multi-factor authentication (MFA)**, select an option:
- To inherit the application or organization setting, select **Respect global enforcement setting**.
- To set custom requirements for users who match this policy, select **Custom MFA settings**, then configure the [allowed MFA methods](/cloudflare-one/access-controls/access-settings/independent-mfa/#supported-mfa-methods) and [authentication duration](#mfa-session-duration).
- To exempt users who match this policy from MFA, select **Disable MFA**.
4. Select **Save**.
To configure MFA for an infrastructure application policy, refer to [Infrastructure applications](#infrastructure-applications).
### MFA session duration
The MFA session duration determines how long a successful MFA authentication remains valid. After the MFA session expires, the user must complete MFA again on their next Cloudflare Access login in addition to completing IdP authentication. You can require users to complete MFA on each Access login or set a custom duration. MFA session durations are only checked during the login flow and do not affect a user's existing session.
Access checks MFA sessions from most specific to least specific:
1. **Policy MFA session duration** — If set, applies to users who match the policy.
2. **Application MFA session duration** — If set, applies to all users accessing the application.
3. **Global MFA session duration** — The default for all applications that do not specify their own duration.
#### Require MFA on every login
To require MFA every time a user logs in to an application, set the authentication duration to **Require every login**. This prevents Access from caching a successful MFA session.
- **Organization** — Go to **Zero Trust** > **Access controls** > **Access settings** > **Allow multi-factor authentication (MFA)**. Set **Authentication duration** to **Require every login**. This applies to all applications unless overridden at the application or policy level. For more details, refer to [independent MFA settings](/cloudflare-one/access-controls/access-settings/independent-mfa/).
- **Application** — Go to **Zero Trust** > **Access controls** > **Applications** > select your application > **Configure** > **Authentication** > **MFA** tab. Select **Custom MFA settings** and set **Authentication duration** to **Require every login**.
- **Policy** — Go to **Zero Trust** > **Access controls** > **Policies** > select your policy > **Configure**. Under **Multi-factor authentication (MFA)**, select **Custom MFA settings** and set **Authentication duration** to **Require every login**.
To configure this for an application via the API, first send a `GET` request to retrieve the full application configuration, then send a `PUT` request with the complete application body including the updated `mfa_config`. Set `session_duration` to `"0m"`:
```bash
curl --request PUT \
https://api.cloudflare.com/client/v4/accounts/{account_id}/access/apps/{app_id} \
--header "Authorization: Bearer " \
--header "Content-Type: application/json" \
--data '{
"mfa_config": {
"mfa_disabled": false,
"session_duration": "0m"
}
}'
```
### Precedence example
Consider the following configuration:
```mermaid
flowchart TD
subgraph org["Organization"]
orgSettings["**Apply global MFA settings by default**,
**MFA methods**: Authenticator app + Security key,
**Authentication duration**: 24 hours"]
end
subgraph appA["Application A"]
appASettings["**Respect global enforcement setting**
(inherits organization settings)"]
subgraph policies["Policies"]
policy1["Policy 1
**Custom MFA settings**,
**MFA methods**: Security keys only,
**Authentication duration**: 1 hour"]
policy2["Policy 2
**Disable MFA**"]
end
end
subgraph appB["Application B"]
appBSettings["**Disable MFA**"]
end
orgSettings --> appASettings
orgSettings -.->|"overridden"| appBSettings
appASettings -.->|"overridden by"| policy1
appASettings -.->|"overridden by"| policy2
```
In this example:
- Users who access Application A and match Policy 1 must use a security key and re-authenticate every hour.
- Users who access Application A and match Policy 2 are not prompted for MFA.
- Users who access Application A and match neither policy must use an authenticator application or a security key, with a 24-hour session.
- Users who access Application B are not prompted for MFA.
## Infrastructure applications
Infrastructure applications that use SSH support two infrastructure-only MFA methods. `piv_key` uses an enrolled Personal Identity Verification (PIV) key. `ssh_fido2_key` uses an enrolled FIDO2 key. Neither method applies to other Access application types or browser WebAuthn authentication.
You can configure MFA for infrastructure apps at the application level or at the policy level.
### Configure MFA for an infrastructure application
Select PIV key, FIDO2 key, or both when configuring custom MFA. The corresponding API arrays are `["piv_key"]`, `["ssh_fido2_key"]`, and `["piv_key", "ssh_fido2_key"]`.
:::note
" \
--header "Content-Type: application/json" \
--data '{
"mfa_config": {
"mfa_disabled": false,
"session_duration": "12h",
"allowed_authenticators": ["piv_key", "ssh_fido2_key"]
}
}'
```
| Field | Type | Description |
| ------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `mfa_disabled` | Boolean | If `true`, MFA is not required for this application, even if global settings enforce MFA. |
| `session_duration` | String | Duration before the user must re-authenticate with MFA (for example, `30m`, `1h`, `24h`). Set to `0m` to require MFA on every SSH connection. |
| `allowed_authenticators` | Array | Use `["piv_key"]`, `["ssh_fido2_key"]`, or `["piv_key", "ssh_fido2_key"]`. |
### Configure MFA for an infrastructure policy
You can set different MFA requirements for different SSH usernames by configuring MFA at the policy level. Policy-level MFA settings override application-level settings.
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **Applications**.
2. Find your infrastructure application and select **Configure**.
3. Go to **Policies** and select the policy you want to configure.
4. Under **Multi-factor authentication (MFA)**, select an option:
- **Respect global enforcement setting** — Inherits the application or organization setting.
- **Custom MFA settings** — Select **PIV key**, **FIDO2 key**, or both as the allowed authenticators and set a custom MFA session duration for users who match this policy.
- **Disable MFA** — Users who match this policy are not prompted for MFA.
5. Select **Save**.
To update MFA settings for a policy, first send a `GET` request to retrieve the full policy configuration, then send a `PUT` request with the complete policy body including the `mfa_config` object. The `mfa_config` object uses the same fields as the [application-level configuration](#configure-mfa-for-an-infrastructure-application).
```bash
curl --request PUT \
https://api.cloudflare.com/client/v4/accounts/{account_id}/access/policies/{policy_id} \
--header "Authorization: Bearer " \
--header "Content-Type: application/json" \
--data '{
"name": "Require MFA for root",
"decision": "allow",
"include": [
{
"email": {
"email": "jdoe@company.com"
}
}
],
"mfa_config": {
"mfa_disabled": false,
"session_duration": "1h",
"allowed_authenticators": ["piv_key", "ssh_fido2_key"]
},
"connection_rules": {
"ssh": {
"usernames": ["root"],
"allow_email_alias": false
}
}
}'
```
### MFA session duration for SSH
The MFA session duration determines how long users can open new SSH connections without another MFA prompt. Set the duration to `0m` to require MFA for every new connection. Expiration does not terminate an active connection.
MFA sessions are bound to the user's device. If a user switches to a different device, they must re-authenticate regardless of the remaining session duration.
Session duration is evaluated in the following order:
1. **Policy-level duration** — If set, applies to users who match the policy.
2. **Application-level duration** — If no policy-level duration is set, uses the application setting.
3. **Organization-level duration** — If neither policy nor application defines a duration, uses the global setting.
When a user matches multiple policies that each define a session duration, Access uses the **shortest** duration across all matching policies.
### Precedence and conflict resolution
MFA configuration is evaluated from most specific to least specific: **policy** > **application** > **organization**.
| Organization MFA | Application MFA | Policy MFA | Result |
| ---------------- | --------------- | ---------- | ------------------------------------------- |
| Required | Required | Required | MFA required |
| Required | Required | Disabled | MFA not required (policy wins) |
| Required | Disabled | (not set) | MFA not required (application wins) |
| Required | (not set) | (not set) | MFA required (organization setting applies) |
Organization-level MFA must be enabled for users to enroll PIV keys. Explicit settings at a lower level (policy or application) override higher levels. If no explicit setting exists at a level, the next higher level applies.
# Manage Access policies
import { Tabs, TabItem, APIRequest } from "~/components";
Access policies define the users who can log in to your Access applications. You can create, edit, or delete policies at any time and reuse policies across multiple applications.
## Create a policy
To create a reusable Access policy:
1. In [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **Policies**.
2. Select **Add a policy**.
3. Enter a **Policy name**.
4. Choose an [**Action**](/cloudflare-one/access-controls/policies/#actions) for the policy.
5. Choose a [**Session duration**](/cloudflare-one/access-controls/access-settings/session-management/) for the policy.
6. Configure as many [**Rules**](/cloudflare-one/access-controls/policies/#rule-types) as needed.
7. (Optional) Configure additional settings for users who match this policy:
- [Isolate application](/cloudflare-one/access-controls/policies/isolate-application/).
- [Purpose justification](/cloudflare-one/access-controls/policies/require-purpose-justification/)
- [Temporary authentication](/cloudflare-one/access-controls/policies/temporary-auth/)
- [Independent MFA](/cloudflare-one/access-controls/policies/mfa-requirements/#independent-mfa)
8. Select **Save**.
You can now add this policy to an [Access application](/cloudflare-one/access-controls/applications/http-apps/).
## Edit a policy
To make changes to an existing Access policy:
1. In [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **Policies**.
2. Locate the policy you want to update and select **Configure**.
3. Once you have made the necessary changes, select **Save**.
The updated policy is now in effect for all associated Access applications.
## Delete a policy
To delete a reusable Access policy:
1. In [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **Policies** and locate the policy you want to delete.
2. If the policy is used by an application, remove the policy from all associated applications.
3. Select **Delete**.
4. A pop-up message will ask you to confirm your decision to delete the policy. Select **Delete**.
## Test your policies
You can test your Access policies against all existing user identities in your Zero Trust organization. For the policy tester to work, users must have logged into the [App Launcher](/cloudflare-one/access-controls/access-settings/app-launcher/) or any other Access application at some point in time.
Cloudflare will use the most recent device that was authenticated with Access to test your policies.
### Test a single policy
The Access policy builder allows you to test your rules before saving any changes.
To test an individual Access policy:
1. In [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **Policies**.
2. Locate the policy you want to test and select **Configure**.
3. Go to **Policy tester** and select **Test policies**.
The policy tester reports the percentage of active users who are allowed or denied access to an application based on this policy. You can expand the test results to view a list of allowed or blocked users.
### Test all policies in an application
You can test your Access application policies against your user population before deploying changes to your users. After saving your changes, you can also perform a more detailed policy test for a specific user.
To test if users have access to an application:
1. In [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **Applications**.
2. Locate the application you want to test and select **Configure**.
3. Go to **Policies** > **Policy tester**.
4. To test all active users in your organization, select **Test policies**.
The policy tester reports the percentage of users who are allowed or denied access to this application based on all configured policies. You can expand the test results to view a list of allowed or blocked users.
5. To perform a detailed test on a single user:
a. If you made any changes to your policies, first save the application.
b. Select **testing a single user**.
c. Enter their email address and select **Test policies**.
The single user test results will show:
- Whether the user is allowed or denied access to this application based on all configured policies.
- The user's identity from their most recent Access login attempt.
- Whether the user matches individual Allow, Block, or Bypass policies.
## Legacy policies
Legacy policies are scoped to a specific application and cannot be added to newly created Access applications.
### Migrate to reusable policies
To migrate legacy policies to reusable policies:
1. [Create a reusable policy](#create-a-policy) that will replace the legacy policy.
2. Go to the Access application associated with the legacy policy.
3. Add the reusable policy to the application and remove the legacy policy. Removing the legacy policy from the application also deletes it.
4. Repeat these steps for each legacy policy. If you have duplicate legacy policies, you can replace them with a single reusable policy.
### Convert a legacy policy
You can use the API to convert a legacy policy into a reusable policy. To convert a legacy policy, make a `PUT` request with an empty request body:
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
-----END CERTIFICATE-----
```
Do not include any SSL/TLS server certificates; Access only uses the CA chain to verify the connection between the user's device and Cloudflare.
5. In **Associated hostnames**, enter the fully-qualified domain names (FQDN) that will use this certificate.
These FQDNs will be the hostnames used for the resources being protected in the [Access policy](/cloudflare-one/access-controls/policies/). You must associate the Root CA with the FQDN that the application being protected uses.
6. Save the policy.
7. Go to **Access controls** > **Policies**.
8. [Create an Access policy](/cloudflare-one/access-controls/policies/policy-management/#create-a-policy) using one of the following [selectors](/cloudflare-one/access-controls/policies/#selectors):
- **Valid Certificate**: Any client certificate that can authenticate with the Root CA will be allowed to proceed.
- **Common Name**: Only client certificates with a specific common name will be allowed to proceed.
9. If this is for a client who does not need to log in through an IdP, set the policy **Action** to _Service Auth_.
**Example mTLS policy**
10. Save the policy, then go to **Access controls** > **Applications**.
11. Select the application you would like to enforce mTLS on and select **Configure**. The application must be included in the **Associated hostnames** list from Step 5.
12. In the **Policies** tab, add your mTLS policy.
13. Save the application.
You can now authenticate to the application using a client certificate. For instructions on how to present a client certificate, refer to [Test mTLS](#test-mtls).
## Test mTLS
### Test using cURL
To test the application protected by an mTLS policy:
1. First, attempt to curl the site without a client certificate.
This curl command example is for the site `example.com` that has an [Access application and policy](#add-mtls-to-your-access-application) set for `https://auth.example.com`:
```sh
curl -sv https://auth.example.com
```
Without a client certificate in the request, a `403 forbidden` response displays and the site cannot be accessed.
2. Now, add your client certificate and key to the request:
```sh
curl -sv https://auth.example.com --cert example.pem --key key.pem
```
When the authentication process completes successfully, a `CF_Authorization Set-Cookie` header returns in the response.
:::caution
Cloudflare Gateway cannot inspect traffic to mTLS-protected domains. If a device has the Cloudflare One Client turned on and passes HTTP requests through Gateway, access will be blocked unless you [bypass HTTP inspection](/cloudflare-one/traffic-controls/http-policies/#do-not-inspect) for the domain.
:::
### Test in a browser
To access an mTLS-protected application in a browser, the client certificate must be imported into your browser's certificate manager. Instructions vary depending on the browser. Your browser may use the operating system's root store or its own internal trust store.
The following example demonstrates how to add a client certificate to the macOS system keychain:
:::caution[Important]
The command adds the client certificate to the trusted store on your device. Only proceed if you are comfortable doing so and intend to keep these testing certificates safeguarded.
:::
1. Navigate to the directory containing the client certificate and key.
`
`CF-Access-Client-Secret: `
For example,
```sh
curl -H "CF-Access-Client-Id: " -H "CF-Access-Client-Secret: " https://app.example.com
```
#### Authenticate with a single header
You can configure a self-hosted Access application to accept a service token in a single HTTP header, as an alternative to the `CF-Access-Client-Id` and `CF-Access-Client-Secret` pair of headers. This is useful for authenticating SaaS services that only support sending one custom header in a request (for example, the `Authorization` header).
To authenticate using a single header:
1. Get your existing Access application configuration:
\", \"cf-access-client-secret\": \"\"}" https://app.example.com
```
## Strict service token authentication
Strict service token authentication is a Zero Trust organization setting that applies consistent behavior to requests made with service tokens. When the setting is on, Access handles requests with service token headers as follows:
- If authentication or authorization fails, Access always returns `401` or `403` instead of redirecting the client to the login page with `302`.
- Only Service Auth policies can authorize the request. Access ignores Allow policies and any `CF_Authorization` cookie sent with the request.
- Access does not return a `CF_Authorization` cookie to the client after successful authentication. Subsequent requests should continue to use service token headers.
- Failed requests for recognized service tokens appear in [Access authentication logs](/cloudflare-one/insights/logs/dashboard-logs/access-authentication-logs/#non-identity-authentication). Access logs expired or disabled tokens, incorrect Client Secrets, and tokens not authorized for the application. It does not log malformed headers or unknown Client IDs.
Zero Trust organizations created on or after `2026-10-05` have strict service token authentication turned on by default and cannot turn it off. Cloudflare recommends that existing organizations turn it on as well.
:::note
Organizations created before `2026-10-05` can turn this setting on or off.
:::
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **Access settings**.
To turn off strict service token authentication, turn off the setting and select **Disable**.
Send a `PATCH` request to the [Update your Zero Trust organization](/api/resources/zero_trust/subresources/organizations/methods/update/) endpoint:
## Rotate service token secrets
Rotate a service token secret when you suspect exposure or as part of regular credential rotation. The Client ID remains the same, but Access generates a new Client Secret.
You can set a grace period during which both secrets work. Use this period to update your services before Access revokes the previous secret.
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **Service credentials** > **Service Tokens**.
Make a `POST` request to the [Rotate a service token](/api/resources/zero_trust/subresources/access/subresources/service_tokens/methods/rotate/) endpoint. Set `previous_client_secret_expires_at` to an RFC 3339 timestamp when the previous secret should expire:
## Renew service tokens
Service tokens expire according to the token duration you selected when you created the token.
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **Service credentials** > **Service Tokens**.
2. Locate the token you want to renew.
3. To extend the token's lifetime by one year, select **Refresh**.
4. To extend the token's lifetime by more than a year:
1. Select **Edit**.
2. Choose a new **Service Token Duration**.
3. Select **Save**. The expiration date will be extended by the selected amount of time.
To extend the token's lifetime by one year, make a `POST` request to the [Refresh a service token](/api/resources/zero_trust/subresources/access/subresources/service_tokens/methods/refresh/) endpoint:
To renew the service token, update the `duration` attribute on the [`cloudflare_zero_trust_access_service_token`](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/zero_trust_access_service_token) resource and apply the change. Cloudflare resets the expiration relative to the time of the update.
```tf
resource "cloudflare_zero_trust_access_service_token" "example_service_token" {
account_id = var.cloudflare_account_id
name = "Example service token"
duration = "17520h"
lifecycle {
create_before_destroy = true
}
}
```
## Manage inactive service tokens
You can configure Access to automatically disable or delete service tokens that are no longer in use. The setting applies to all service tokens in your Zero Trust account.
Access considers a service token inactive when all of the following are true:
- The token has not successfully authenticated with an Access application during the configured inactivity period.
- The token is older than the configured inactivity period.
- The token is not directly referenced by an Access policy rule.
You can set the inactivity period to a whole number from 30 to 365 days. Disabled tokens remain in your account and can be turned on again. Deleted tokens cannot be recovered.
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **Access settings**.
Send a `PATCH` request to update your Zero Trust organization. Set `action` to `disable` or `delete`:
Cleanup runs gradually in the background. An eligible token may not be disabled or deleted immediately.
## Turn a service token on or off
Turn off a service token to temporarily prevent it from authenticating. Access preserves the token so you can turn it on again later.
Turning off a token also stops its previous secret from working during an active rotation grace period.
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **Service credentials** > **Service Tokens**.
Make a `PUT` request to the [Update a service token](/api/resources/zero_trust/subresources/access/subresources/service_tokens/methods/update/) endpoint. Set `enabled` to `false` to turn off the token:
",
enabled: false,
}}
/>
To turn the token on again, set `enabled` to `true`.
## Revoke service tokens
If you need to revoke access before the token expires, delete the token. Services that rely on a deleted service token can no longer reach your application.
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **Service credentials** > **Service Tokens**.
2. **Delete** the token you need to revoke.
Make a `DELETE` request to the [Delete a service token](/api/resources/zero_trust/subresources/access/subresources/service_tokens/methods/delete/) endpoint:
To revoke the service token, remove the [`cloudflare_zero_trust_access_service_token`](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/zero_trust_access_service_token) resource from your configuration and run `terraform apply`, or target the resource for destruction:
```sh
terraform destroy -target=cloudflare_zero_trust_access_service_token.example_service_token
```
:::note
When editing an Access application, selecting **Revoke existing tokens** revokes existing sessions but does not prevent the user from starting a new session. As long as the Client ID and Client Secret are still valid, they can be exchanged for a new token on the next request. To revoke access, you must delete the service token.
:::
## Set a token expiration alert
An alert can be configured to notify a week before a service token expires to allow an administrator to invoke a token refresh.
Included and excluded requests"]
B --> C["Policy filters
Select applicable policies"]
C -->|Matching policies| D["Rego validation
Each policy's valid rule"]
C -->|No matching policy| F["Request decision
Enforce and deployment defaults"]
E["Rego modules, metadata,
and tenant structures"] -.-> D
D --> F
```
## Select applicable policies
### Deployment and policy sets
The deployment selects the policy sets available for evaluation. Each set groups policies and specifies included and excluded workloads.
### Workload scope
A request must match an included workload when inclusions are configured. It must not match an excluded workload. An empty inclusion list adds no inclusion restriction.
### Policy filter
Within that scope, each policy's filter selects the requests to check. For example, a workload can select Cloudflare API traffic while a policy filter selects one R2 operation. Workload scope and policy filter must both match for the policy to apply.
## Validate with Rego
Each matching policy evaluates a Boolean rule named `valid`. A `true` result passes that policy's check. A `false` result fails it. Use Rego to validate request content, such as whether a change would make a bucket public.
Policies can reuse shared logic and data:
- [Rego modules](/cloudflare-one/cloud-workload-security/guides/policy-reference/#create-a-rego-module) supply reusable checking logic.
- [Rego metadata](/cloudflare-one/cloud-workload-security/guides/policy-reference/#create-rego-metadata) supplies shared JSON values.
- [Tenant structures](/cloudflare-one/cloud-workload-security/guides/policy-reference/#create-a-tenant-structure) describe cloud resource hierarchies. A package path makes their nodes available to Rego.
## Apply enforcement and defaults
Each policy's **Enforce** setting within its policy set determines how its check result affects the request:
| Condition | Effect |
| ------------------------------------------------------- | ------------------------------------------------------------------------ |
| A matching policy returns `true`. | That check passes. Another enforcing policy can still block the request. |
| A matching policy returns `false` with **Enforce** on. | Block the request. |
| A matching policy returns `false` with **Enforce** off. | Record the failed check without blocking on that policy's result. |
| No policy matches the request. | Apply the deployment's **Default mode**. |
More than one policy can match a request. A failed enforcing policy blocks even when another policy passes. A failed Rego check is not an unmatched request, so it does not fall back to **Default mode**.
Configure policy error handling with the deployment's **On error action** setting.
## Example: keep R2 buckets private
Suppose a workload selects Cloudflare API requests. Its policy set contains a policy for changing R2 bucket public access. The policy filter selects that operation. Rego permits it only when `input.http.request.body.enabled` is `false`.
An attempt to turn on public access matches the filter but fails Rego validation. With **Enforce** on, CWS blocks the request. For a runnable guardrail example, follow [Get started](/cloudflare-one/cloud-workload-security/get-started/).
## Related controls
[Domain ACLs](/cloudflare-one/cloud-workload-security/guides/manage-traffic-scope/#create-a-domain-acl) control which destinations a deployment can reach. Allowing a destination does not bypass workload scope or policy checks.
[Basic Auth credentials](/cloudflare-one/cloud-workload-security/guides/manage-traffic-scope/#create-a-basic-auth-credential) provide client identities that workload and policy filters can match. The cloud provider still applies its own authentication and permissions.
To configure scope and enforcement, follow [Configure policies](/cloudflare-one/cloud-workload-security/guides/configure-policies/). To inspect decisions, refer to [Read proxy logs](/cloudflare-one/cloud-workload-security/troubleshooting/#read-proxy-logs).
# Proxy configuration
Use `config.yaml` to configure the Cloud Workload Security (CWS) proxy process. Start with the complete local configuration in [Get started](/cloudflare-one/cloud-workload-security/get-started/#configure-the-proxy), then replace the relevant blocks with the options in this reference.
Either API authentication mode can be combined with direct or chained outbound connections and any cache mode.
The file requires three top-level objects:
| Object | Purpose |
| ------- | ------------------------------------------------------------------- |
| `cws` | Account, deployment, API authentication, and configuration refresh. |
| `proxy` | Listener, logging, TLS certificates, and outbound proxy settings. |
| `redis` | Process-local cache limits and optional shared Redis storage. |
Unknown settings are rejected, including unknown fields within these objects. Examples containing one object are partial configurations. Retain the other required objects from your file.
## Validate a configuration
After editing your configuration, validate it before starting the proxy:
```sh
cws-proxy --config config.yaml --config-test
```
Successful validation prints `CWS proxy configuration is valid`. This checks local settings. It does not fetch the deployment, verify credentials, connect to Redis, or prove the listener can start.
Restart the proxy after changing `config.yaml` or its process environment. Dashboard policy changes are loaded through configuration refresh instead.
## API connection and authentication
The `cws` object connects the proxy to one account and deployment. Its settings are:
| Setting | Required or default | Description |
| ------------------------ | ------------------------------------------ | ---------------------------------------------------------------------------------------- |
| `api_base_url` | Required | Use `https://api.cloudflare.com/client/v4`. |
| `account_id` | Required | Account ID containing the deployment. |
| `deployment_id` | Required | ID of the deployment whose configuration the proxy loads. |
| `api_poll_interval_secs` | `30` | Seconds between deployment configuration refreshes. Must be an integer of at least `30`. |
| `api_token_env` | Required for API token authentication | Name of the environment variable containing the API token. |
| `api_key_env` | Required for Global API Key authentication | Name of the environment variable containing the Global API Key. |
| `api_key_email` | Required for Global API Key authentication | Literal account email associated with that key. |
Choose exactly one authentication mode. For API token authentication, omit `api_key_env` and `api_key_email`. For Global API Key authentication, supply both key fields and omit `api_token_env`. Do not set unused authentication fields to `null`.
### API token
Use an API token with the **Cloud Workload Security Deployment** permission for the intended account. For token creation, follow [Create the proxy API token](/cloudflare-one/cloud-workload-security/get-started/#create-the-proxy-api-token).
Replace `` and `` with your resource IDs:
```yaml title="API token authentication"
cws:
api_base_url: "https://api.cloudflare.com/client/v4"
api_poll_interval_secs: 30
api_token_env: CWS_DEPLOYMENT_TOKEN
account_id: ""
deployment_id: ""
```
Supply the token through `CWS_DEPLOYMENT_TOKEN` in the proxy process environment. `api_token_env` stores the variable's name, not its value. This credential loads CWS configuration. Clients still need their own cloud-provider credentials.
### Global API Key
For Global API Key authentication, replace the entire `cws` object with this form. Replace the email and resource placeholders:
```yaml title="Global API Key authentication"
cws:
api_base_url: "https://api.cloudflare.com/client/v4"
api_poll_interval_secs: 30
api_key_env: CWS_GLOBAL_API_KEY
api_key_email: ""
account_id: ""
deployment_id: ""
```
Supply the key through `CWS_GLOBAL_API_KEY` in the proxy process environment.
### Environment references
`api_base_url`, `account_id`, and `deployment_id` also accept complete environment references such as `${CWS_ACCOUNT_ID}`. The referenced variable must exist and contain a nonblank value. Embedded substitutions and shell expressions are not supported.
For example, replace the two ID values in your existing `cws` object with:
```yaml title="Account and deployment references"
account_id: "${CWS_ACCOUNT_ID}"
deployment_id: "${CWS_DEPLOYMENT_ID}"
```
Other strings remain literal. For `api_token_env`, `api_key_env`, and Redis `url_env`, use the variable name directly, without `${...}`. Certificate paths and `api_key_email` do not expand environment references.
## Listener and logging
The `proxy` object requires `logging`, `tls_interception`, and `upstream`. Its listener and logging options are:
| Setting | Default | Description |
| ------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `proxy.listen_addr` | `0.0.0.0:8080` | IP address and port for the HTTP proxy listener. Hostnames are not accepted. Use brackets for IPv6, such as `[::1]:8080`. |
| `proxy.logging.format` | `json` | Log format: `json` or `text`. |
| `proxy.logging.verbosity` | `INFO` | Log level: `CRITICAL`, `ERROR`, `WARN`, `INFO`, `DEBUG`, or `TRACE`. Values are case-sensitive. |
Keep `127.0.0.1:8080` for clients on the same host or network namespace. For a shared proxy, choose an address clients can reach and restrict network access to intended clients. `0.0.0.0` listens on all IPv4 interfaces. It is not a destination address for clients.
An empty `logging: {}` uses JSON at `INFO`. For human-readable logging, replace `proxy.logging` with:
```yaml title="Text logging"
logging:
format: text
verbosity: INFO
```
For log events, decision fields, and redaction guidance, refer to [Read proxy logs](/cloudflare-one/cloud-workload-security/troubleshooting/#read-proxy-logs).
## TLS certificates and trust
The `proxy.tls_interception` object requires all three settings:
| Setting | Value | Description |
| ---------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------- |
| `ca_cert` | Nonblank file path | CA certificate used to sign certificates presented to clients. |
| `ca_private_key` | Nonblank file path | Matching CA private key. Keep this key on the proxy host. |
| `extra_root_cas` | List of unique, nonblank file paths | Additional trusted roots for the proxy's outbound TLS connections. Use `[]` when none are needed. |
Clients trust `ca_cert`, not the private key. For CA creation and client setup, follow [Prepare a certificate authority](/cloudflare-one/cloud-workload-security/get-started/#prepare-a-certificate-authority).
Paths are resolved from the proxy process's working directory, not the configuration file's directory. Use absolute paths when those directories differ.
If your network inspects outbound TLS, add its approved CA certificate to `extra_root_cas`. Each file supplies only its first certificate, so use a separate PEM file for each additional root. This setting does not configure client trust or the CA used to sign intercepted certificates.
## Outbound proxy chaining
Use `proxy.upstream.proxy` when CWS must reach destinations through another HTTP proxy. These settings belong to the CWS proxy process. They are separate from the client's `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` environment variables.
The outbound proxy settings are:
| Setting | Default | Description |
| ------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `http_proxy` | `null` | Upstream proxy URL for destination port `80`. |
| `https_proxy` | `null` | Upstream proxy URL for destination port `443`. |
| `ca_cert` | `null` | Additional CA certificate file trusted when connecting to an `https://` upstream proxy. Only the first certificate in the file is read. |
| `no_proxy` | `null` | Unique destination rules that connect directly instead of using the upstream proxy. An empty list also means no exceptions. |
Both proxy URL fields accept `http://` or `https://`. The field chooses the destination traffic. The URL scheme chooses whether CWS uses TLS to connect to the upstream proxy. For example, `https_proxy: "http://proxy.example.com:8080"` routes port `443` through an HTTP proxy.
Configure each traffic type independently. Setting only `http_proxy` does not route port `443` through it. Omit a field or use `null` for direct connections of that type. `proxy.upstream.proxy: {}` uses direct connections for both types.
Proxy URLs can include Basic Auth credentials. Supply such configuration through your secret-management process. Do not confuse these credentials with the deployment API credential or client identity.
### Chain both traffic types
Replace `proxy.upstream` with this block, substituting your upstream proxy URL and CA path:
```yaml title="Upstream proxy with direct exceptions"
upstream:
proxy:
http_proxy: "https://proxy.example.com:8443"
https_proxy: "https://proxy.example.com:8443"
ca_cert: /path/to/upstream-proxy-ca.pem
no_proxy:
- api.example.com
- .internal.example.com
- 192.0.2.10
- 2001:db8::/32
```
`ca_cert` establishes trust in the upstream proxy. `tls_interception.extra_root_cas` establishes additional trust for outbound destination certificates. These serve different connections.
### Direct-connection rules
`no_proxy` supports these rule types:
| Rule | Matches |
| --------------------------------- | ------------------------------------------- |
| `api.example.com` | That hostname only. |
| `.example.com` | The parent domain and its subdomains. |
| `192.0.2.10` or `2001:db8::10` | That IP address. |
| `192.0.2.0/24` or `2001:db8::/32` | IP-address destinations in that CIDR range. |
Hostname comparisons ignore case. Entries are destination names or addresses, not URLs or `host:port` pairs. Use hostname rules for named destinations rather than assuming a CIDR rule resolves their DNS names.
An exception bypasses the additional upstream proxy, not CWS policy evaluation. Domain ACLs and applicable request policies still apply.
## Cache and Redis
CWS always has a bounded process-local memory cache. Redis adds shared storage. Without Redis, cached values are local to that process and are lost when it exits.
Choose the connection mode that matches your Redis service:
| Mode | `enabled` | `cluster_mode` | `auth_type` | Additional required settings |
| ------------------------------- | --------- | -------------- | ----------- | ------------------------------------------------ |
| Memory only | `false` | Not needed | Not needed | None. |
| Standalone Redis | `true` | `false` | `basic` | `url_env`. |
| Redis Cluster | `true` | `true` | `basic` | `url_env`. |
| Standalone ElastiCache with IAM | `true` | `false` | `iam` | `url_env`, `iam_cluster_name`, and `iam_region`. |
| ElastiCache cluster with IAM | `true` | `true` | `iam` | `url_env`, `iam_cluster_name`, and `iam_region`. |
### Memory only
This is the configuration used in Get started:
```yaml title="Memory-only cache"
redis:
enabled: false
```
Redis connection and authentication settings are unused in this mode. The memory-cache limits still apply.
### Redis with URL credentials
Replace the `redis` object with:
```yaml title="Standalone Redis"
redis:
enabled: true
url_env: CWS_REDIS_URL
cluster_mode: false
auth_type: basic
```
Inject the Redis connection URL into the proxy environment variable named `CWS_REDIS_URL`. The URL uses `redis://` or `rediss://` and includes the Redis username and password when required. `rediss://` uses TLS.
For Redis Cluster, set `cluster_mode: true`. The environment variable can contain one seed URL or comma-separated seed URLs. Each seed needs a complete URL, and all seeds must use the same scheme.
### ElastiCache IAM
Replace the `redis` object with this form. Substitute your replication-group name and AWS region:
```yaml title="ElastiCache IAM authentication"
redis:
enabled: true
url_env: CWS_REDIS_URL
cluster_mode: false
auth_type: iam
iam_cluster_name: ""
iam_region: ""
```
Set `cluster_mode: true` for an ElastiCache cluster. The connection URL must use `rediss://`, include the ElastiCache username, and omit a password. All seed URLs must use the same username. The proxy obtains AWS credentials through the default AWS credential provider chain and generates IAM authentication tokens. The proxy's AWS identity needs permission to connect to that ElastiCache user and replication group.
When Redis is enabled, startup requires a successful Redis connection. A missing connection variable, invalid authentication, or exhausted connection retries prevents startup. Local `--config-test` validation does not test that connection.
### Redis settings reference
The `redis` settings and defaults are:
| Setting | Default | Description |
| -------------------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `enabled` | Required | `false` for process-local memory only; `true` adds Redis storage. |
| `url_env` | `null` | Environment variable name containing the Redis URL. Required and nonblank when enabled. |
| `cluster_mode` | `false` when disabled | Required when enabled. Use `true` for Redis Cluster and `false` for standalone Redis. |
| `auth_type` | `basic` | `basic` for credentials from the URL, or `iam` for ElastiCache IAM. |
| `iam_cluster_name` | `null` | ElastiCache replication-group name. Required and nonblank for enabled IAM authentication. |
| `iam_region` | `null` | AWS region used to sign IAM tokens. Required and nonblank for enabled IAM authentication. |
| `max_retries` | `3` | Additional connection or command attempts after the first attempt. Integer from `0` through `5`. |
| `backoff_secs` | `1` | Whole seconds between connection or command attempts. Integer from `0` through `5`. |
| `namespace` | `cws` | Prefix for proxy-internal cache keys. Must be nonblank, omit the trailing `:`, and not equal `cws_data` or start with `cws_data:`. |
| `cache_item_size` | `0` | Maximum bytes read from Redis for a non-internal key. `0` removes this read limit. Does not limit process-local or proxy-internal reads. |
| `memory_cache_max_entries` | `10000` | Maximum process-local cache entries. Must be a positive integer. |
| `memory_cache_max_bytes` | `67108864` | Maximum combined process-local key and value bytes, equivalent to 64 MiB. Must be a positive integer. |
Both memory limits apply whether Redis is enabled or disabled. A zero `cache_item_size` does not remove those limits.
The proxy appends `:` to the internal namespace. Policy cache keys use a separate account-and-deployment-scoped namespace, `cws_data:::`. Changing `redis.namespace` does not replace that policy-key isolation.
# Get started
import { DashButton, Steps, TabItem, Tabs } from "~/components";
Run a Cloud Workload Security (CWS) proxy locally and block requests that make an R2 bucket public. This walkthrough uses an empty test bucket in your Cloudflare account.
The proxy and `cf` client run on the same Linux machine. For pipeline runners, application hosts, and shared proxies, refer to [Proxy deployment options](/cloudflare-one/cloud-workload-security/platform/#proxy-deployment-options).
## Prerequisites
:::note[Zero Trust subscription required]
Your account must have a [Zero Trust subscription](/cloudflare-one/setup/#2-create-a-zero-trust-organization). The Zero Trust Free plan is sufficient.
:::
- A Linux machine or virtual machine with APT or DNF, `curl`, and `sudo` access.
- A Cloudflare account with access to manage CWS resources and create account API tokens.
- R2 access in the same account and permission to create and configure a test bucket.
- The [Cloudflare CLI installed and signed in](/cf/get-started/). Use Node.js 24.5 or later for the client proxy settings in this guide.
- OpenSSL and a terminal on the proxy host.
## Set up the proxy locally
1. ### Install the proxy
Install `cws-proxy` using your Linux distribution's package manager:
```sh
sudo curl -fsSLo /usr/share/keyrings/cloudflare-cws.gpg \
https://downloads.cac.cloudflare.com/packages/keys/cws-package-signing.gpg
sudo curl -fsSLo /etc/apt/sources.list.d/cws-proxy.sources \
https://downloads.cac.cloudflare.com/packages/cws-proxy.sources
sudo apt update
sudo apt install cws-proxy
```
```sh
sudo rpm --import \
https://downloads.cac.cloudflare.com/packages/keys/cws-package-signing.asc
sudo curl -fsSLo /etc/yum.repos.d/cws-proxy.repo \
https://downloads.cac.cloudflare.com/packages/cws-proxy.repo
sudo dnf install cws-proxy
```
Confirm that the installed command is available:
```sh
cws-proxy --help
```
For the proxy's Beta terms, license notices, and acknowledgments, refer to [Legal](/cloudflare-one/cloud-workload-security/legal/).
2. ### Create the guardrail policy
In the Cloudflare dashboard, select your account and go to **Cloud Workload Security** > **Policies**.
` and `` with the values you copied. Use absolute certificate paths if the files are outside your working directory.
```yaml title="config.yaml"
cws:
api_base_url: "https://api.cloudflare.com/client/v4"
api_poll_interval_secs: 30
api_token_env: "CWS_DEPLOYMENT_TOKEN"
account_id: ""
deployment_id: ""
proxy:
logging:
format: json
verbosity: INFO
listen_addr: "127.0.0.1:8080"
tls_interception:
ca_cert: ./ca-cert.pem
ca_private_key: ./ca-key.pem
extra_root_cas: []
upstream:
proxy:
http_proxy: null
https_proxy: null
ca_cert: null
no_proxy: null
redis:
enabled: false
```
`api_token_env` contains an environment variable name, not the token value. This local example binds the proxy to loopback and does not require a Redis server.
For other authentication modes, upstream proxies, logging, and Redis options, refer to [Proxy configuration](/cloudflare-one/cloud-workload-security/configuration/).
8. ### Validate and start the proxy
In the terminal that runs the proxy, set your token and validate the file:
```sh
export CWS_DEPLOYMENT_TOKEN=""
cws-proxy --config config.yaml --config-test
```
Successful validation prints `CWS proxy configuration is valid`. It checks the local configuration, not API access.
Start the proxy in that terminal:
```sh
cws-proxy --config config.yaml
```
Keep the terminal open. Wait for `remote_config_loaded` and `action_mapper_loaded` in the logs before sending requests. Do not point this terminal's `HTTP_PROXY` or `HTTPS_PROXY` variables at the local proxy.
9. ### Route the CLI through the proxy
Open a second terminal for the client. Replace the certificate path and Account ID, then set:
```sh
export HTTP_PROXY="http://127.0.0.1:8080"
export HTTPS_PROXY="http://127.0.0.1:8080"
export NODE_USE_ENV_PROXY=1
export NODE_EXTRA_CA_CERTS=""
export CLOUDFLARE_ACCOUNT_ID=""
```
`NODE_EXTRA_CA_CERTS` points to the CA certificate, not its private key. These variables apply to the `cf` client in this terminal. Make sure `NO_PROXY` and `no_proxy` do not bypass `api.cloudflare.com`.
10. ### Verify the guardrail
In the client terminal, create an empty test bucket and inspect managed public access:
```sh
cf r2 buckets create --name cws-r2-guardrails-demo
cf r2 buckets domains managed list --bucket-name cws-r2-guardrails-demo
```
The managed-domain result should contain `"enabled": false`. Use a different bucket name if this name already exists in your account.
First, confirm the policy permits turning off public access:
```sh
cf r2 buckets domains managed update cws-r2-guardrails-demo --enabled false
```
This request should succeed. Then attempt to turn on public access:
```sh
cf r2 buckets domains managed update cws-r2-guardrails-demo --enabled true
```
The request should fail with HTTP status `403` and a `CWS.Error` response. Check the managed-domain result again to confirm public access remains off.
If the request succeeds, immediately turn off public access with `--enabled false`. Check that the CLI uses the proxy, the deployment contains your policy set, and **Enforce** is on. For further checks, refer to [Requests expected to be blocked succeed](/cloudflare-one/cloud-workload-security/troubleshooting/#requests-expected-to-be-blocked-succeed).
11. ### Remove the test bucket
In the client terminal, delete the empty bucket:
```sh
cf r2 buckets delete cws-r2-guardrails-demo
```
Confirm the deletion when prompted.
## Next steps
To apply guardrails outside this local walkthrough, review [Proxy deployment options](/cloudflare-one/cloud-workload-security/platform/#proxy-deployment-options).
To target specific request groups or add more policies, follow [Configure policies](/cloudflare-one/cloud-workload-security/guides/configure-policies/). For destination controls, follow [Manage traffic scope](/cloudflare-one/cloud-workload-security/guides/manage-traffic-scope/).
For startup, certificate, or unexpected request results, refer to [Troubleshooting](/cloudflare-one/cloud-workload-security/troubleshooting/).
# Configure policies
import { DashButton, Steps } from "~/components";
Use workloads to select requests and policies to check them. Group policies in a policy set, then attach that set to a deployment.
You need access to manage Cloud Workload Security in your account. Before attaching a policy set, [create a deployment](/cloudflare-one/cloud-workload-security/get-started/#create-a-deployment). To connect a proxy, follow [Get started](/cloudflare-one/cloud-workload-security/get-started/).
## Create a workload
A workload is a reusable request filter. For example, you can group requests to the Cloudflare API.
Use separate workloads to [target security profiles for production and non-production environments](/cloudflare-one/cloud-workload-security/#target-security-profiles-with-workloads). Include each workload in the policy set for that environment.
1. In the Cloudflare dashboard, select your account and go to **Cloud Workload Security** > **Workloads**.
## Create a policy
Both **Filters** and **Rego source** are required.
A policy filter selects the requests that run its Rego check. The Rego source must declare a package under `policy.` and a Boolean rule named `valid`.
1. In the Cloudflare dashboard, go to **Cloud Workload Security** > **Policies**.
## Create a policy set
A policy set groups policies and their workload scope. A request must match an included workload and must not match an excluded workload. Without included workloads, the set has no inclusion restriction.
1. In the Cloudflare dashboard, go to **Cloud Workload Security** > **Policy sets**.
The policy filter still applies within the policy set's workload scope. A workload match does not bypass a policy filter.
## Attach the set to a deployment
1. In the Cloudflare dashboard, go to **Cloud Workload Security** > **Deployments** and open the deployment.
### Default mode and enforcement
A policy matches when its policy set's workload scope and its filter both match. The deployment default mode applies when no policy matches. A `false` Rego result is a failed check, not an unmatched request.
For example, a matching policy with **Enforce** off does not block a `false` result, even with _Default block_. Another enforcing policy can still block the request.
Send one request that passes your policy and one that fails it. Confirm the failing request returns a CWS block response when **Enforce** is on.
To change an existing resource, open it from its list and select **Save** after editing. Changes to a policy or policy set affect deployments that reference it.
# Guides
Use these guides to configure Cloud Workload Security resources:
- [Configure policies](/cloudflare-one/cloud-workload-security/guides/configure-policies/): define workloads, write policies, and attach policy sets to deployments.
- [Manage traffic scope](/cloudflare-one/cloud-workload-security/guides/manage-traffic-scope/): configure domain access control lists and manage Basic Auth secrets.
- [Manage policy reference resources](/cloudflare-one/cloud-workload-security/guides/policy-reference/): create reusable Rego modules, metadata, and tenant structures.
To understand how CWS validates requests, refer to [Request Validation](/cloudflare-one/cloud-workload-security/concepts/request-validation/). To connect your first proxy and test a policy, follow [Get started](/cloudflare-one/cloud-workload-security/get-started/).
# Manage traffic scope
import { DashButton, Steps } from "~/components";
Domain access control lists (ACLs) control which destinations a deployment can reach. Use the Basic Auth page to manage credentials and their secrets. To understand how these controls relate to request policies, refer to [Request Validation](/cloudflare-one/cloud-workload-security/concepts/request-validation/).
You need access to manage Cloud Workload Security in your account.
## Create a domain ACL
A domain ACL contains domain-specific actions and a default action. The default action applies when no domain entry matches.
1. In the Cloudflare dashboard, select your account and go to **Cloud Workload Security** > **Traffic scope** > **Domain ACLs**.
Use `example.com` for an exact domain match. Use `.example.com` to match the parent domain and its subdomains.
## Attach a domain ACL
1. In the Cloudflare dashboard, go to **Cloud Workload Security** > **Deployments** and open the deployment.
An ACL allow decision permits the connection. CWS policies can still block API requests on that connection.
To detach the list, select **None** in **Domain ACL** and select **Save**. Detach an ACL from its deployments before deleting it.
## Create a Basic Auth credential
Basic Auth credentials are separate from the Cloudflare API token used in your proxy configuration.
1. In the Cloudflare dashboard, go to **Cloud Workload Security** > **Traffic scope** > **Credentials** > **Basic Auth**.
The username is read-only after creation. Open the credential to manage its secrets.
## Rotate a secret
Use this procedure for a credential your clients already use.
1. In **Basic Auth**, open the credential.
2. In **Secrets**, select **Add a secret**. Enter and confirm the new password, set an optional expiration, and select **Add a secret**.
3. Allow the deployment configuration to refresh before updating clients to use the new password. Verify requests from those clients before deleting the old secret.
4. For the old secret, select **Delete** and confirm the deletion.
The secret list displays creation and expiration information. It does not display stored passwords.
# Manage policy reference resources
import { DashButton, Steps } from "~/components";
Use **Policy reference** resources to share code and data between policies. You need access to manage Cloud Workload Security in your account.
## Create a Rego module
Rego modules hold reusable library code under `lib.`. Write each policy's `policy.` package and `valid` rule in the policy editor.
1. In the Cloudflare dashboard, select your account and go to **Cloud Workload Security** > **Policy reference** > **Rego modules**.
To call the library from a policy, import it and reference its rule:
```txt title="Policy source"
package policy.private_bucket
import data.lib.bucket_rules
default valid := false
valid if {
bucket_rules.private
}
```
The policy also requires a filter to select the intended operation. Refer to [Configure policies](/cloudflare-one/cloud-workload-security/guides/configure-policies/).
## Create Rego metadata
Metadata stores reusable JSON values. An import path such as `metadata.bucket_rules` exposes the value as `data.metadata.bucket_rules` in Rego.
1. In the Cloudflare dashboard, go to **Cloud Workload Security** > **Policy reference** > **Rego metadata**.
`.
3. In **Data**, enter valid JSON. For example:
```json
{
"require_private_buckets": true
}
```
4. Select **Add Rego metadata** to save the value.
For this example, a policy can read `data.metadata.bucket_rules.require_private_buckets`. Update the metadata to change the shared value without editing each policy.
## Create a tenant structure
Tenant structures describe an AWS or Cloudflare resource hierarchy. An optional **Package path** exposes the hierarchy to Rego, such as `data.tenant.aws.production`.
1. In the Cloudflare dashboard, go to **Cloud Workload Security** > **Policy reference** > **Tenant structures**.
` or `tenant.cloudflare.`, matching your selected application.
4. In **Nodes**, select **Import nodes** and choose a `.json` file. Review the imported nodes in **Table view** or **JSON view**.
5. Select **Add tenant structure** to save the structure and nodes.
### Node import format
Use a JSON object keyed by each node's native resource ID. Each value contains `node_kind`, an optional `name`, and `parent` for a child node. Do not add a `native_id` field inside the value.
This AWS example places an account under a root. Replace the example IDs with your resource IDs:
```json title="nodes.json"
{
"r-example": {
"node_kind": "root",
"name": "Example organization"
},
"123456789012": {
"node_kind": "account",
"name": "Production account",
"parent": "r-example"
}
}
```
AWS supports `root`, `ou`, and `account` nodes. Cloudflare supports `org`, `account`, and `zone` nodes. Native IDs must be unique, and each parent must exist in the structure.
### Edit nodes
Open an existing tenant structure to add, edit, or delete nodes in **Table view**. Select **Save** to apply the changes. **JSON view** is read-only.
Policies read mounted nodes by native ID. For example, `data.tenant.aws.production.nodes["123456789012"]` returns the example account node.
# Legal
This software is made available as a "Beta Service" under the agreement applicable to your Cloudflare account. By downloading, installing, or using this software, you agree that your use is governed by that agreement. Depending on your subscription type, the applicable agreement is either the Cloudflare Self-Serve Terms of Service (https://www.cloudflare.com/terms/), the Cloudflare Enterprise Terms (https://www.cloudflare.com/enterpriseterms/), or a separately negotiated written agreement between you and Cloudflare. Cloudflare processes personal information as described in its Privacy Policy (https://www.cloudflare.com/privacypolicy/). If you do not agree to the applicable terms, do not download, install, or use this software.
## Third-party licenses
Review the [Third-party licenses](/cloudflare-one/cloud-workload-security/legal/third-party-licenses/) for the Cloud Workload Security proxy.
# Third-party licenses
import { LinkButton } from "~/components";
The Cloud Workload Security (CWS) proxy includes third-party Rust and Go dependencies. These notices cover the Linux ARM64 build with default Cargo features.
## License notices
The full notice file contains license text, copyright notices, and attributions. [View the third-party license notices](/cloudflare-one/cloud-workload-security/legal/third-party-licenses.txt) or download the file.
Download license notices
## Acknowledgments
> This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit. (http://www.openssl.org/)
> This product includes cryptographic software written by Eric Young (eay@cryptsoft.com)
> This product includes software written by Tim Hudson (tjh@cryptsoft.com)
# Platform
Cloud Workload Security (CWS) is available in Beta. Manage CWS resources in the Cloudflare dashboard after selecting your account.
Your account must have a Zero Trust subscription. The Zero Trust Free plan is sufficient.
You need permission to manage the resources you change. The proxy also needs a Cloudflare API credential for the same account. Refer to [API connection and authentication](/cloudflare-one/cloud-workload-security/configuration/#api-connection-and-authentication) for API token and Global API Key setup.
## Limits
CWS applies these standard resource and relationship limits.
### Entity quotas
Quotas apply per account unless otherwise indicated:
| Entity | Standard limit |
|---|---:|
| Deployments | 5 |
| Policy sets | 10 |
| Workloads | 10 |
| Domain ACLs | 10 |
| Basic Auth credentials | 10 |
| Policies | 50 |
| Rego modules — shared libraries | 10 |
| Rego metadata documents | 10 |
| Tenant structures | 5 |
| Tenant nodes per structure | 100 |
### Per-entity and relationship limits
The following limits apply to individual resources and relationships:
| Constraint | Standard limit |
|---|---:|
| Policy sets attached to a deployment | 10 |
| Basic Auth credentials attached to a deployment | 10 |
| Policies in a policy set | 50 |
| Included workloads in a policy set | 10 |
| Excluded workloads in a policy set | 10 |
| Entries in a domain ACL | 100 |
| Stored secrets per Basic Auth credential, including expired secrets | 10 |
| Tags per deployment, policy, policy set, or workload | 10 |
| Domain ACLs attached to a deployment | 1 |
| Roots in a tenant structure | 1 |
## Proxy deployment options
You run the CWS proxy in your environment. Choose a location that your cloud API clients can reach, and install the `cws-proxy` package using APT or DNF.
### Local machine
Run the proxy and client on the same Linux machine or Linux virtual machine (VM) to test a guardrail. Follow [Set up the proxy locally](/cloudflare-one/cloud-workload-security/get-started/#set-up-the-proxy-locally) for the empty-R2-bucket walkthrough.
### CI/CD runner
Run the proxy alongside jobs in a continuous integration and continuous delivery (CI/CD) pipeline. This applies guardrails to cloud API requests made by applications and deployment scripts.
For this pattern, the runner needs:
- A proxy process that is ready before jobs make cloud API requests. After starting the proxy, check the proxy logs for `remote_config_loaded` and `action_mapper_loaded` to confirm startup.
- The API credential supplied through the CI secret store, and a certificate authority (CA) certificate and private key available to the proxy process.
- Client tools configured to use the proxy endpoint and trust its CA certificate. Apply client proxy settings to the cloud-request steps, separately from the proxy process.
Manage proxy startup and cleanup through your runner's process or service lifecycle. For the `cf` client settings, refer to [Route the CLI through the proxy](/cloudflare-one/cloud-workload-security/get-started/#route-the-cli-through-the-proxy).
### Application host or container
Run the installed proxy as a managed process on a Linux VM or application host. For containers, use a Linux environment with APT or DNF and provide the proxy's configuration, credentials, and CA files.
Configure your application to use the proxy through its supported proxy and CA trust settings. Keep the proxy running while the application makes cloud API requests.
### Shared proxy host
Run a proxy on a host reachable by multiple applications or pipeline jobs. Set `proxy.listen_addr` to a private IP address and port on that host, then configure clients with the corresponding proxy URL.
Restrict network access to the intended clients. Each client needs the CA certificate for trust. Keep the matching private key on the proxy host.
For package installation, refer to [Get started](/cloudflare-one/cloud-workload-security/get-started/). For listener, authentication, upstream proxy, and cache settings, refer to [Proxy configuration](/cloudflare-one/cloud-workload-security/configuration/).
## Traffic requirements
Policies evaluate API requests routed through your CWS proxy. Creating a deployment does not route application traffic automatically.
Clients must use the proxy and trust its CA certificate. Keep the matching private key on the proxy host.
Clients on other hosts or in separate containers need a reachable proxy address. A loopback address such as `127.0.0.1` only reaches processes in the same network namespace.
Domain ACLs control destination access separately from request policies. An allowed destination does not bypass policy checks.
## Configuration refresh
The proxy refreshes its deployment configuration at the interval configured in `cws.api_poll_interval_secs`. The minimum interval is `30` seconds.
After saving policy, policy set, or deployment changes, allow a refresh interval before verifying their effect. Restart the proxy after changing its local configuration file.
If changes do not affect requests, follow [Saved changes do not affect requests](/cloudflare-one/cloud-workload-security/troubleshooting/#saved-changes-do-not-affect-requests).
## Request authentication
Cloud provider authentication still applies to requests sent through the proxy. The proxy uses its Cloudflare API credential to load deployment configuration. Clients still need their own cloud provider credentials.
To identify the source of a block response, follow [Requests receive an unexpected 403](/cloudflare-one/cloud-workload-security/troubleshooting/#requests-receive-an-unexpected-403).
## Licenses
For the proxy's Beta terms, license notices, and acknowledgments, refer to [Legal](/cloudflare-one/cloud-workload-security/legal/).
# Troubleshooting
import { Steps } from "~/components";
Diagnose Cloud Workload Security (CWS) proxy, client, and policy issues. This guide covers the proxy setup in [Get started](/cloudflare-one/cloud-workload-security/get-started/).
:::note
For questions about the Open Beta, contact [cloud-workload-security-open-beta@cloudflare.com](mailto:cloud-workload-security-open-beta@cloudflare.com).
:::
Use the sections to identify your symptom and verify the fix. Read the logs from the terminal or service running the proxy. For the relevant fields, refer to [Read proxy logs](/cloudflare-one/cloud-workload-security/troubleshooting/#read-proxy-logs).
## Proxy does not start
### Symptoms
The proxy exits before accepting connections. The terminal reports a configuration, file, or listener error.
### Possible causes and solutions
#### Invalid local configuration
Validate the configuration file without starting the proxy:
```sh
cws-proxy --config config.yaml --config-test
```
Successful validation prints:
```txt output
CWS proxy configuration is valid
```
Correct the reported YAML or schema error, then validate again. Use the `cws`, `proxy`, and `redis` settings from [Proxy configuration](/cloudflare-one/cloud-workload-security/configuration/). Unknown settings are rejected.
This check validates local configuration. It does not verify the API token, fetch the deployment, or prove the listener can start.
#### Unavailable certificate files or listener address
The proxy needs a certificate authority (CA) certificate and its matching private key. Confirm that `proxy.tls_interception.ca_cert` and `ca_private_key` point to files the proxy process can read. Use absolute paths if you start the proxy from another directory.
Check that `proxy.listen_addr` contains an IP address and port, such as `127.0.0.1:8080`. The address must be available on the proxy host, and another process must not already occupy the port.
#### Package or command is unavailable
If `cws-proxy` is not found, confirm that package installation succeeded in the environment that starts the proxy. Check that the installed command is on that process's `PATH`.
If the operating system cannot execute the command, check that the package is compatible with your Linux distribution and CPU architecture. Refer to [Install the proxy](/cloudflare-one/cloud-workload-security/get-started/#install-the-proxy) for the package setup and available-command check.
### Verify the fix
Start the proxy with `cws-proxy --config config.yaml`. Wait for `remote_config_loaded` and `action_mapper_loaded`, then retry your client request. If configuration loading fails, follow [Proxy cannot load the deployment](/cloudflare-one/cloud-workload-security/troubleshooting/#proxy-cannot-load-the-deployment).
## Proxy cannot load the deployment
### Symptoms
The proxy does not reach `remote_config_loaded`. Logs report a missing credential, an unsuccessful API response, or configuration fetch retries.
### Possible causes and solutions
#### Token environment variable is missing or empty
`cws.api_token_env` contains an environment variable name, not a token value. For the setup in Get started, the name is `CWS_DEPLOYMENT_TOKEN`.
In the terminal that starts the proxy, check whether the variable is populated without printing the token:
```sh
if [ -n "${CWS_DEPLOYMENT_TOKEN:-}" ]; then
printf '%s\n' "CWS_DEPLOYMENT_TOKEN is set"
else
printf '%s\n' "CWS_DEPLOYMENT_TOKEN is not set or is empty"
fi
```
The `cws_api_token_missing` error means the configured variable is missing or empty. A service or container must receive the variable in its own process environment. Setting it in the client terminal does not set it in the proxy process.
This presence check does not verify token validity. After correcting the proxy process environment, restart the proxy.
#### Account, deployment, or permission mismatch
Confirm that `cws.account_id` and `cws.deployment_id` identify the intended deployment. The API token must have the **Cloud Workload Security Deployment** permission for that account.
For `401` or `403` API responses, check the token's validity and account permissions. For `404`, check the account and deployment IDs and whether the deployment still exists. Refer to [Create the proxy API token](/cloudflare-one/cloud-workload-security/get-started/#create-the-proxy-api-token).
#### API connectivity or trust failure
For the API, use `https://api.cloudflare.com/client/v4` as `cws.api_base_url`. Check that the proxy host can resolve and reach that origin. Use the logged connection, timeout, or certificate error to identify the failing connection.
:::caution
Do not set client `HTTP_PROXY` or `HTTPS_PROXY` variables in the proxy process environment.
:::
If your network inspects Transport Layer Security (TLS), configure its approved trust roots through `proxy.tls_interception.extra_root_cas`. Client `NODE_EXTRA_CA_CERTS` does not change the proxy's outbound trust.
#### Deployment configuration cannot be parsed or prepared
Local configuration validation does not validate the downloaded deployment bundle. If the API returns successfully but the proxy cannot parse or compile the configuration, [contact the Open Beta team](/cloudflare-one/cloud-workload-security/troubleshooting/#contact-the-open-beta-team) with the proxy version and sanitized error.
### Verify the fix
Restart after changing local configuration or the process environment. Confirm `remote_config_loaded` and `action_mapper_loaded` before retrying your client. Transient startup fetch failures can retry, but a missing credential or invalid configuration needs correction.
## Client connections or certificate verification fail
### Symptoms
The client reports a refused connection or a certificate verification error. It cannot complete a request through the proxy.
### Possible causes and solutions
#### Client uses an unreachable proxy address
Compare the client's proxy address with `proxy.listen_addr`. In the local setup, both use `127.0.0.1:8080`, and `HTTPS_PROXY` uses the `http://` scheme:
```sh
export HTTP_PROXY="http://127.0.0.1:8080"
export HTTPS_PROXY="http://127.0.0.1:8080"
```
A loopback address only reaches the proxy within the same host or network namespace. A client in another container or host needs a reachable proxy address. Confirm that the proxy has finished startup before retrying.
#### Client does not trust the proxy CA
Use the CA files configured for your proxy. Substitute their paths if they differ from `ca-cert.pem` and `ca-key.pem`.
1. In the proxy terminal, inspect the CA certificate's validity dates:
```sh
openssl x509 -in ca-cert.pem -noout -dates
```
Confirm that the current time falls between `notBefore` and `notAfter`. Correct an expired certificate or an incorrect system clock.
2. Compare the public-key digests of the certificate and private key:
```sh
openssl x509 -in ca-cert.pem -noout -pubkey | openssl pkey -pubin -outform DER | openssl dgst -sha256
openssl pkey -in ca-key.pem -pubout -outform DER | openssl dgst -sha256
```
The digests must match. These commands print public-key digests, not the private key. If they differ, configure the matching CA certificate and key.
3. In the client terminal, configure trust in the CA certificate. For the Node.js-based `cf` client, set:
```sh
export NODE_EXTRA_CA_CERTS=""
```
Start a new client process after changing its trust settings. Keep the private key on the proxy host. Other clients need their own supported CA trust configuration.
For CA setup, refer to [Prepare a certificate authority](/cloudflare-one/cloud-workload-security/get-started/#prepare-a-certificate-authority).
### Verify the fix
Retry a read-only request through the proxy, such as the managed-domain list request in [Verify the guardrail](/cloudflare-one/cloud-workload-security/get-started/#verify-the-guardrail). Confirm that connection and certificate verification succeed. Diagnose an HTTP error separately using [Requests receive an unexpected 403](/cloudflare-one/cloud-workload-security/troubleshooting/#requests-receive-an-unexpected-403).
## Requests expected to be blocked succeed
### Symptoms
A client completes a request that your guardrail should block. The proxy may have no corresponding request record, or may record an allowed decision.
### Possible causes and solutions
#### Client bypasses the proxy
Creating a deployment does not route traffic automatically. Confirm that the client process receives the intended proxy settings. Check that `NO_PROXY` and `no_proxy` do not bypass the target origin.
For the documented `cf` setup, use Node.js 24.5 or later. Check the client terminal's version:
```sh
node --version
```
Set `NODE_USE_ENV_PROXY=1` before starting the client. Refer to [Route the CLI through the proxy](/cloudflare-one/cloud-workload-security/get-started/#route-the-cli-through-the-proxy).
A connection record alone does not prove that CWS evaluated an HTTP request. Check for the request decision. An unclassified destination can pass through as a raw tunnel without request-policy evaluation.
#### Policy is not attached, in scope, or enforcing
Compare `cws.deployment_id` with the deployment you edited. Verify the configuration path from deployment to policy:
1. Confirm that the deployment includes the intended policy set.
2. Confirm that the policy set includes the intended policy and has **Enforce** turned on for it.
3. Compare the request with the included and excluded workloads. An empty inclusion list includes all requests before exclusions. An excluded workload match removes the request from the set's scope.
4. Check the policy filter against the request's application, service, operation, and other selected fields. Both workload scope and policy filter must match.
For the editing procedure, refer to [Configure policies](/cloudflare-one/cloud-workload-security/guides/configure-policies/). After a configuration refresh, inspect `request.policy_sets` for the evaluated policies, their decisions, and their `enforce` values.
An enforcing policy that returns `false` blocks a matching request. A non-enforcing policy can record a denial without blocking. The deployment **Default mode** applies when no policy matches. For policy evaluation errors, also inspect **On error action** and the error outcome.
#### Request or identity differs from the policy's assumptions
Confirm that the client sends the operation and request body your Rego check expects. If the proxy reports `request_body_inspection_skipped_too_large`, body inspection was skipped and `input.http.request.body` is `null`. A body-dependent check can produce a different result.
If your filters depend on a Basic Auth identity, check the configured credential and secret expiration or rotation. Refer to [Manage traffic scope](/cloudflare-one/cloud-workload-security/guides/manage-traffic-scope/). The deployment API token does not identify your client or replace its cloud-provider credentials.
### Verify the fix
Use a controlled test request that should pass and another that should fail. Confirm the expected decision and evaluated policy in the proxy logs. For the empty-R2-bucket walkthrough, follow [Verify the guardrail](/cloudflare-one/cloud-workload-security/get-started/#verify-the-guardrail), including restoring private access if the blocking test succeeds.
## Requests receive an unexpected 403
### Symptoms
The client receives HTTP `403`, a `CWS.Error` response, or a rejected CONNECT request.
### Possible causes and solutions
#### Domain ACL blocks the connection
A domain access control list (ACL) can reject CONNECT before request-policy evaluation. Look for `domain_acl_denied_connect`. Inspect the ACL attached to your deployment and its default action.
Check the destination pattern: `example.com` is an exact match, while `.example.com` includes the parent domain and its subdomains. Correct the entry for the intended destination using [Manage traffic scope](/cloudflare-one/cloud-workload-security/guides/manage-traffic-scope/).
An ACL allow decision permits the connection. It does not bypass request policies.
#### CWS rejects the request
`CWS.Error` identifies a CWS request denial. Inspect the related request logs for the reason and evaluated policies. If a matching policy denies, compare its Rego check with the request. Another enforcing policy can block even when one policy passes.
If no policy matches, inspect the deployment **Default mode** and intended request scope. If an evaluation error occurs, inspect the error and deployment **On error action**. Correct the underlying configuration or policy using [Configure policies](/cloudflare-one/cloud-workload-security/guides/configure-policies/).
If application classification fails before policy evaluation, the logs may report that failure instead of a normal policy decision. Include that error when [contacting the Open Beta team](/cloudflare-one/cloud-workload-security/troubleshooting/#contact-the-open-beta-team).
#### Cloud provider rejects an allowed request
If `request.outcome` is `allowed` and the response record has `upstream_status: 403`, the cloud provider rejected the forwarded request. Check the client's provider credentials, resource permissions, and provider error message.
The CWS deployment token loads proxy configuration. It does not grant access to cloud-provider resources.
### Verify the fix
Retry an authorized, in-scope request. Confirm the proxy decision and the provider response separately. A `403` status alone does not identify which layer rejected the request.
## Saved changes do not affect requests
### Symptoms
You save a policy, policy set, or deployment change, but subsequent requests behave as before.
### Possible causes and solutions
#### Proxy has not refreshed the intended deployment
Confirm that the running proxy uses the account and deployment you edited. Allow the interval configured in `cws.api_poll_interval_secs` before testing again. Its minimum is `30` seconds.
Look for `polling_remote_config` and any fetch or prepare failure. `remote_config_updated` is not emitted for every applied policy change. Verify changes through subsequent request decisions and evaluated policies.
#### Refresh fails and the proxy retains its previous configuration
`remote_config_fetch_failed_keeping_current` and `remote_config_prepare_failed_keeping_current` mean the refresh failed. The running proxy retains its previous valid deployment configuration.
For fetch failures, check [API access and connectivity](/cloudflare-one/cloud-workload-security/troubleshooting/#proxy-cannot-load-the-deployment). For prepare failures, review the reported configuration error and [contact the Open Beta team](/cloudflare-one/cloud-workload-security/troubleshooting/#contact-the-open-beta-team) if it persists. A saved dashboard change alone does not prove that the proxy applied it.
#### Local configuration or process environment changed
Restart the proxy after changing its local configuration file or credential environment. A configuration poll does not reload those local settings.
### Verify the fix
After a successful refresh or restart, repeat the controlled policy test. Confirm the expected policy set, enforcement state, and request decision in the logs.
## Requests receive an Action Mapper 503
### Symptoms
The response has HTTP `503` and the message `Action Mapper application data is unavailable`. It can also contain `x-cws-proxy-err: Action Mapper unavailable`.
### Possible causes and solutions
#### Application data is unavailable or invalid
Action Mapper classifies API requests for policy evaluation. The proxy rejects inspected HTTP traffic when it cannot use a complete, valid application data set. A successful deployment configuration load does not prove this data is ready.
Look for `initial_action_mapper_fetch_failed`, `initial_action_mapper_load_failed`, or `initial_action_mapper_incomplete` during startup. During operation, check `action_mapper_application_pending`, `action_mapper_poll_failed_keeping_current`, and any `action_mapper_degraded_denied_connect` or `action_mapper_degraded_denied_request` events.
Use the reported error to check API connectivity and authentication. The proxy retries application-data loading. If validation failures persist, [contact the Open Beta team](/cloudflare-one/cloud-workload-security/troubleshooting/#contact-the-open-beta-team) with sanitized log excerpts.
### Verify the fix
At startup, confirm `action_mapper_loaded`. After a runtime failure, confirm recovery in the mapper logs and retry a read-only request. The request should no longer return the Action Mapper unavailable response. An unrelated `503` needs investigation using its own error and logs.
## Requests receive 421 Misdirected Request
### Symptoms
The client receives HTTP `421`. The proxy logs `request_host_tunnel_mismatch`.
### Possible causes and solutions
#### Request destination differs from the CONNECT destination
Check that the request URL, `Host` header, and CONNECT destination agree on the host and effective port. Inspect any client configuration or intermediary that overrides the destination or rewrites `Host`.
Configure the client to send the intended destination consistently. Retain the proxy's destination checks. Refer to the logged `request_authority`, `context_authority`, and `tunnel_authority` fields to identify the disagreement.
### Verify the fix
Start a new client connection and retry the request. Confirm that it no longer produces `421` or `request_host_tunnel_mismatch`, then inspect its policy decision and provider response.
## Dashboard resources cannot be loaded or saved
### Symptoms
The dashboard reports a loading or saving error. A policy or workload form may report invalid filter or Rego input.
### Possible causes and solutions
#### Wrong account, missing permission, or connection failure
Confirm that the dashboard uses the account containing your resources. Check that your account role permits the resource operation. The proxy's deployment token and your dashboard permissions serve different purposes.
For a loading error, check your connection and reload the page. If a resource is missing, confirm that it still exists in the selected account.
#### Invalid filter or Rego source
Correct the displayed field errors. Filters must use supported Wirefilter fields and operators. Put request-body checks in Rego, using `input.http.request.body`.
For dashboard policies, declare a package under `policy.` and a Boolean `valid` rule. Check the syntax and imported library or metadata paths. Refer to [Configure policies](/cloudflare-one/cloud-workload-security/guides/configure-policies/) and [Manage policy reference resources](/cloudflare-one/cloud-workload-security/guides/policy-reference/).
If the operation still fails, [contact the Open Beta team](/cloudflare-one/cloud-workload-security/troubleshooting/#contact-the-open-beta-team) with the sanitized API error code and message, when available. Do not treat a failed save as an applied configuration change.
### Verify the fix
Confirm that the resource saves and reloads successfully. For a policy change, allow a configuration refresh and verify its effect through the proxy.
## Read proxy logs
The configuration in Get started uses JSON logging at `INFO`. Read records from the proxy process that handled the request. Use the timestamp and `cws.request_id`, when present, to relate records.
For evaluated HTTP requests, inspect these events and fields:
| Event or field | What it tells you |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `remote_config_loaded` | Deployment configuration loaded at startup. |
| `action_mapper_loaded` | Application data loaded at startup. |
| `request.outcome` | CWS allowed or denied the evaluated request. An allowed decision does not guarantee provider success. |
| `request.outcome_reason` | Reason for a denied request, when present. |
| `request.policy_sets` | JSON-encoded audit of matching policy sets and evaluated policies, including `enforce` and each policy's decision. |
| `request.evaluation_result` | Evaluation result, when available. Use the per-policy audit to understand which policy controlled the outcome. |
| `response` | Response record containing `status` and, for a provider response, `upstream_status`. |
| `request.context` | Redacted policy input for diagnosis. It can be truncated and is not a complete copy of policy input. |
JSON-encoded log values can be truncated. A truncated audit is not a complete policy list. CONNECT denials and failures before policy evaluation can have their own events. The absence of a normal request record does not, by itself, prove that the client bypassed the proxy.
## Contact the Open Beta team
If the issue persists, contact [the Open Beta team](mailto:cloud-workload-security-open-beta@cloudflare.com) with:
- The failure timestamp and timezone.
- The proxy version, operating system, and CPU architecture.
- The client name, version, and error message.
- The account, deployment, and relevant policy or policy-set IDs.
- The target API operation and expected versus actual result.
- Short, sanitized log excerpts, `cws.request_id`, and any response reference, when available.
To collect the proxy version, run:
```sh
cws-proxy --version
```
Include only the relevant configuration keys. Remove API tokens, passwords, private keys, and credential-bearing headers. Redact cookies, sensitive URLs, request bodies, and metadata before sharing. Review logs even when the proxy has already redacted some fields.
# DLP settings
DLP settings allow you to configure account-level settings that apply across all DLP profiles and policies. These settings are located in **Zero Trust** > **Data loss prevention** > **DLP settings** in the [Cloudflare dashboard](https://dash.cloudflare.com/).
## Optical Character Recognition (OCR)
Optical Character Recognition (OCR) analyzes and interprets text within image files. When turned on, OCR can detect sensitive data within images your users upload.
OCR supports scanning `.jpg`/`.jpeg` and `.png` files between 4 KB and 1 MB in size. Text is encoded in UTF-8 format, including support for non-Latin characters.
To turn on OCR:
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Data loss prevention** > **DLP settings**.
2. Turn on **Optical Character Recognition (OCR)**.
## AI context analysis
:::note
AI context analysis only supports Gateway HTTP and HTTPS traffic.
:::
AI context analysis uses a pretrained model to analyze surrounding context and adjust the confidence level of a detection. For example, a number that matches a credit card pattern may receive a lower confidence score if it appears in a context where credit card numbers are unlikely. DLP will log any matches that are above your confidence threshold.
DLP redacts any matched text, then converts the surrounding context into a vector embedding and submits it to [Cloudflare Workers AI](/workers-ai/). Vector embeddings (not raw text) are stored in user-specific private namespaces for up to six months, along with hit count and the [false positive/negative report](/cloudflare-one/data-loss-prevention/dlp-policies/logging-options/#report-false-and-true-positives-to-ai-context-analysis).
To turn on AI context analysis:
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Data loss prevention** > **DLP settings**.
2. Turn on **AI context analysis**.
3. [Add the profile](/cloudflare-one/data-loss-prevention/dlp-policies/#2-create-a-dlp-policy) to a DLP policy.
4. When configuring the DLP policy, turn on [payload logging](/cloudflare-one/data-loss-prevention/dlp-policies/logging-options/#log-the-payload-of-matched-rules).
AI context analysis results will appear in the payload section of your [DLP logs](/cloudflare-one/data-loss-prevention/dlp-policies/#4-view-dlp-logs). To improve future detections of sensitive data, you need to [report false and true positives](/cloudflare-one/data-loss-prevention/dlp-policies/logging-options/#report-false-and-true-positives-to-ai-context-analysis).
## Payload encryption key
Before you begin logging DLP payloads, you will need to set a DLP payload encryption public key. DLP uses public-key encryption so that matched sensitive data is readable only by you — Cloudflare does not have access to your private key and cannot decrypt your logs.
### Generate a key pair
You will generate two keys: a public key (uploaded to Cloudflare to encrypt log data) and a private key (kept by you to decrypt log data later).
To generate a public/private key pair in the command line, refer to [Generate a key pair](/waf/managed-rules/payload-logging/command-line/generate-key-pair/).
### Upload the public key to Cloudflare
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Data loss prevention** > **DLP settings**.
2. In the **DLP Payload Encryption public key** field, paste your public key.
3. Select **Save**.
:::note
The matching private key is required to view logs. If you lose your private key, you will need to [generate](#generate-a-key-pair) and [upload](#upload-the-public-key-to-cloudflare) a new public key. The payload of new requests will be encrypted with the new public key. Previously logged data encrypted with the old key will be permanently unreadable.
:::
## Payload log masking
You can control how sensitive data appears in your DLP payload logs by selecting a masking level. This determines how much of the matched content is visible after decryption.
To configure payload log masking:
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Data loss prevention** > **DLP settings**.
2. Go to the **Payload log masking** card.
3. Choose one of the following masking levels:
- **Full Mask (default):** Masks the match while preserving character count and visual formatting. For example, a Social Security Number appears as `***-**-****`.
- **Partial Mask:** Reveals 25% of the matched content while masking the remainder. For example, `***-**-6789`.
- **Clear Text:** Stores the full, unmasked match for detailed investigation. For example, `123-45-6789`.
:::note
The masking level is applied at detection time, before the payload is encrypted. Your team will see the selected format when they decrypt the log with your private key.
:::
:::caution
The selected masking level applies to all sensitive data matches found within a payload window — not just the match that triggered the policy.
:::
## Migrate from profile-level settings
OCR and AI context analysis are available at both the profile level (**Data loss prevention** > **Profiles**) and the account level (**Data loss prevention** > **DLP settings**) during the migration period. When both are configured, DLP uses OR logic for evaluation. A match occurs if either the profile-level or account-level setting would trigger a detection.
Profile-level OCR and AI context analysis settings will be deprecated in a future release. We recommend migrating to account-level settings in **DLP settings** to ensure consistent behavior across all profiles.
To migrate:
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Data loss prevention** > **DLP settings**.
2. Turn on **Optical Character Recognition (OCR)** and/or **AI context analysis** as needed.
3. Go to **Zero Trust** > **Data loss prevention** > **Profiles**.
4. For each profile with OCR or AI context analysis enabled, edit the profile and turn off the profile-level settings.
5. Select **Save profile**.
# Data loss prevention
import { GlossaryDefinition, Render } from "~/components";
:::note[Availability]
Available as an add-on to Zero Trust Enterprise plans.
Users on Zero Trust Free and Pay-as-you-go plans can use the [Financial Information](/cloudflare-one/data-loss-prevention/dlp-profiles/predefined-profiles/#financial-information) and [Social Security, Insurance, Tax, and Identifier Numbers](/cloudflare-one/data-loss-prevention/dlp-profiles/predefined-profiles/#social-security-insurance-tax-and-identifier-numbers) predefined profiles, [payload logging](/cloudflare-one/data-loss-prevention/dlp-policies/logging-options/#log-the-payload-of-matched-rules), and [false positive reporting](/cloudflare-one/data-loss-prevention/dlp-policies/#report-false-positives).
:::
1. In the Cloudflare dashboard, go to **Zero Trust** > **Insights & Logs** > **Dashboards**.
Use **Request** to see data sent to destinations and **Response** to see data received from them. **Unknown** includes HTTP bodies without a recorded traffic direction. Remove the filter to include all traffic directions. Request and response bodies are counted separately.
The selected time range and traffic direction also apply when you open an entry to investigate it.
## Learn from the data
Start with the account summary for the broad picture. From there, select a detection entry to see where it appeared, the matching profiles, and whether policy enforcement was applied.
### Start with the account summary
The summary cards describe detections within your selected time range and traffic direction:
- **Total detections**: Each entry counts once per HTTP body.
- **Unique traffic with detections**: HTTP bodies with at least one detection, counted once.
- **Entries detected**: Unique DLP entries matched in the selected scope.
For example, one request body that matches two different entries contributes two detections to **Total detections** and one body to **Unique traffic with detections**. These counts do not tell you how many individual sensitive values the body contains.
Use **Detections by data type** to see which entries account for the most detections. Use **Policy coverage** to find entries that may need policy review.
### Find sensitive data
Next, use the detection table to decide what to investigate. Compare entries, then inspect their profiles and destinations. The table contains one row per detection entry found in sampled traffic. Entries without detections do not appear.
Use these fields to compare entries:
| Field | Meaning |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Entry | The DLP detection entry found in sampled traffic. |
| Profiles | The profiles associated with the detection. |
| Detections | HTTP bodies where this entry was detected at least once. Multiple occurrences of the same entry in one body count once. |
| URL destinations | The number of distinct destinations associated with the entry. |
| Confidence (H/M/L) | Observed detections grouped by high, medium, and low confidence. |
| Policy coverage | Whether matching profiles were selected for policy enforcement when the bodies were scanned. Refer to [Find policy coverage gaps](#find-policy-coverage-gaps). |
| Last seen | When the entry was most recently observed during the selected time range. |
All times are reported in UTC.
The same body can contribute confidence counts through more than one matching profile. Confidence counts can therefore add up to more than the number of detected bodies, even within a single confidence level.
### Trace where data goes
After you choose an entry, select it to see where it appeared. The detail view shows detections and confidence over time, followed by the destinations and applications associated with that entry.
Destinations group URLs by host and a normalized path. For example, paths such as `/users/12345` can be grouped under `/users/{id}`. Each destination includes detection counts, confidence, traffic direction, and the last detection time.
Expand a destination to review a selection of matched URLs, their detection counts, and when they were last observed. Use these details to check whether the activity involves an expected application or a destination that needs further investigation.
For example, a detection associated with an unfamiliar file-sharing destination may warrant a closer look. Check whether that destination is approved for the data involved before deciding whether to create a policy.
:::caution
Matched URLs can contain sensitive values in their paths or query strings. Review them before sharing results.
:::
The dashboard shows detection metadata. Original request and response bodies are not stored.
### Find policy coverage gaps
Policy coverage helps you find detections that may need a closer look. A detection counts as covered when at least one matching DLP profile was selected for policy enforcement when the HTTP body was scanned.
Coverage does not confirm that the complete Gateway policy matched or that Gateway logged or blocked the traffic. The dashboard groups coverage into three statuses:
| Status | Meaning |
| -------------- | --------------------------------------------------------------------------------- |
| Covered | Each detection had at least one matching profile selected for enforcement. |
| Partly covered | Some detections had a matching profile selected for enforcement and some did not. |
| Not covered | No detections had a matching profile selected for enforcement. |
Start with entries that are **Not covered** or **Partly covered**, then review their destinations and the relevant policies. A coverage gap is a reason to investigate, not a recommendation to block every detection.
## Create a DLP policy
Once you understand what data was detected and where it appeared, turn those findings into a policy that fits your traffic. Focus on the data types and destinations that need protection, rather than applying the same action to every detection.
1. Choose a detection entry to act on. Review its destinations, confidence, and policy coverage to decide whether the activity is expected.
2. Configure a [DLP profile](/cloudflare-one/data-loss-prevention/dlp-profiles/) with the detection entries you want the policy to match, or use an existing profile.
3. (Optional) If Test scan is available for the profile, use [Test scan](/cloudflare-one/data-loss-prevention/test-scan/) to confirm that it detects representative content. Test scan checks the profile on its own. It does not evaluate a Gateway policy.
4. Create a [Gateway DLP policy](/cloudflare-one/data-loss-prevention/dlp-policies/) to log or block matching traffic. Scope it to the relevant destinations, applications, or users.
5. [Test the policy with Gateway traffic](/cloudflare-one/data-loss-prevention/dlp-policies/#3-test-dlp-policy) and confirm that it takes the expected action in [HTTP request logs](/cloudflare-one/insights/logs/dashboard-logs/gateway-logs/).
For an existing policy, use your findings to review its scope and detection settings. [Data security analytics](/cloudflare-one/insights/analytics/data-analytics/) shows activity from DLP policies after they are configured.
## Limitations
- Passive Detection scans a random sample of eligible Gateway HTTP traffic, not every request or response body.
- Counts may be estimated for high-volume detections due to analytics sampling. They describe sampled traffic, not all eligible Gateway traffic.
- The dashboard does not report total sampled traffic or detection rates.
- Destinations are scoped to one detection entry. Passive Detection does not provide an account-wide destination inventory.
- Results do not include user identity.
An empty dashboard does not confirm that sensitive data is absent.
For help with missing results, refer to [Troubleshoot DLP](/cloudflare-one/data-loss-prevention/troubleshoot-dlp/#passive-detection-shows-no-results).
# Troubleshoot DLP
import { Render, Steps } from "~/components";
Use this guide to troubleshoot common issues with Data Loss Prevention (DLP).
To check whether a profile detects specific content without sending traffic through Gateway, use [Test scan](/cloudflare-one/data-loss-prevention/test-scan/).
## DLP policy does not trigger or block content
DLP not inspecting or blocking content is the most common issue reported. If you have configured a [DLP policy](/cloudflare-one/data-loss-prevention/dlp-policies/) but it fails to inspect or block traffic, the cause is almost always that the traffic is not being decrypted. To use DLP to scan the content of HTTPS requests, you must turn on [TLS decryption](/cloudflare-one/traffic-controls/http-policies/tls-decryption/).
To turn on TLS decryption:
1. Select a time range that includes the traffic you want to investigate.
2. Check **Traffic direction**. Remove the filter to include all traffic directions, or select _Unknown_ to check bodies without a recorded direction.
3. Confirm that the expected detection entry is enabled in at least one DLP profile in the account.
4. Confirm that traffic meets the [Gateway inspection prerequisites](/cloudflare-one/data-loss-prevention/passive-detection/#prerequisites), including HTTP filtering and TLS decryption for HTTPS.
5. Check whether a [Do Not Inspect policy](/cloudflare-one/traffic-controls/http-policies/#do-not-inspect) or another routing configuration excludes the traffic from inspection.
An individual request or response body may not be sampled. An empty dashboard does not confirm that sensitive data is absent.
## DLP scans trigger false positives or block legitimate sites
If your DLP policy is blocking access to business-critical applications (such as Zoho, Google, or internal domains) or generating a high number of false positives, your DLP policy is likely too broad. Profiles such as **Credentials and Secrets** are powerful but can be overly aggressive if not scoped correctly.
### Problematic configuration
Applying a sensitive profile to all traffic causes unnecessary blocks. For example:
| Selector | Operator | Value | Action |
| ----------- | -------- | ------------------------- | ------ |
| DLP Profile | in | _Credentials and Secrets_ | Block |
### Recommended solution
Make your policies more specific. Instead of a catch-all block, create granular policies that target high-risk destinations or user groups.
This policy only blocks uploads of financial data to file-sharing websites for a specific user group, reducing the risk of false positives on other sites.
| Selector | Operator | Value | Logic | Action |
| ------------------ | -------- | ------------------------------- | ----- | ------ |
| Destination Domain | in | `dropbox.com`, `wetransfer.com` | And | Block |
| DLP Profile | in | _Financial Information_ | And | |
| User Group Names | in | `Finance Team` | | |
You can also create policies that match trusted applications using the [**Do Not Scan** action](/cloudflare-one/traffic-controls/http-policies/#do-not-scan).
## DLP detections are inconsistent
If DLP detects sensitive data in plain text but not within images or certain applications, check for the following issues:
- **OCR is turned on**: For DLP to scan text within images (such as a picture of a credit card), you must turn on [Optical Character Recognition (OCR)](/cloudflare-one/data-loss-prevention/dlp-settings/#optical-character-recognition-ocr) in DLP settings.
- **Application-specific behavior**: Some applications, such as WhatsApp Web, use protocols or encryption methods (such as WebSocket connections) that Gateway may not be able to fully inspect with HTTP policies.
- **Supported file types**: Content must be in a [supported file type](/cloudflare-one/data-loss-prevention/#supported-file-types) for DLP inspection.
## PII Record profile does not match
The **Personally Identifiable Information (PII) Record** predefined profile does not match isolated values. Unlike most profiles, it matches only when at least three unique detection entries appear in close proximity, which reduces false positives from single, unrelated matches.
If you need to detect an individual data type (such as a single email address or credit card number), use a different predefined profile or a [custom profile](/cloudflare-one/data-loss-prevention/dlp-profiles/#build-a-custom-profile) with the specific detection entries you want.
## DLP options are missing or you cannot create custom profiles
If you cannot use the _DLP Profile_ selector when creating an HTTP policy or are blocked from creating a custom DLP profile, it typically means one of two things:
1. Incorrect plan. These features require a Zero Trust Enterprise plan. If you believe your account should have this entitlement, contact your account team to confirm your subscription details.
2. Permissions issue. You may not have the required administrative privileges to configure DLP settings. Check with your Cloudflare account administrator.
# Build a data class
Data classes are reusable classification rules built from detection entries, other data classes, sensitivity levels, and data tags.
Use a data class when you want to combine multiple signals into a single reusable classification rule that can then be added to custom DLP profiles.
## What a data class does
A data class lets you define classification logic separately from a DLP profile.
Instead of rebuilding the same logic in multiple profiles, you can create one reusable data class and apply it wherever you need it.
Data classes can also assign labels to matched content. This lets you connect raw detections to a broader classification model instead of relying only on direct entry matching in a profile.
## Create a data class
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Data loss prevention** > **Data classification** > **Data classes**.
2. Select **Create data class**.
3. Enter a name and optional description.
4. Build the detection rules for the data class.
5. Assign the labels you want matching content to receive.
6. Select **Save**.
## Build detection rules
Data classes use a rule builder to combine multiple signals into one classification rule.
You can build rules from:
- [detection entries](/cloudflare-one/data-loss-prevention/detection-entries/)
- other existing data classes
Use logical operators such as `AND` and `OR` to control how those conditions are evaluated.
Because data classes can reference other data classes, you can build reusable classification layers instead of recreating the same logic in multiple places. Cloudflare excludes the current data class from the selector to prevent recursive references.
## Assign labels
After you define the rule logic, choose the labels you want matching content to receive.
You can assign:
- a sensitivity schema and sensitivity level
- a data tag group and one or more data tags
When content matches the data class, Cloudflare applies those labels to the match.
## Use a data class in a DLP profile
After you create a data class, you can add it to a custom DLP profile.
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Data loss prevention** > **Profiles**.
2. Create or edit a custom DLP profile.
3. In **Data classes**, select **Add data classes**.
4. Choose the data classes you want to include, then select **Confirm**.
5. (Optional) Add direct detection entries or labels to the profile.
6. Select **Save profile**.
Custom DLP profiles can combine direct detection entries, data classes, and labels in the same profile.
# Configure labels and templates
Labels and templates define the classification metadata you can apply to sensitive content in Cloudflare DLP.
Use the **Labels** tab to create and manage sensitivity schemas, sensitivity levels, data tag groups, and data tags. Use the **Templates** tab to review Cloudflare-managed starting points for sensitivity schemas and data tag groups.
## Labels
Labels help you describe matched content in a consistent way.
Data Classification supports two label types:
- **Sensitivity schemas and levels** define an ordered classification hierarchy.
- **Data tag groups and tags** define additional descriptors you can apply to content.
You can use labels directly in custom DLP profiles and assign them through data classes.
### Sensitivity schemas and levels
A sensitivity schema is a named hierarchy of sensitivity levels, such as `Public`, `Internal`, `Confidential`, or `Restricted`.
Each schema contains one or more ordered levels. In custom DLP profiles, selecting a sensitivity level lets you match content at that level or higher within the selected schema.
### Create a sensitivity schema
When creating a sensitivity schema, you can either create a custom schema from scratch or start from a template.
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Data loss prevention** > **Data classification** > **Labels**.
2. Select **Create labels**.
3. In **Sensitivity schema**, choose one of the following:
- **Create a custom schema** to define the schema from scratch
- **Choose a template** to start from a Cloudflare-managed template
4. Enter or review the name and description.
5. Add or update the sensitivity levels you want to include, in order.
6. Select **Save**.
You can edit the resulting sensitivity schema after creation.
### Data tag groups and tags
A data tag group contains related tags you can use to describe content beyond its sensitivity level. For example, a data tag group could contain tags for business function, data owner, or content category.
### Create a data tag group
When creating a data tag group, you can either create a custom group from scratch or start from a template.
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Data loss prevention** > **Data classification** > **Labels**.
2. Select **Create labels**.
3. In **Data tag group**, choose one of the following:
- **Create a custom group** to define the group from scratch
- **Choose a template** to start from a Cloudflare-managed template
4. Enter or review the name and description.
5. Add or update the data tags you want to include.
6. Select **Save**.
You can edit the resulting data tag group after creation.
## Templates
Templates provide Cloudflare-managed starting points for sensitivity schemas and data tag groups.
Templates are not linked objects. When you build from a template, Cloudflare creates a new sensitivity schema or data tag group in your account. After that, you can edit it like any other label object you create.
You can start from a template in either of the following ways:
- from the **Templates** tab, by reviewing a template and selecting **Build with template**
- from the **Labels** tab, by selecting **Create labels** and then **Choose a template** inline during creation
### Build from a template from the Templates tab
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Data loss prevention** > **Data classification** > **Templates**.
2. Select a template to review its details.
3. Select **Build with template**.
4. Review and customize the resulting sensitivity schema or data tag group.
5. Select **Save**.
After you build from a template, the resulting object appears in the **Labels** tab and can be used in data classes and DLP profiles.
## Use labels in DLP
After you create labels, you can use them in either of the following ways:
- assign them to content through [Build a data class](/cloudflare-one/data-loss-prevention/data-classification/build-a-data-class/)
- apply them directly in [custom DLP profiles](/cloudflare-one/data-loss-prevention/dlp-profiles/)
In custom DLP profiles, sensitivity levels and data tags can be used directly as profile criteria, even when they are not assigned through a data class.
# Data classification
Data Classification extends Cloudflare DLP with a reusable layer for identifying, organizing, and labeling sensitive content. Instead of building all detection logic directly inside a DLP profile, you can define labels and reusable classification rules, then apply them in custom DLP profiles.
## What is Data Classification?
With Data Classification, you can:
- Define labels such as sensitivity levels and data tags
- Use templates as a starting point for those labels
- Build reusable data classes that combine multiple signals into a single classification rule
This is useful when you want more than direct inspection. Detection entries help identify sensitive content. Data Classification helps organize and label that content so administrators can identify its severity and apply it consistently across DLP profiles.
Templates provide Cloudflare-managed starting points for sensitivity schemas and data tag groups. When you build from a template, Cloudflare creates a new object in your account that you can edit.
## How Data Classification fits with DLP
Data Classification works alongside detection entries and DLP profiles.
| Component | What it does |
| --- | --- |
| Detection entries | Detect specific content such as patterns, datasets, document fingerprints, AI prompt topics, and predefined detections. |
| Labels | Define sensitivity schemas, sensitivity levels, data tag groups, and data tags used to describe matched content. |
| Templates | Provide Cloudflare-managed starting points for sensitivity schemas and data tag groups. |
| Data classes | Build reusable classification rules from detection entries, other data classes, sensitivity levels, and data tags. |
| DLP profiles | Apply detection and classification logic to DLP scanning and enforcement workflows. |
In general, detection entries help identify sensitive content. Data Classification helps organize and label that content so administrators can identify its severity, understand where it exists, and apply it consistently. DLP profiles then apply that logic to scanning and enforcement workflows.
## When to use Data Classification vs DLP profiles
Use detection entries and DLP profiles when you want direct detection and enforcement. For example, if you want to detect a specific regex, dataset, or predefined detection and immediately use it in a policy, building directly with detection entries may be enough.
Use Data Classification when you want a more reusable and structured model. For example, Data Classification is a better fit when you want to:
- standardize sensitivity labels across multiple detections
- organize related detections into a reusable data class
- combine multiple signals into a single classification rule
- reuse the same classification logic across multiple DLP profiles
In summary, use DLP profiles when you want enforcement. Use Data Classification when you want to organize and label sensitive content in a reusable way before applying that logic in DLP workflows.
## Next steps
To get started:
- [Configure labels and templates](/cloudflare-one/data-loss-prevention/data-classification/configure-labels-and-templates/) — Create labels and build from Cloudflare-managed templates.
- [Build a data class](/cloudflare-one/data-loss-prevention/data-classification/build-a-data-class/) — Create reusable classification rules and apply them in custom DLP profiles.
- [Configure DLP profiles](/cloudflare-one/data-loss-prevention/dlp-profiles/) — Apply detection entries, data classes, and labels in DLP scanning workflows.
# Configure detection entries
Detection entries are the reusable detection logic that Cloudflare DLP uses to identify sensitive content in your web traffic and SaaS applications. You can create and manage detection entries independently of [DLP profiles](/cloudflare-one/data-loss-prevention/dlp-profiles/), then add the same entry to one or more custom profiles. You can also use detection entries in [data classes](/cloudflare-one/data-loss-prevention/data-classification/build-a-data-class/).
Detection entries include:
- [Pattern entries](#pattern-entries) — regular expressions used to detect text patterns
- [Predefined detection entries](/cloudflare-one/data-loss-prevention/detection-entries/predefined-detection-entries/) — Cloudflare-managed detections for specific types of sensitive content
- [Exact Data Match datasets](#exact-data-match-datasets) — uploaded datasets of sensitive values to match against, such as customer records or account numbers
- [Custom Wordlist datasets](#custom-wordlist-datasets) — uploaded plaintext datasets used to detect terms such as product names, internal codes, or SKU numbers
- [Document entries](#document-entries) — fingerprints of example documents used to find similar content
- [AI prompt topics](#ai-prompt-topics) — categories of prompts submitted to generative AI tools
## Manage detection entries
In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Data loss prevention** > **Detection entries** to create, review, and manage detection entries.
The Detection entries section includes dedicated views for different entry types, including **All**, **Pattern**, **Predefined**, **Datasets**, **Documents**, and **AI prompt topics**. You can use search and filters to find specific entries and review details such as type, status, and last updated time.
You can add the same detection entry to multiple custom DLP profiles. When you delete a custom detection entry, Cloudflare lists the profiles that currently use it.
## Test a detection entry
To test whether a detection entry identifies sample content, add the entry to a [DLP profile](/cloudflare-one/data-loss-prevention/dlp-profiles/#build-a-custom-profile), then use [Test scan](/cloudflare-one/data-loss-prevention/test-scan/). Test scan confirms whether the selected profile detects the sample. It does not test a Gateway policy or traffic flowing through Gateway.
If the profile does not match the sample, review the detection entry configuration, the profile [match count](/cloudflare-one/data-loss-prevention/dlp-profiles/advanced-settings/#match-count), and [confidence threshold](/cloudflare-one/data-loss-prevention/dlp-profiles/advanced-settings/#confidence-thresholds).
## Predefined detection entries
Predefined detection entries are Cloudflare-managed detections for specific types of sensitive content. You can review them from the **Predefined** view in **Detection entries** and add them directly to custom DLP profiles.
For a full list, refer to [Predefined detection entries](/cloudflare-one/data-loss-prevention/detection-entries/predefined-detection-entries/).
## Pattern entries
Pattern entries use regular expressions to detect text patterns in scanned content. You can create pattern entries independently of a DLP profile and reuse them across multiple custom profiles.
Regular expressions are written in Rust. Cloudflare recommends validating your regex with [Rustexp](https://rustexp.lpil.uk/).
DLP detects UTF-8 characters, which can be up to 4 bytes each. Custom text pattern detections are limited to 1024 bytes in length.
DLP does not support regular expressions with `+` or `*` operators because they are prone to exceeding the length limit. For example, the regex pattern `a+` can detect an infinite number of `a` characters. Cloudflare recommends using `a{min,max}` instead, such as `a{1,1024}`.
### Create a pattern entry
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Data loss prevention** > **Detection entries**.
2. From the **Pattern** tab, select **Add Pattern**.
3. Enter a name. Optionally, add a description.
4. In **Value**, enter the regular expression you want to detect.
5. Select **Validate Regex**.
6. After the regex is validated, select **Save**.
To use a pattern entry, add it as an existing entry to one or more [custom DLP profiles](/cloudflare-one/data-loss-prevention/dlp-profiles/#build-a-custom-profile).
To apply organization-specific checks to pattern matches, refer to [Validate data loss prevention matches with Cloudflare Workers](/cloudflare-one/data-loss-prevention/detection-entries/custom-validation-workers/).
## Exact Data Match datasets
Exact Data Match (EDM) datasets protect sensitive information such as names, addresses, phone numbers, and account numbers.
All EDM dataset data is encrypted before reaching Cloudflare. To detect matches, Cloudflare hashes traffic and compares it to hashes from your dataset. Matched data will be redacted in payload logs.
### Prepare Exact Data Match datasets
#### Formatting
To prepare an Exact Data Match dataset for DLP, add your desired data to a multi-column spreadsheet. Each line must be at least six characters long. Entries do not require trailing or final commas.
For compatibility, save your file in either `.csv` or `.txt` format with LF (`\n`) newline characters. DLP does not support CRLF (`\r\n`) newline characters. For information on dataset limits, refer to [Account limits](/cloudflare-one/account-limits/#data-loss-prevention-dlp).
#### Column title cells
DLP will detect and use title cells as column names for Exact Data Match datasets. If multiple columns have the same name, DLP will append a number sign (`#`) and number to their names.
:::caution[Update EDM datasets]
To select which Exact Data Match columns to use, you will need to [reupload any EDM datasets](#manage-existing-exact-data-match-datasets) added prior to column support.
:::
### Upload a new Exact Data Match dataset
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Data loss prevention** > **Detection entries**.
2. From the **Datasets** tab, select **Add a dataset**.
3. Select **Exact Data Match (EDM)**.
4. Upload your dataset file. Select **Next**.
5. Review and choose the detected columns you want to include. Select **Next**.
6. Name your dataset. Optionally, add a description. Select **Next**.
7. Review the details for your uploaded dataset. Select **Save dataset**.
DLP will encrypt your dataset and save its hash.
The dataset will appear in the list with an **Uploading** status. Once the upload is complete, the status will change to **Complete**. You can then add the dataset as an existing entry to one or more [custom DLP profiles](/cloudflare-one/data-loss-prevention/dlp-profiles/#build-a-custom-profile).
### Manage existing Exact Data Match datasets
Uploaded Exact Data Match datasets are read-only. To update a dataset, you must upload a new file to replace the original.
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Data loss prevention** > **Detection entries**.
2. From the **Datasets** tab, select the dataset you want to update.
3. Select **Upload dataset** and choose your updated dataset. Select **Next**.
4. Review and choose the new columns. Select **Next**.
5. Select **Save dataset**.
Your new dataset will replace the original dataset.
:::caution[Remove existing column entries]
If you want to update an Exact Data Match dataset to remove a column in use as an [existing detection entry](/cloudflare-one/data-loss-prevention/dlp-profiles/#build-a-custom-profile), you must remove the existing entry from any custom DLP profiles using it before updating the dataset.
:::
## Custom Wordlist datasets
Custom Wordlist (CWL) datasets protect non-sensitive terms such as intellectual property, SKU numbers, and internal project names.
Cloudflare stores data from CWL datasets in plaintext within DLP. Plaintext matches appear in payload logs. Optionally, CWL can detect case-sensitive data.
### Prepare Custom Wordlist datasets
Column title cells may result in false positives in Custom Wordlist datasets and should be removed.
### Upload a new Custom Wordlist dataset
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Data loss prevention** > **Detection entries**.
2. From the **Datasets** tab, select **Add a dataset**.
3. Select **Custom Wordlist (CWL)**.
4. Name your dataset. Optionally, add a description.
5. In **Upload file**, choose your dataset file.
6. (Optional) In **Settings**, turn on **Enforce case sensitivity** to require matched values to contain exact capitalization.
7. Select **Save**.
DLP will save your dataset in cleartext.
The dataset will appear in the list with an **Uploading** status. Once the upload is complete, the status will change to **Complete**. You can then add the dataset as an existing entry to one or more [custom DLP profiles](/cloudflare-one/data-loss-prevention/dlp-profiles/#build-a-custom-profile).
### Manage existing Custom Wordlist datasets
Uploaded Custom Wordlist datasets are read-only. To update a dataset, you must upload a new file to replace the original.
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Data loss prevention** > **Detection entries**.
2. From the **Datasets** tab, select the dataset you want to update.
3. Select **Upload dataset** and choose your updated dataset. Select **Next**.
4. Select **Save dataset**.
Your new dataset will replace the original dataset.
## Document entries
You can upload example documents to detect similar content in your organization's traffic. DLP creates a unique fingerprint of the document and compares traffic against it based on how similar it is to the original. This is useful for detecting specific document types common to your organization, such as contract templates or internal reports, where the content does not reduce to a list of individual values in an uploaded dataset.
DLP stores uploaded documents encrypted at rest in a [Cloudflare R2](/r2/) bucket. To upload sensitive data that is only stored in memory, use [Exact Data Match datasets](#exact-data-match-datasets).
### Prepare document entries
DLP supports documents in `.docx` and `.txt` format. Documents must be under 10 MB.
### Upload a new document entry
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Data loss prevention** > **Detection entries**.
2. From the **Documents** tab, select **Add a document entry**.
3. Name your document. Optionally, add a description.
4. In **Minimum similarity for matches**, enter a value between 0% and 100%.
5. In **Upload document**, choose and upload your document file.
6. Select **Save**.
The document will appear in the list with a **Pending** status. Once the upload is complete, the status will change to **Complete**. If you created a document entry with Terraform, the status will be **No file** until you upload a file.
To use your uploaded document fingerprint, add it as an existing entry to one or more [custom DLP profiles](/cloudflare-one/data-loss-prevention/dlp-profiles/#build-a-custom-profile).
### Manage existing document entries
Uploaded document entries are read-only. To update a document entry, you must upload a new file to replace the original.
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Data loss prevention** > **Detection entries**.
2. From the **Documents** tab, choose the document you want to update and select **Edit**.
3. (Optional) Update the name and minimum similarity for matches for your document entry. You can also open the existing uploaded document.
4. In **Update document entry**, choose and upload your updated document file.
5. Select **Save**.
Your new document entry will replace the original document entry. If your file upload fails, DLP will still use the original document fingerprint to scan traffic until you delete the entry.
## AI prompt topics
DLP uses [Application Granular Controls](/cloudflare-one/traffic-controls/http-policies/#granular-controls) to detect and categorize prompts submitted to generative AI tools. Application Granular Controls analyzes prompts for both content and user intent. Supported AI prompt protection detections include:
| Detection entry | Description |
| --- | --- |
| Content: PII | Prompt contains personal information such as names, SSNs, or email addresses. |
| Content: Credentials and Secrets | Prompt contains API keys, passwords, or other sensitive credentials. |
| Content: Source Code | Prompt contains actual source code, code snippets, or proprietary algorithms. |
| Content: Customer Data | Prompt contains customer names, projects, business activities, or confidential customer contexts. |
| Content: Financial Information | Prompt contains financial numbers or confidential business data. |
| Intent: PII | Prompt requests specific personal information about individuals. |
| Intent: Code Abuse and Malicious Code | Prompt requests malicious code for attacks, exploits, or harmful activities. |
| Intent: Jailbreak | Prompt attempts to circumvent AI security policies. |
Each detection entry is categorized as either **Content** or **Intent**:
- **Content** — Detects specific text or data in the prompt itself (for example, a user pasting source code or a credit card number into a chat).
- **Intent** — Detects the user's goal or objective for the AI's response (for example, a user asking an AI to generate malicious code or extract personal information).
Intent detection is useful when AI applications have access to internal data sources containing sensitive information through SaaS connectors or Model Context Protocol (MCP) servers.
To use an AI prompt topic, configure the corresponding [predefined DLP profile](/cloudflare-one/data-loss-prevention/dlp-profiles/predefined-profiles/#ai-prompt) or add it as an existing entry to one or more [custom DLP profiles](/cloudflare-one/data-loss-prevention/dlp-profiles/#build-a-custom-profile). AI prompt protection is available for ChatGPT, Google Gemini, Perplexity, and Claude.
# Validate data loss prevention matches with Cloudflare Workers
import {
DashButton,
PackageManagers,
Steps,
TypeScriptExample,
} from "~/components";
Data loss prevention (DLP) can run a Cloudflare Worker in your account when a pattern matches. Use your Worker to apply organization-specific checks, adjust confidence, or reject the match.
Custom functions appear in the entry editor when this feature is available for your account. You can attach them to custom pattern entries.
## Set up your Workers account
1. Set up Workers in the same [Cloudflare account](/fundamentals/account/create-account/) where you configure DLP. If you have not used Workers before, follow the [Workers getting started guide](/workers/get-started/guide/).
2. Configure a [Workers subdomain](/workers/configuration/routing/workers-dev/) for that account.
## Create a validation Worker
Deploy the Worker to the account where you configure DLP. Export a class named `DlpValidationEntrypoint` with a `validate` method. Import its base class and types from `@cloudflare/zt-types`.
```ts
import {
DlpValidation,
type DlpValidationInput,
type DlpValidationResult,
} from "@cloudflare/zt-types";
export class DlpValidationEntrypoint extends DlpValidation {
async validate(input: DlpValidationInput): Promise {
if (input.entryId === "entry-id-to-reject") {
return { score: "veto" };
}
return { score: 0 };
}
}
```
Replace the example condition with your validation logic. Return a score from `-1` to `1` to adjust confidence. Positive scores increase confidence. Negative scores decrease it. A score of `0` leaves confidence unchanged. Return `"veto"` to reject the match.
## Attach a Worker to a pattern entry
1. Log in to Cloudflare One and go to **Data loss prevention** > **Detection entries**.
Default behavior options are _No fallback_, _Veto_, or _Score_. Scores range from `-1` to `1`.
To use the pattern entry in DLP scanning, add it to a [custom DLP profile](/cloudflare-one/data-loss-prevention/dlp-profiles/#build-a-custom-profile).
# Detection entries
Detection entries are the reusable detection logic that Cloudflare DLP uses to identify sensitive content in your web traffic and SaaS applications. You can create and manage detection entries independently of DLP profiles, then add the same entry to one or more custom profiles.
Use the following pages to configure detection entries and review Cloudflare-managed predefined detections.
## Detection entry pages
- [Configure detection entries](/cloudflare-one/data-loss-prevention/detection-entries/configure-detection-entries/) — Create and manage pattern entries, datasets, document entries, and AI prompt topics.
- [Validate data loss prevention matches with Cloudflare Workers](/cloudflare-one/data-loss-prevention/detection-entries/custom-validation-workers/) - Attach a Worker in your account to a pattern entry to adjust confidence or reject a match.
- [Predefined detection entries](/cloudflare-one/data-loss-prevention/detection-entries/predefined-detection-entries/) — Review Cloudflare-managed predefined detections and their descriptions.
# Predefined detection entries
Predefined detection entries are Cloudflare-managed detections for specific types of sensitive content. You can review these entries from the **Predefined** view in **Detection entries**.
You can add any predefined detection entry directly to a custom [DLP profile](/cloudflare-one/data-loss-prevention/dlp-profiles/#build-a-custom-profile) or [data class](/cloudflare-one/data-loss-prevention/data-classification/build-a-data-class/). Use the following reference to review all predefined detection entries currently supported by Cloudflare DLP.
| Detection entry | Description |
| --- | --- |
| AI Prompt Content: Credentials and Secrets | Prompt contains API keys, passwords, or other sensitive credentials |
| AI Prompt Content: Customer data | Prompt contains customer names, projects, business activities, or confidential customer contexts |
| AI Prompt Content: Financial Information | Prompt contains actual financial numbers or confidential business data |
| AI Prompt Content: PII | Prompt contains personal information (names, SSNs, emails, etc.) |
| AI Prompt Content: Source code | Prompt contains source code, code snippets, or proprietary algorithms |
| AI Prompt Intent: Code Abuse and Malicious Code | Malicious code or attempts to exploit vulnerabilities |
| AI Prompt Intent: Jailbreak | Prompt attempts to circumvent security policies |
| AI Prompt Intent: PII | Prompt requests specific personal information about individuals |
| Amazon AWS Access Key ID | Detects Amazon AWS access key IDs such as `AKIA`. |
| Amazon AWS Secret Access Key | Detects potential Amazon AWS secret access keys such as ``. |
| American Express Card Number | Detects American Express credit card numbers such as "378282246310005". |
| American Express Text | Detects mentions of the American Express brand name such as "American Express". |
| Australia Address | Detects Australian street addresses with state and postcode such as "100 George St, Sydney NSW 2000". |
| Australia Business (ABN) | Detects Australian Business Numbers (ABN) such as "51 824 753 556". |
| Australia Company (ACN) | Detects Australian Company Numbers (ACN) such as "001 000 004". |
| Australia Medicare | Detects Australian Medicare card numbers such as "2000000006". |
| Australia Passport Number | Detects Australian passport numbers such as "L1234567". |
| Australia Tax File Number | Detects Australian Tax File Numbers (TFN) such as "85 655 734". |
| Austria SSN (SV-Nummer) | Detects Austrian social security numbers (SV-Nummer) such as "1018 010180". |
| Austria Tax ID | Detects Austrian tax identification numbers (Steuernummer) such as "12 345/6789". |
| Austria VAT (UID) | Detects Austrian VAT numbers (UID-Nummer) such as "ATU12345678". |
| Belgium Tax ID (NN) | Detects Belgian national numbers (Numéro National / Rijksregisternummer) such as "85.07.30-000.61". |
| Belgium VAT | Detects Belgian VAT numbers such as "BE0000000097". |
| Bitcoin Wallet | Detects Bitcoin wallet addresses such as "1BvBMSEYstWetqTFn5Au4m4GFg7xJaNVN2". |
| Brazil CNPJ | Detects Brazilian corporate taxpayer registry numbers (CNPJ) such as "11.222.333/0001-81". |
| Brazil CPF (Tax ID) | Detects Brazilian individual taxpayer registry numbers (CPF) such as "529.982.247-25". |
| Bulgaria Uniform Civil (EGN) | Detects Bulgarian Uniform Civil Numbers (EGN) such as "2405500007". |
| C | Detects C source code. |
| C# | Detects C# source code. |
| C++ | Detects C++ source code. |
| Canada Bank Account Number | Detects Canadian bank account numbers (institution + transit + account) such as "12345-678 1234567". |
| Canada Health Number | Detects Canadian provincial health card numbers such as "1234-567-897". |
| Canada Passport | Detects Canadian passport numbers such as "AB123456". |
| Canada PHIN (Manitoba) | Detects Manitoba Personal Health Identification Numbers (PHIN) such as "100000009". |
| Canada Physical Address | Detects Canadian street addresses with postal code such as "100 Main St, Ottawa, ON K1A 0B1". |
| Canada Social Insurance Number | Detects Canadian Social Insurance Numbers (SIN) such as "114 905 474". |
| Chile National ID (RUT) | Detects Chilean national identification numbers (RUT / Rol Único Tributario) such as "12.345.678-5". |
| China ID Card | Detects Chinese resident identity card numbers such as "11010519491231002X". |
| Cloudflare Account Owned API Token | Detects Cloudflare account-owned API tokens such as `cfat_`. |
| Cloudflare User API Key | Detects Cloudflare user API keys such as `cfk_`. |
| Cloudflare User API Token | Detects Cloudflare user API tokens such as `cfut_`. |
| Croatia Personal ID (OIB) | Detects Croatian personal identification numbers (OIB) such as "10000000005". |
| CVV Card Number (labeled) | Detects credit card CVV/CVC verification codes in context of the "cvv" keyword, such as "cvv: 033". |
| Denmark Tax (CPR) | Detects Danish personal identification numbers (CPR-nummer) such as "010180-0008". |
| Diners Club Card Number | Detects Diners Club credit card numbers such as "30121690374838". |
| Discord Webhook | Detects Discord webhook URLs such as a webhook URL under `discord.com/api/webhooks/`. |
| Email Address | Detects email addresses such as "test@example.com". |
| Ethereum Wallet | Detects Ethereum wallet addresses such as "0x71C7656EC7ab88b098defB751B7401B5f6d8976F". |
| EU Passport | Detects EU member state passport numbers such as "AB1234567". |
| FDA Active Ingredients | Detects FDA-registered drug active ingredient names such as "ABEMACICLIB". |
| FDA Drug Names | Detects FDA-registered drug names such as "ABACAVIR". |
| Finland Tax ID | Detects Finnish personal identity codes (Henkilötunnus / HETU) such as "311280-888Y". |
| France CNI (National ID) | Detects French national identity card numbers (Carte nationale d'identité) such as "12345678901". |
| France Passport | Detects French passport numbers such as "12AB34567". |
| France Social Security Number | Detects French social security (INSEE) numbers such as "145081849670637". |
| France Tax ID (SPI) | Detects French tax identification numbers (Numéro fiscal SPI) such as "1234567890123". |
| France VAT | Detects French VAT numbers such as "FR12000000000". |
| Full Name | Detects personal full names. |
| Germany Tax ID | Detects German tax identification numbers (Steueridentifikationsnummer) such as "10000000005". |
| Germany VAT | Detects German VAT numbers (USt-IdNr) such as "DE100000003". |
| GitHub PAT | Detects GitHub personal access tokens such as a token beginning with `ghp_`. |
| Go | Detects Go source code. |
| Google GCP API Key | Detects Google Cloud Platform API keys such as `AIza`. |
| Greece Tax (AFM) | Detects Greek tax identification numbers (AFM) such as "100000003". |
| Haskell | Detects Haskell source code. |
| Hong Kong Identity Card Number | Detects Hong Kong identity card (HKID) numbers such as "F543210(A)". |
| Hungary Tax | Detects Hungarian tax identification numbers (Adóazonosító jel) such as "8000000008". |
| IBAN | Detects International Bank Account Numbers (IBAN) such as "GB94 BARC 1020 1530 0934 59". |
| ICD-10 FY2023 Short Description | Detects ICD-10 FY2023 medical diagnosis terms such as "Typhoid fever, unspecified". |
| ICD-11 Short Description | Detects ICD-11 medical diagnosis terms such as "ABDOMINAL ACTINOMYCOSIS". |
| India Aadhaar | Detects Indian Aadhaar national identification numbers such as "2345 6789 0124". |
| India GST (GSTIN) | Detects Indian Goods and Services Tax identification numbers (GSTIN) such as "22AAAAA0000A1Z5". |
| India PAN Card | Detects Indian Permanent Account Number (PAN) card identifiers such as "ABCDE1234F". |
| India Voter ID | Detects Indian Voter ID (EPIC) numbers such as "ABC1234567". |
| Indonesia Identity Card Number | Detects Indonesian identity card (KTP/NIK) numbers such as "3203012503770011". |
| Indonesia Tax (NPWP) | Detects Indonesian taxpayer identification numbers (NPWP) such as "12.345.678.9-012.345". |
| Ireland Tax (PPS) | Detects Irish Personal Public Service numbers (PPS) such as "1234567FA". |
| Ireland VAT | Detects Ireland VAT numbers such as "IE1234567T". |
| Italy Fiscal Code | Detects Italian fiscal codes (Codice Fiscale) such as "BNZVCN32S10E573Z". |
| Japan Postal Code | Detects a Japanese postal code preceded by the 〒 marker, such as "〒100-0001". Free-form addresses without a 〒 postal-code marker are not matched. |
| Japan My Number (Corp) | Detects Japanese corporate My Number identifiers (Hojin Bango) such as "7000012050002". |
| Japan My Number (Person) | Detects Japanese individual My Number identifiers (Kojin Bango) such as "100000000005". |
| Japan Names (Kanji, labeled) | Detects a kanji personal name only when it immediately follows an inline label such as 氏名, 名前, or Name — for example "氏名: 田中太郎". Bare kanji names with no preceding label (for example a standalone name or one in a spreadsheet column) are not matched. |
| Japan Passport | Detects Japanese passport numbers such as "TZ1234567". |
| Java | Detects Java source code. |
| JavaScript | Detects JavaScript source code. |
| Korea Resident Number (RRN) | Detects South Korean Resident Registration Numbers (RRN) such as "850515-1234567". |
| Lua | Detects Lua source code. |
| Luxembourg Tax | Detects Luxembourg national identification numbers (Matricule) such as "1985010112345". |
| Luxembourg VAT | Detects Luxembourg VAT numbers such as "LU10000053". |
| Malaysian National Identity Card Number | Detects Malaysian national identity card (MyKad) numbers such as "560224-10-8354". |
| Mastercard Card Number | Detects Mastercard credit card numbers such as "5252 5971 4219 4116". |
| Mastercard Text | Detects mentions of the Mastercard brand name such as "Mastercard". |
| Microsoft Azure Client Secret | Detects Microsoft Azure client secrets such as ``. |
| MX CLABE (Bank) | Detects Mexican CLABE bank account numbers such as "032180000118359719". |
| MX CURP | Detects Mexican CURP codes such as "GOMC850515HJCRRR05". |
| Netherlands BSN | Detects Dutch citizen service numbers (Burgerservicenummer / BSN) such as "123456782". |
| Netherlands VAT | Detects Dutch VAT numbers (Btw-nummer) such as "NL123456782B01". |
| NPM Token | Detects npm registry access tokens such as a token beginning with `npm_`. |
| NZ NHI Number | Detects New Zealand National Health Index (NHI) numbers such as "ZZZ0016". |
| NZ Tax (IRD) | Detects New Zealand Inland Revenue Department (IRD) tax numbers such as "49-091-850". |
| OpenAI API Key | Detects OpenAI API keys such as a key beginning with `sk-proj-`. |
| Peru Tax (RUC) | Detects Peruvian taxpayer identification numbers (RUC) such as "20000000001". |
| Peru Unique ID (DNI) | Detects Peruvian national identity numbers (DNI) such as "12345678". |
| Philippines Unified Multi-Purpose ID Identity Number | Detects Philippines Unified Multi-Purpose ID (UMID) numbers such as "2460-1501400-1". |
| Poland National ID (PESEL) | Detects Polish national identification numbers (PESEL) such as "85051500006". |
| Poland REGON | Detects Polish National Business Registry numbers (REGON) such as "100000008". |
| Poland Tax (NIP) | Detects Polish tax identification numbers (NIP) such as "123-456-32-18". |
| Portugal Tax (NIF) | Detects Portuguese tax identification numbers (NIF / Número de Contribuinte) such as "100000002". |
| PyPI Token | Detects PyPI package upload tokens such as a token beginning with `pypi-`. |
| Python | Detects Python source code. |
| R | Detects R source code. |
| Rust | Detects Rust source code. |
| Singapore National Registration Identity Card Number | Detects Singapore NRIC/FIN identity card numbers such as "S6792120H". |
| Slack API Token | Detects Slack API tokens such as a token beginning with `xoxb-`. |
| Slack Webhook | Detects Slack incoming webhook URLs such as a webhook URL under `hooks.slack.com/services/`. |
| Spain DNI/NIF | Detects Spanish national identity numbers (DNI/NIF) such as "12345678Z". |
| Spain SSN | Detects Spanish Social Security affiliation numbers (NAF) such as "28 1234567890". |
| Spain Tax (CIF) | Detects Spanish corporate tax identification codes (CIF) such as "A58818501". |
| SSH Private Key | Detects SSH private key material such as "-----BEGIN OPENSSH PRIVATE KEY-----". |
| Stripe Granular Restricted Key | Detects Stripe live-mode restricted API keys such as a key beginning with `rk_live_`. |
| Stripe Standard Secret Key | Detects Stripe live-mode secret API keys such as a key beginning with `sk_live_`. |
| Sweden Tax | Detects Swedish personal identity numbers (Personnummer) such as "811228-9874". |
| SWIFT | Detects SWIFT/BIC business identifier codes such as "PMFAUS66". |
| Swift | Detects Swift source code. |
| Taiwan National Identification Number | Detects Taiwan national identification numbers such as "W171845961". |
| Thai Identity Card Number | Detects Thai national identity card numbers such as "4-8547-01245-28-9". |
| UAE Passport | Detects United Arab Emirates passport numbers such as "A1234567". |
| Union Pay Card Number | Detects UnionPay credit card numbers such as "6250941006528599". |
| Union Pay Text | Detects mentions of the UnionPay brand name such as "Union Pay". |
| United Kingdom National Insurance Number | Detects UK National Insurance Numbers (NINO) such as "OC 66 31 85 C". |
| United Kingdom NHS Number | Detects UK NHS patient identification numbers such as "485-585-0454". |
| United States ABA Routing Number | Detects US ABA bank routing numbers such as "021000021". |
| United States SSN Numeric Detection | Detects US Social Security Numbers such as "123-45-6789". |
| United States SSN Text | Detects mentions of "SSN" or "social security" as a keyword, such as "social security". |
| Unsanitized HAR File | Detects HAR (HTTP Archive) files that may contain unsanitized authentication tokens or session data, such as a HAR file containing `Authorization: Bearer `. |
| Uruguay ID (CI) | Detects Uruguayan national identity numbers (Cédula de Identidad) such as "1.234.500-8". |
| US Driver's License Number | Detects US driver's license numbers such as "CA License: A1234567". |
| US Individual Tax Identification Number (ITIN) | Detects US Individual Taxpayer Identification Numbers (ITIN) such as "934-78-5678". |
| US Mailing Address | Detects US mailing addresses such as "100 First St, Chicago, IL 60601". |
| US Passport Number | Detects US passport numbers such as "A12345678". |
| US Phone Number | Detects US phone numbers such as "555-555-5555". |
| Visa Card Number | Detects Visa credit card numbers such as "4111 1111 1111 1111". |
| Visa Text | Detects mentions of the Visa brand name such as "Visa". |
# Common policies
import { GlossaryTooltip, Render } from "~/components";
The following DLP policies are commonly used to secure sensitive data in uploaded and downloaded files. They are built as [Gateway HTTP policies](/cloudflare-one/traffic-controls/http-policies/) using the [DLP Profile](/cloudflare-one/traffic-controls/http-policies/#dlp-profile) selector.
Before using these policies, complete the [prerequisites for scanning HTTP traffic](/cloudflare-one/data-loss-prevention/dlp-policies/#prerequisites).
## Log uploads/downloads
When you want to monitor where sensitive data is going before enforcing blocks, use the **Allow** action. In a Gateway HTTP policy, all matches — including Allow — are recorded in your [HTTP request logs](/cloudflare-one/data-loss-prevention/dlp-policies/#4-view-dlp-logs). This gives you visibility into sensitive data transfers without disrupting users.
The following example logs any upload or download that matches your enabled [Financial Information](/cloudflare-one/data-loss-prevention/dlp-profiles/predefined-profiles/#financial-information) DLP profile entries when users interact with file sharing applications.
| Selector | Operator | Value | Logic | Action |
| ------------------ | -------- | ----------------------- | ----- | ------ |
| DLP Profile | in | _Financial Information_ | And | Allow |
| Content Categories | in | _File Sharing_ | | |
## Block file types
certificate pinning , which is incompatible with Gateway TLS decryption. These applications verify they are connecting directly to their own servers and will reject Gateway's inspection certificate. If needed, you can create a [Do Not Inspect policy](/cloudflare-one/traffic-controls/http-policies/#do-not-inspect) so that the app can continue to function on Android:
1. Set up an [OS version device posture check](/cloudflare-one/reusable-components/posture-checks/client-checks/os-version/) that checks for the Android operating system.
2. Create the following HTTP policy in Gateway:
| Selector | Operator | Value | Logic | Action |
| ---------------------------- | -------- | -------------------- | ----- | -------------- |
| Application | in | _Google Drive_ | And | Do Not Inspect |
| Passed Device Posture Checks | in | _OS Version Android_ | | |
Android users can now use the app, but the app traffic will bypass Gateway inspection entirely — including DLP scanning, HTTP logging, and antivirus scanning.
## Exclude specific sites
In your [DLP logs](/cloudflare-one/data-loss-prevention/dlp-policies/#4-view-dlp-logs), you may find that certain sites routinely trigger DLP detections that do not represent actual data loss (false positives). To exempt these sites from DLP scanning:
1. [Create a list](/cloudflare-one/reusable-components/lists/) of hostnames or URLs.
2. Exclude the list from your DLP policy using the `not in list` operator, which references the list you created in step 1:
| Selector | Operator | Value | Logic | Action |
| ----------- | ----------- | ----------------------- | ----- | ------ |
| DLP Profile | in | _Financial Information_ | And | Block |
| Application | in | _Google Drive_ | And | |
| Domain | not in list | _Do not DLP - SSN_ | | |
# Scan HTTP traffic
import { Badge, GlossaryTooltip } from "~/components";
You can scan HTTP traffic for sensitive data through [Secure Web Gateway](/cloudflare-one/traffic-controls/) policies. To enforce DLP policies, first configure a **DLP profile** that defines what sensitive data patterns to detect. Then build a **Gateway HTTP policy** that defines what action to take (allow, block, or log) when Gateway finds matching data.
Before creating a policy, use [Passive Detection](/cloudflare-one/data-loss-prevention/passive-detection/) to explore sensitive data in sampled Gateway traffic. Its findings can help you choose which data types and destinations your policy should cover.
:::note
To scan AI prompts and responses without Gateway HTTP filtering, you can also enable DLP directly on an [AI Gateway](/ai-gateway/features/dlp/).
:::
## Prerequisites
- Set up [Gateway HTTP filtering](/cloudflare-one/traffic-controls/get-started/http/). This routes your users' web traffic through Cloudflare Gateway so it can be inspected.
- HTTP filtering requires turning on the [Gateway proxy](/cloudflare-one/traffic-controls/proxy/#turn-on-the-gateway-proxy) for TCP traffic.
- Turn on [TLS decryption](/cloudflare-one/traffic-controls/http-policies/tls-decryption/#turn-on-tls-decryption). Because most web traffic is encrypted with HTTPS, Gateway must decrypt it before DLP can scan the request body for sensitive data.
## 1. Configure a DLP profile
A DLP profile defines the sensitive data patterns you want to detect — for example, social security number formats, credit card numbers, or custom patterns specific to your organization. Refer to [Configure a DLP profile](/cloudflare-one/data-loss-prevention/dlp-profiles/). We recommend getting started with a predefined profile.
## 2. Create a DLP policy
DLP Profiles may be used alongside other Cloudflare One rules in a [Gateway HTTP policy](/cloudflare-one/traffic-controls/http-policies/). To start logging or blocking traffic, create a policy for DLP:
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Traffic policies** > **Firewall policies**. Select **HTTP**.
2. Select **Add a policy**.
3. Build an [HTTP policy](/cloudflare-one/traffic-controls/http-policies/) using the [DLP Profile](/cloudflare-one/traffic-controls/http-policies/#dlp-profile) selector. For example, the following policy blocks users from uploading sensitive data to any location other than an approved corporate application. It combines three conditions: the request content matches a DLP profile, the HTTP method is `POST`, and the destination is not an approved application:
| Selector | Operator | Value | Logic | Action |
| ----------- | -------- | --------------------------------------------------------- | ----- | ------ |
| DLP Profile | in | _Social Security, Insurance, Tax, and Identifier Numbers_ | And | Block |
| HTTP Method | in | _POST_ | And | |
| Application | not in | _Workday_ | | |
4. Select **Create policy**.
Gateway now applies the configured action when traffic matches the complete HTTP policy.
### DLP with the Forward action
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Data loss prevention** > **Test scan**.
2. Under **Input method**, select the type of content you want to test:
- **Text**: Enter or paste content into **Content to scan**.
- **File**: Select or drag a file into the upload area. Files can be up to 10 MB. To test several files at once, upload a `.zip` archive. Each file inside the archive is scanned and reported separately.
- **HAR**: Select or drag a `.har` file into the upload area. Up to 50 bodies are scanned per file. Request and response bodies count toward the same limit.
3. Choose which profiles to test. Turn on **Scan against all profiles**, or select one or more profiles from the list.
4. Select **Scan**.
## Review scan results
Depending on the input and scan result, the results can include the following sections:
| Section | What it shows |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Summary** | The number of profiles matched and files scanned, and the overall antivirus status. |
| **File metadata** | The detected file name, size, MIME type, extension, and file categories. |
| **Antivirus results** | Whether each file is clean, suspicious, infected, or was not scanned, along with its SHA-256 hash. Infected files include available malware details. |
| **OCR results** | The text that OCR extracted from each image. |
| **Profile matches** | The profiles, detection entries, data classes, data tags, and sensitivity levels that matched. |
| **Match contexts** | The matched content, confidence level, and proximity keywords that increased or decreased confidence. |
| **JSON** | The complete scanner response, which you can download for further analysis. |
To save the complete response as `dlp-scan-results.json`, open **JSON** and select **Download**. The file can contain sample payloads and match context. Store and share it as sensitive data.
## Example
A Gateway policy that uses a custom profile is not blocking a spreadsheet that contains credit card numbers. Use a test scan to find out whether the profile or the policy is responsible.
1. Run a test scan with the same file and select only the custom profile. This tests the profile on its own, with Gateway removed from the path.
2. If the scan returns matches, the profile detects this sample under Test scan settings. This does not confirm that Gateway inspects the traffic the same way, so check the Gateway policy conditions, the traffic path, and TLS decryption.
3. If the scan returns no matches, work through the profile itself. A profile matches when its [detection entries](/cloudflare-one/data-loss-prevention/detection-entries/) match, and each entry defines a single pattern or dataset, such as a credit card number pattern, a custom regular expression, or an exact match dataset. Confirm that the profile contains the entry you expect and that the entry is turned on.
4. Compare the entry against the values in the file. Some entries apply [additional validation](/cloudflare-one/data-loss-prevention/dlp-profiles/predefined-profiles/) beyond pattern matching. A test value that has the expected format may still fail validation. Use a valid test value for the entry.
5. Check the profile's [match count](/cloudflare-one/data-loss-prevention/dlp-profiles/advanced-settings/#match-count). If it requires more matches than your sample contains, the profile does not trigger. Add more sample data or lower the match count.
6. Check the profile's [confidence threshold](/cloudflare-one/data-loss-prevention/dlp-profiles/advanced-settings/#confidence-thresholds). Test scan does not show detections below the threshold in **Match contexts**. To check whether the threshold prevented a match, temporarily lower it and run the scan again. If a match appears, review the match context. For example, adding relevant proximity keywords such as "payment" or "billing" may increase confidence. You can also lower the profile's confidence threshold if appropriate.
## Troubleshoot scan results
### Expected content does not match
Confirm that you selected the intended profile and that the profile contains the expected detection entries. A detection may not appear when the content does not meet the entry's matching requirements, when the profile [match count](/cloudflare-one/data-loss-prevention/dlp-profiles/advanced-settings/#match-count) is greater than the number of matches in the sample, or when the detection is below the profile's [confidence threshold](/cloudflare-one/data-loss-prevention/dlp-profiles/advanced-settings/#confidence-thresholds).
### Test scan matches content that should not match
Raise the profile's [confidence threshold](/cloudflare-one/data-loss-prevention/dlp-profiles/advanced-settings/#confidence-thresholds) so that DLP only triggers on higher confidence detections, or increase the [match count](/cloudflare-one/data-loss-prevention/dlp-profiles/advanced-settings/#match-count) so that a single incidental value does not trigger the profile. For custom entries, narrow the regular expression or dataset.
[AI context analysis](/cloudflare-one/data-loss-prevention/dlp-settings/#ai-context-analysis) can also reduce false positives in production, but it only supports Gateway HTTP and HTTPS traffic.
If a profile behaves correctly here but blocks legitimate traffic in production, the policy is likely too broad. Refer to [Troubleshoot DLP](/cloudflare-one/data-loss-prevention/troubleshoot-dlp/).
### OCR extracted text but no entries matched
OCR runs on images, but DLP only matches the extracted text against profiles that have OCR turned on. If **OCR results** shows the text you expect and no entry triggered, OCR is turned off for the profile you selected.
To apply OCR to every profile, turn on [OCR in DLP settings](/cloudflare-one/data-loss-prevention/dlp-settings/#optical-character-recognition-ocr). You can also turn on OCR for an [individual profile](/cloudflare-one/data-loss-prevention/dlp-profiles/advanced-settings/#optical-character-recognition-ocr), though profile-level OCR is deprecated.
### Test scan matches but Gateway does not
If the scan detects the content but your Gateway policy does not, the selected profile can detect the sample under Test scan settings. This does not confirm that Gateway can decrypt or inspect the traffic in the same way. Check the Gateway policy, traffic path, TLS decryption, and supported file types. For more information, refer to [Troubleshoot DLP](/cloudflare-one/data-loss-prevention/troubleshoot-dlp/).
### A scan returns an error
For file uploads, confirm that the file is 10 MB or smaller. For HAR files, confirm that the file contains valid HAR data. If the scanner is temporarily unavailable, wait and run the scan again.
## Limitations
- **AI prompt profiles are not supported.**
- Changes to your DLP configuration can take up to two minutes to take effect in a test scan. After you update a profile, detection entry, or data class, wait before testing.
- Profile detection is validated, but Gateway policy conditions and actions are not. To verify that a complete policy allows, blocks, or logs traffic as expected, [test the DLP policy with Gateway traffic](/cloudflare-one/data-loss-prevention/dlp-policies/#3-test-dlp-policy).
:::note
Fair use rate limits apply. This tool is intended for validating configuration, not for bulk or automated scanning.
:::
# Email security
import { Description, Render } from "~/components";
:::caution[Important]
Refer to [Area 1](/email-security/) if you are looking for the Area 1 documentation.
:::
:::note
If you have not yet purchased Email security, you can try Email security with Retro Scan. Refer to [Retro Scan](/cloudflare-one/email-security/retro-scan/) to learn more.
:::
Protect your email inbox with Email security.
Cloudflare Email Security uses AI, threat intelligence, and security rules to analyze every incoming email, protecting your organization from phishing, malware, [Business Email Compromise](https://www.cloudflare.com/en-gb/learning/email-security/business-email-compromise-bec/) (where attackers impersonate executives or authority figures to commit fraud), vendor email fraud, and spam.
It integrates with your existing email provider (such as Outlook or Gmail) and can be deployed via [API](/cloudflare-one/email-security/setup/post-delivery-deployment/api/), [BCC](/cloudflare-one/email-security/setup/post-delivery-deployment/bcc-journaling/bcc-setup/gmail-bcc-setup/gmail-bcc-setup/)/[Journaling](/cloudflare-one/email-security/setup/post-delivery-deployment/bcc-journaling/journaling-setup/m365-journaling/), or [MX/Inline](/cloudflare-one/email-security/setup/pre-delivery-deployment/mx-inline-deployment-setup/).
When you complete the [setup process](/cloudflare-one/email-security/setup/), the Cloudflare dashboard will display the Email security overview page.
The Email security overview provides you with:
- **Quick actions**, where you can:
- View [submissions](/cloudflare-one/email-security/submissions/)
- Manage detection settings: manage [allow policies](/cloudflare-one/email-security/policies/inbound/allow-policies/), [blocked senders](/cloudflare-one/email-security/policies/inbound/blocked-senders/), [trusted domains](/cloudflare-one/email-security/policies/inbound/trusted-domains/), [impersonation registry](/cloudflare-one/email-security/settings/detection-settings/impersonation-registry/) and [additional detections](/cloudflare-one/email-security/settings/detection-settings/additional-detections/).
- [Run screens](/cloudflare-one/email-security/investigation/search-email/#screen-criteria): Search, filter, reclassify, and bulk-move emails
- **Recommendations**: Suggested next steps to improve your configuration. For example, submitting misclassified emails for reclassification, creating policies, or protecting users at risk of [impersonation](/cloudflare-one/email-security/settings/detection-settings/impersonation-registry/).
- **Email security metrics**: Activity from the last seven days.
- **Recently modified policies**: A list of recently changed policies.
- **Education and resources**: Links to [implementation guides](/cloudflare-one/implementation-guides/), [Email security changelogs](/cloudflare-one/changelog/email-security/), and [API documentation](https://developers.cloudflare.com/api/resources/email_security/subresources/investigate/methods/get/)
To access the Email security overview:
1. Log in to [Cloudflare One](https://one.dash.cloudflare.com/).
2. Go to **Email security** > **Overview**.
---
## Troubleshooting
For help resolving common issues with Email Security, refer to [Troubleshoot Email Security](/cloudflare-one/email-security/troubleshooting/).
# PhishGuard
PhishGuard is a team of analysts that routinely inspects your email environment and responds to threats that come through your email inbox.
While Email security uses advanced technologies to protect your email inbox, PhishGuard offers an additional human component to protect your email environment against impersonation events, suspicious items, false negatives/false positives, and any new event that automated intelligent systems may miss due to a lack of context (for example, a compromised account activity).
PhishGuard only works on a post-delivery environment (only emails that have already landed in your email inbox are reviewed). As a result, PhishGuard analysts may [submit a message for review](/cloudflare-one/email-security/submissions/#submit-messages-for-review) or [auto-move](/cloudflare-one/email-security/settings/detection-settings/auto-moves/) based on their findings.
:::caution
Auto-moves are mandatory for PhishGuard customers.
:::
PhishGuard coordinates with the email detections team, allowing you to directly request immediate detection for specific items and implement custom detections unique to your needs. An example of this is requesting to block all PayPal traffic if you do not use PayPal for invoicing. This capability allows you to take ownership over the rules governing your email environment through PhishGuard's human intervention.
Additionally, PhishGuard analysts:
- Use real-time threat data to identify malicious activity. Email-based threats are responded to rapidly, and immediately reported and documented.
- Review every [user](/cloudflare-one/email-security/investigation/search-email/#user-submissions) and [team](/cloudflare-one/email-security/investigation/search-email/#team-submissions) submission so your security team can focus on more critical activities.
- Help you detect and mitigate threats faster, reducing the time attacks have access to your network. This also helps reducing business impact, because it prevents data breaches, financial loss, and reputational damage.
To use PhishGuard:
1. Log in to [Cloudflare One](https://one.dash.cloudflare.com/).
2. Select **Email security**.
3. Select **PhishGuard**.
The dashboard will display the following metrics:
- ROI Calculator
- Insider threat defense
- Email threat hunting
- Actions
- API Status
- Managed email security operations
- Reports
## ROI Calculator
Use the ROI Calculator to compare triage durations and hourly rates to calculate PhishGuard's return on investment.
The ROI Calculator displays:
- Total aggregated saved number in USD dollars.
- Triage duration: The amount of time in minutes spent triaging the message.
- Hourly rate.
## Insider threat defense
An [insider threat](https://www.cloudflare.com/en-gb/learning/access-management/what-is-an-insider-threat/) is a risk to an organization's security stemming from someone associated with the organization. PhishGuard looks for threat actor groups.
Insider threat defense on the dashboard displays **Insider leads** and **Insider reports generated**. **Insider leads** displays the number of emails identified as potential insider threat email. **Insider reports generated** displays the number of reports created based on insider leads.
## Email threat hunting
PhishGuard reviews suspicious and highly malicious activity in your email environment.
On the Cloudflare One dashboard, email threat hunting displays previously unknown phishing attacks.
Email threat hunting also gives you information on **Threat leads generated** and **Total reposts generated**.
## Actions
**Actions** allows you to review the most common actions taken by the PhishGuard team, such as escalations, threat hunts, and moves.
## API Status
API Status allows you to monitor and configure the current status of API message auto-moves and directory integrations.
Select **Message moves** to [configure auto-moves](/cloudflare-one/email-security/settings/detection-settings/auto-moves/). Select **Directory integration** to [configure directories](/cloudflare-one/email-security/settings/domains-and-directories/directories/).
## Managed email security operations
Managed email security operations allows you to review the results of phish submissions reviewed by the PhishGuard team.
It displays the following:
- Total [phish submissions](/cloudflare-one/email-security/settings/submission-settings/)
- Tracked incidents
- Median time to resolve
- Resolved track incidents
## Reports
Under Reports, you can review reports of threats discovered and resolved by the PhishGuard team.
If you select the three dots, you can:
- **View report details**: Report Details gives you the following information about each report:
- **Overview**: An Overview of the report. This includes date and time of the report, type of attack performed, and more.
- **Target and victimology**: Company targeted.
- **Details**: Displays information such as delivery disposition, current disposition, ES Alert ID, Message-ID, Timestamp, Subject, and Attempted Fraudulent Amount.
- **Indicators of compromise (IOC)**: [Indicators of compromise (IOC)](https://www.cloudflare.com/en-gb/learning/security/what-are-indicators-of-compromise/) are information about a specific security breach that can help security teams determine if an attack has taken place.
- Preview email.
- [Move email](/cloudflare-one/email-security/settings/detection-settings/auto-moves/).
# Retro Scan
Use Retro Scan to check whether your current email security provider has missed any threats. Cloudflare scans up to 14 days of emails in your Microsoft 365 mailbox and generates a report of malicious messages. Once the scan is complete, you will receive an email notification with a link to the report.
:::note
Retro Scan is only available for Microsoft 365 accounts.
:::
To start a free scan:
1. Log in to [Cloudflare One](https://one.dash.cloudflare.com/).
2. Select **Email security** > **Overview**.
3. Select **Start a free scan** > **Generate report**.
4. Enable your [Microsoft integration](/cloudflare-one/email-security/setup/post-delivery-deployment/api/m365-api/#enable-microsoft-integration). Once you have enabled your Microsoft integration, you will be redirected to a page where you will add your domains and specify your current email security system.
5. Generate Retro Scan report:
- **Connect domains**: Select at least one domain from your integration, then select **Continue**.
- **Select current solution**: Select the email security tool you are currently using, then select **Continue**.
- **Review details**: Confirm the domain and current solution you selected, then select **Continue**. You will receive an email notification once the report is ready.
6. When you receive the notification email, select the link to view the full report.
7. On the Cloudflare dashboard, select **View report**.
The dashboard will display **Overview** and **Details** pages.
### Overview
The **Overview** page shows a summary of the scan results across your selected domains, including:
- [Disposition evaluation](/cloudflare-one/email-security/monitoring/#disposition-evaluation), the verdict assigned to each scanned message (for example: malicious, suspicious, or spam)
- Malicious threat types
- Malicious targets, the top recipients targeted by malicious messages
- Malicious threat origins
### Details
The **Details** page lists up to 1,000 emails that were assigned a disposition during the scan. Select any email to review [details](/cloudflare-one/email-security/investigation/search-email/#details) about the message.
# Troubleshoot Email security
import { Render } from "~/components";
An example of allow policy is a phishing simulation product. You want to configure a phishing simulation product as **Accept sender** so Email security does not scan the messages (or crawl links) in these simulated messages.
Allow policies can be configured to match messages based on specific criteria such as individual email addresses, IP address ranges, or domains. This flexibility allows you to exempt legitimate messages from specific sources, even if those sources have low spam reputation or send bulk messages from their own servers.
Allow policies are used to mitigate false positives. When an email has been marked as malicious or suspicious, but you still want to receive that email, you configure that email as part of an allow policy.
### Accept sender
Allow policies in Email security give you the option to choose **Accept sender**.
Accept sender creates exceptions for messages that would otherwise be marked as spam, bulk, or spoof. However, Email security will continue to scan the message for maliciousness.
It is recommended to choose this option, as it is the safest option to protect your email inbox from malicious or suspicious activities.
When a marketing email does not follow the correct template, it may be marked as malicious or spam. It may not be possible to change the template. However, in this scenario, the marketing email is legitimate.
To make sure that users still receive the marketing email, you will have to select **Accept sender** and add the marketing domain in **Rule Type** > **Domains**.
**Accept sender** and **Domains** combined exempt marketing emails that may not follow the correct template.
Below you can find a list of known services you can add when configuring an Accept sender. We recommend you use [RegExr Validation](https://regexr.com/) to validate your regular expressions.
- Google
`drive-shares-noreply@google.com`
`.*@docs\.google\.com`
`.*@docos\.bounces\.google\.com`
`.*@calendar-server\.bounces\.google\.com`
`.*@alerts\.bounces\.google\.com`
`calendar-notification@google.com`
`.*\+bnc.*@`
`noreply-cloud@google.com`
`@`
`.*@doclist\.bounces\.google\.com`
- DocuSign
`.*@docusign\.net`
- Twitter - Mentions/Retweets
`notify@twitter.com`
- GitHub (mentions and notifications)
`noreply@(github|git)\.`
`notifications@github.com`
- Apache Foundations (Developers)
`.*@.*\.apache\.org`
`jira@apache.org`
- Atlassian
`jira@`
`jira@.atlassian.net`
`confluence@`
`confluence@.atlassian.net`
- Intercom
`notifications@intercom-mail.com`
`notifications@mail.intercom.io`
- SharePoint
`no-reply@sharepointonline.com`
- Box and Dropbox
`.*@dropbox\.com`
`noreply@box.com`
- Salesforce
`.*@chatter\.salesforce\.com`
`.*@.*\.(apex|bnc)\.salesforce\.com`
`.*@.*\.bnc(\.sandbox)?\.salesforce\.com`
- Webex - Invites/Mentions
`messenger@webex.com`
- Bulk mailers
`.*@.*mailchimp\.com`
`.*@mandrillapp\.com`
`.*mailspike\.org`
- LinkedIn
`invitations@linkedin.com`
- FBWork
`.*@fbworkmail\.com`
- Asana
`.*@mail\.asana\.com`
- EchoSign
`.*@mail\.echosign\.com`
- HelloSign
`noreply@(email|mail)\.hellosign\.com`
- Podio
`noreply@podio.com`
- Quip
`noreply.*@quip\.com`
- Zeplin
`no-reply@zeplin.io`
- DataHug
`notifications@datahug.com`
- Paperless
`.*@paperlesspost\.com`
- NetSuite
`.*@.*\.na\d\.netsuite\.com`
- FS-ISAC
`cyberintel@lists.fsisac.com`
- Expensify
`replies\+[0-9]+@expensify\.com`
- KnowBe4
`.*@[a-z]+\.knowbe4\.com`
`147\.160\.167\.([1-5][0-9]|6[0-2]|[1-9])`
- FreshDesk
`.*@.*\.freshdesk\.com`
- Webroot
`167.89.85.54`
`49.72.237.117`
- Wombat Egress IPs
**Training Platform**
`107.20.210.250`
`52.1.14.157`
- Phishing Assessment
`107.23.16.222`
`54.173.83.138`
## Configure allow policies
To configure allow policies:
1. Log in to [Cloudflare One](https://one.dash.cloudflare.com/).
2. Select **Email security**.
3. Select **Policies & rules**, then go to **Inbound** > **Allow policies**.
4. On the **Allow policies** page, select **Add a policy**.
5. On the **Add an allow policy** page, enter the policy information:
- **Input method**: Choose between **Manual input**, and **Uploading an allow policy**:
- **Manual input**:
- **Action**: Select one of the following to choose how Email security will handle messages that match your criteria:
- **Trust sender**: Messages will bypass all detections and link following.
- **Exempt recipient**: Message to this recipient will bypass all detections.
- **Accept sender**: Messages from this sender will be exempted from Spam, Spoof, and Bulk dispositions. Refer to [Allow policy configuration use cases](#use-case-1) for use case examples on how to configure allow policies for accept sender.
- **Rule type**: Specify the scope of your policy. Choose one of the following:
- **Email addresses**: Must be a valid email. Enter an email address whose emails are going to be exempted.
- **IP addresses**: This is the IP address of the email server. Any email address sent from this email server is going to be allowed. The IP address can only be IPv4. IPv6 and CIDR are invalid entries.
- **Domains**: Must be a valid domain.
- **Regular expressions**: Must be valid Java expressions. Regular expressions are matched with fields related to the sender email address (envelope from, header from, reply-to), the originating IP address, and the server name for the email. For example, you can enter `.*@domain\.com` to exempt any email address that ends with `domain.com`.
- **(Recommended) Sender verification**: This option enforces DMARC, SPF, or DKIM authentication. If you choose to enable this option, Email security will only honor policies that pass authentication.
- **Notes**: Provide additional information about your allow policy.
- **Uploading an allow policy**: Upload a file no larger than 150 KB. The file can only contain `Values`, `Rule Type`, `Is Regex`, `Sender Verification`, `Trusted Sender`, `Exempt Recipient`, `Acceptable Sender`, and `Notes` fields. The first row must be a header row. Refer to [CSV uploads](#csv-uploads) for an example file.
6. Select **Save**.
The following use cases show how you could configure allow policies for accept sender.
### Use case 1
This use case can affect companies such as Shopify, PayPal, and Docusign.
To solve this:
1. Create a [team submission](/cloudflare-one/email-security/submissions/team-submissions/).
2. Inform your Cloudflare contact about the escalation.
3. Do not set up allow policies or blocked senders. In this use case, configuring allow policies will create a security gap. Setting up blocked senders will block legitimate emails from providers such as Shopify, PayPal, and Docusign.
### Use case 2
This use case can cause the emails you want to receive to follow the auto-moves rules you set up. This use case affects emails from internal tools (such as Salesforce, Atlassian, and Figma) that are given an incorrect disposition.
To solve this, when you add an allow policy in the Cloudflare One dashboard:
1. Choose **Accept sender**.
2. Verify that **Sender verification (recommended)** is turned on.
### Use case 3
This use case impacts the emails from internal tools (such as Salesforce, Atlassian, and Figma) that are given an incorrect disposition.
To solve this, when you add an allow policy in the Cloudflare One dashboard:
1. Choose **Accept sender** based on the static IP you own.
2. Ensure that **Sender verification (recommended)** is turned off.
:::caution
Do not use email addresses or email domains for this policy as they can be easily spoofed without **Sender Verification (Recommended)** enabled.
:::
### CSV uploads
You can upload a file no larger than 150 KB. The file can only contain `Values`, `Rule Type`, `Is Regex`, `Sender Verification`, `Trusted Sender`, `Exempt Recipient`, `Acceptable Sender`, and `Notes` fields. The first row must be a header row.
An example file would look like this:
```txt
Values, Rule Type, Is Regex, Sender Verification, Trusted Sender, Exempt Recipient, Acceptable Sender, Notes
whale@notaphish.com, EMAIL, false, true, true, false, true, not a phish
```
## Export allow policies
To export all allow policies:
1. On the **Allow policies** page, select **Value(s)**. Selecting **Value(s)** will select all allow policies.
2. Select **Export to CSV**.
To export specific allow policies:
1. On the **Allow policies** page, select the allow policies you want to export.
2. Select **Export to CSV**.
## Edit allow policy
To edit an allow policy:
1. On the **Allow policies** page, select the allow policy you want to edit.
2. Select the three dots > **Edit**.
3. Edit the allow policy.
4. Select **Save**.
## Delete allow policy
To delete an allow policy:
1. On the **Allow policies** page, select the allow policy you want to delete.
2. Select the three dots > **Delete**.
3. On the pop-up message, select **Delete**.
To delete multiple allow policies at once:
1. On the **Allow policies** page, select the allow policies you want to delete.
2. Select **Action**.
3. Select **Delete**.
# Blocked content
Blocked content policies are only available on Enterprise plans and Enterprise + [PhishGuard](/cloudflare-one/email-security/phishguard/) plans.
Email security allows you to configure blocked content policies. A blocked content policy marks all messages containing specific words or phrases with a malicious [disposition](/cloudflare-one/email-security/reference/dispositions-and-attributes/).
## How blocked content works
Blocked content policies use regular expressions to define content patterns that Email security scans for in inbound email messages. You can block content in the subject, body, or both. When a message matches a blocked content policy, Email security automatically assigns it a malicious disposition.
This is useful when your organization needs to block emails containing specific terms associated with known threats, scams, or unwanted content, regardless of who sent them.
## Create a blocked content policy
To create a blocked content policy:
1. Log in to [Cloudflare One](https://one.dash.cloudflare.com/).
2. Select **Email security**.
3. Select **Policies & rules**, then go to **Inbound** > **Blocked content**.
4. Select **Create a policy**.
5. In **Step 1 - Name your policy**, enter a policy name and, optionally, a description in **Note**.
6. In **Step 2 - Build the pattern**, configure the content to block:
- **Scope**: Choose where to look for the content. Select one of the following:
- **Subject only**: Match the pattern in the email subject line only.
- **Body only**: Match the pattern in the email body only.
- **Subject and body**: Match the pattern in both the subject and body.
- **Pattern**: Enter a regular expression that defines the content to block. For example, entering `pay` will match content containing that pattern.
- **Exact word match**: Select this option to only match the exact word. For example, `pay` would match "pay" or "PAY", but not "payment" or "payable". Case is insensitive.
7. In **Step 3 - Validate your policy**, review and test your policy:
- **Review potential matches**: Displays a list of words that your pattern could match.
- **Test specific content against your regular expression**: Enter a sample text and select **Test policy** to verify whether your policy catches the expected content.
8. Select **Create policy**.
### Allowed regex modifiers
When building your pattern, you can use the following regex modifiers:
| Regex modifier | Description |
| -------------- | ------------------- |
| `.` | Any character |
| `*` | Zero or more |
| `+` | One or more |
| `?` | Optional |
| `\d` | Digit |
| `\w` | Word character |
| `\s` | Whitespace |
| `\b` | Word boundary |
| `[abc]` | Character class |
| `[^abc]` | Negated class |
| `[a-z]` | Range |
| `{n,m}` | Quantifier (max 50) |
| `\\|` | Or |
| `^` | Start |
| `$` | End |
## Edit a blocked content policy
To edit a blocked content policy:
1. On the **Blocked content** page, select the policy you want to edit.
2. Select the three dots > **Edit**.
3. Edit the blocked content policy.
4. Select **Save**.
## Delete a blocked content policy
To delete a blocked content policy:
1. On the **Blocked content** page, select the policy you want to delete.
2. Select the three dots > **Delete**.
3. On the pop-up message, select **Delete**.
To delete multiple blocked content policies at once:
1. On the **Blocked content** page, select the policies you want to delete.
2. Select **Action**.
3. Select **Delete**.
# Blocked senders
Email security marks all messages from these senders with a malicious [disposition](/cloudflare-one/email-security/reference/dispositions-and-attributes/).
## How blocked senders work
Blocked senders ensures messages from any sender is automatically marked as malicious, preventing them from reaching users' inbox.
Sometimes, the same email, IP address or domain always sends malicious emails to the company. In this case, you can add an email address, IP address or domain as a blocked sender. You can choose to enter a regular expression by turning **Regular expression** on.
## Configure blocked senders
To configure blocked senders:
1. Log in to [Cloudflare One](https://one.dash.cloudflare.com/).
2. Select **Email security**.
3. Select **Policies & rules**, then go to **Inbound** > **Blocked senders**.
4. On the **Blocked senders** page, select **Add a sender**.
5. Select the **Input method**: Choose between **Manual input**, and **Upload blocked sender list**:
- **Manual input**:
- **Sender type**:
- **Email addresses**: Must be a valid email.
- **IP addresses**: Can only be IPv4. IPv6 and CIDR are invalid entries.
- **Domains**: Must be a valid domain.
- **Regular expressions**: Must be valid Java expressions. Regular expressions are matched with fields related to the sender email address (envelope from, header from, reply-to), the originating IP address, and the server name for the email. For example, you can enter `.*@domain\.com` to exempt any email address that ends with `domain.com`.
- **Notes**: Provide additional information about the blocked sender policy.
- **Upload blocked sender list**: Upload a file that follows the [CSV upload format](#csv-uploads).
6. Select **Save**.
### CSV uploads
You can upload a file no larger than 150 KB. The file can only contain `Blocked Sender`, `Blocked Sender Type`, `Is Regex`, and `Notes` fields. The first row must be a header row.
An example file would look like this:
```txt
Blocked Sender, Blocked Sender Type, Is Regex, Notes
john.smith@gmail.com, EMAIL, false, John Smith
example.com, DOMAIN, false, Melanie Turner
```
## Export blocked senders
To export all blocked senders:
1. On the **Blocked senders** page, select **Sender**. Selecting **Sender** will select all blocked senders.
2. Select **Export to CSV**.
To export specific blocked senders:
1. On the **Blocked senders** page, select **Value(s)**. Select the blocked senders you want to export.
2. Select **Export to CSV**.
## Edit a blocked sender
To edit a blocked sender:
1. On the **Blocked senders** page, select the blocked sender you want to edit.
2. Select the three dots > **Edit**.
3. Edit the blocked sender.
4. Select **Save**.
## Delete a blocked sender
To delete a blocked sender:
1. On the **Blocked senders** page, select the blocked sender you want to delete.
2. Select the three dots > **Delete**.
3. On the pop up message, select **Delete**.
To delete multiple blocked senders at once:
1. On the **Blocked senders** page, select the senders you want to delete.
2. Select **Action**
3. Select **Delete**.
# Inbound
import { DirectoryListing } from "~/components"
phishing campaign. These small pattern assessments are dynamic in nature and — in many cases — no single pattern will determine the final verdict.
:::note[Detection vs. disposition]
Detection is the process Email security does to identify what threat an email may contain. An email can have multiple detections, but they will only have one and final disposition. The detections an email have will determine the disposition of the email.
:::
## Dispositions
Any traffic that flows through Email security is given a final disposition, which represents our evaluation of that specific message. Each message will receive only one disposition header, so your organization can take clear and specific actions on different message types.
You can use disposition values when [setting up auto-moves](/cloudflare-one/email-security/settings/detection-settings/auto-moves/).
### Available values
The following disposition values follow an order of maliciousness:
` | Alerts to mail from a newly registered domain. Formatted as yyyy-MM-dd HH:mm:ss ZZZ. |
| `NEW_DOMAIN_LINK=` | Alerts to mail with links pointing out to a newly registered domain. Formatted as yyyy-MM-dd HH:mm:ss ZZZ. |
| `ENCRYPTED` | Email message is encrypted. |
| `EXECUTABLE` | Email message contains an executable file. |
| `BEC` | Indicates that an email address was contained in your [impersonation registry](/cloudflare-one/email-security/settings/detection-settings/impersonation-registry/) list. Associated with `MALICIOUS` or `SPOOF` dispositions. |
### Header structure
When Email security adds a disposition header to an email message, that header matches the following format:
```txt
X-CFEmailSecurity-Attribute: [Value]
X-CFEmailSecurity-Attribute: [Value2]
```
# How Email security detects phish
import { GlossaryTooltip, Render } from "~/components";
phishing samples to Email security, so Cloudflare can process them and take necessary action.
Submitting missed phish samples to Cloudflare is of paramount importance and necessary for continuous protection. Submitting missed phish samples helps Cloudflare improve our machine learning (ML) models, and alerts us of new attack vectors before they become prevalent.
There are three routes you can use to report an email as a phish:
- Via Investigation, by [reclassifying an email](/cloudflare-one/email-security/settings/submission-settings/#reclassify-an-email).
- Via [PhishNet 365](/cloudflare-one/email-security/settings/submission-settings/phishnet-365/).
- Via [Submission addresses](/cloudflare-one/email-security/settings/submission-settings/submission-addresses/).
## Reclassify an email
1. Log in to [Cloudflare One](https://one.dash.cloudflare.com/).
2. Select **Email security** > **Investigation**.
3. On the **Investigation** page, under **Your matching messages**, select the message you want to reclassify. Select the three dots, then select **Submit for review**. By selecting **Submit for review**, you are requesting a new disposition for the message.
4. Select the new disposition, then select **Save**.
When you report an email as phish, this email will be displayed under [User submissions](/cloudflare-one/email-security/submissions/user-submissions/).
# PhishNet Microsoft 365
import { GlossaryTooltip } from "~/components";
PhishNet is an add-in button that helps users to submit directly to Email security phish samples missed by Email security's detection.
To set up PhishNet Microsoft 365:
1. Get the customized manifest URL from [Cloudflare One](https://one.dash.cloudflare.com/?to=/:account/email-security/settings/email-policy/phish-submission?tab=phish-submission).
2. Log in to the [Microsoft admin panel](https://admin.microsoft.com/).
3. Go to **Microsoft 365 admin center** > **Settings** > **Integrated Apps**.
4. Select **Upload custom apps**.
5. Choose **Provide link to manifest file** and paste the URL you copied from the Cloudflare One dashboard.
6. Verify and complete the wizard.
# PhishNet for Google Workspace
To set up PhishNet with Google Workspace you need admin access to your Google Workspace account.
## Set up PhishNet for Google Workspace
1. Log in to [Google Workspace Marketplace apps](https://workspace.google.com/marketplace/app/cloudflare_phishnet/11369379045) using this direct link and an administrator account.
2. Select **Admin install** to install Cloudflare PhishNet. Read the warning, and select **Continue**.
3. You will be redirected to the **Allow data access** page, where you can choose to install Cloudflare PhishNet for **Everyone at your organization**, or **Certain groups or organizational units**. If you choose the latter option, you will have to select the users in the next step.
4. After choosing the groups you want to install PhishNet for, agree with Google's terms of service, and select **Finish**.
5. Cloudflare PhishNet has been installed. Select **DONE**.
You have now successfully installed Cloudflare PhishNet.
## Submit phish with PhishNet
1. In your Gmail web client, open the message you would like to flag as either spam or phish.
2. Select the PhishNet logo on the side panel.
3. Under **Select Submission Type**, select **Spam** or **Phish**.
4. Select **Submit Report**.
# Submission addresses
To view the destination addresses of user and team submissions:
1. Log in to [Cloudflare One](https://one.dash.cloudflare.com/).
2. Select **Email security**.
3. Select **Settings** > **Submission addresses** > **View**.
The dashboard will display **User submission addresses** and **Team submission addresses**.
# Before you begin
import { Markdown } from "~/components";
Before you start the onboarding process, you will have to:
1. Choose a deployment path: Email security provides two deployment modes, [post-delivery](/cloudflare-one/email-security/setup/post-delivery-deployment/) for API and BCC/Journaling and [pre-delivery](/cloudflare-one/email-security/setup/pre-delivery-deployment/) for MX/Inline.
2. Learn about dispositions, impersonation registry, and submissions.
3. Know the steps to configure your email environment correctly.
The following table compares features available across API, BCC/Journaling and MX/Inline:
| Feature | Microsoft 365 | Google Workspace | Others (On-prem/Cloud) |
|--------------------- |----------------------------------------------------- |----------------------------------- |---------------------------------------------------------- |
| Deployment type | API and MX | BCC and MX | MX only |
| API integration | Microsoft Graph API | BCC only | None |
| BCC/Journaling | Uses a Journal Rule in the Microsoft Purview portal | Uses BCC rules | Uses journaling |
| Inline/MX Mode | MX records point to Cloudflare | MX records point to Cloudflare | MX records point to Cloudflare |
| Message remediation | Auto-moves through Read/Write API | Auto-moves through Read/Write API | Messages can be blocked, quarantined, or modified inline |
Note that:
- All email providers support MX/Inline deployment.
- Microsoft 365 or Google Workspace users who integrate Email security via API, BCC/Journaling can modify emails primarily through deletion or post-delivery [move](/cloudflare-one/email-security/settings/detection-settings/auto-moves/).
- Microsoft 365 or Google Workspace users who integrate Email security via MX/Inline can modify emails via post-delivery [move](/cloudflare-one/email-security/settings/detection-settings/auto-moves/), [link actions](/cloudflare-one/email-security/settings/detection-settings/configure-link-actions/) and [text add-ons](/cloudflare-one/email-security/settings/detection-settings/configure-text-add-ons/).
## 1. Choose a deployment
### Post-delivery deployment
When you choose post-delivery deployment, Cloudflare scans emails **after** they reach a users' inbox.
If you are a Microsoft 365 user, this is done via [Microsoft's Graph API](/cloudflare-one/email-security/setup/post-delivery-deployment/api/m365-api/) or [journaling](/cloudflare-one/email-security/setup/post-delivery-deployment/bcc-journaling/journaling-setup/m365-journaling/).
If you are a [Google Workspace](/cloudflare-one/email-security/setup/post-delivery-deployment/bcc-journaling/bcc-setup/gmail-bcc-setup/gmail-bcc-setup/) or [Microsoft Exchange](/cloudflare-one/email-security/setup/post-delivery-deployment/bcc-journaling/bcc-setup/bcc-microsoft-exchange/) user, this is done via BCC.
#### Why you should consider post-delivery deployment
Post-delivery deployment is time-efficient, because it does not involve MX changes. Post-delivery deployment does not disrupt mail flow. Post-delivery deployment allows you to enable [auto-move events](/cloudflare-one/email-security/settings/detection-settings/auto-moves/) to hard or soft delete messages, and synchronize your [directory](/cloudflare-one/email-security/settings/domains-and-directories/directories/) when you use Microsoft Graph API or Google Workspace.
:::note
When you choose post-delivery deployment:
- The threat is removed **after** the message has been delivered to the inbox.
- It requires API scopes, or BCC/Journaling rule configuration.
- Auto-move is only available in BCC/Journaling if you associate an integration.
:::
### Pre-delivery deployment
When you choose pre-delivery deployment, Cloudflare scans emails **before** they reach a users' inbox. The MX record points to Cloudflare.
#### Why you should consider pre-delivery deployment
Pre-delivery deployment provides you with the highest level of protection. It enforces [text add-ons](/cloudflare-one/email-security/settings/detection-settings/configure-text-add-ons/) or link rewrite at delivery.
Pre-delivery blocks threats in transit, and it adds banners or texts before the user views the email.
:::note
When you choose pre-delivery deployment:
- You must edit MX records or create a connector.
- You can enable auto-move events only after you associate an integration.
- Cloudflare [egress IPs](/cloudflare-one/email-security/setup/pre-delivery-deployment/egress-ips/) are allowed on downstream mail servers.
:::
## 2. Understand dispositions
Dispositions allow you to configure policies and tune reporting. For example, you can configure a policy to move suspicious emails to your junk folder.
Refer to [Dispositions](/cloudflare-one/email-security/reference/dispositions-and-attributes/#dispositions) to learn more about dispositions.
## 3. Set up the impersonation registry
Most [business email compromise (BEC)](https://www.cloudflare.com/en-gb/learning/email-security/business-email-compromise-bec/) targets executives or finance roles. You must add addresses of roles who are likely to be impersonated. Refer to [Impersonation registry](/cloudflare-one/email-security/settings/detection-settings/impersonation-registry/) to learn how to add a user to the impersonation registry.
Roles you may want to include in the impersonation registry are:
- C-suites
- Finance roles
- HR
- IT help-desk
- Legal
You should review your impersonation registry on a quarterly basis as roles change.
## 4. Submit messages
A submission is a change to an email's disposition **after** initial scanning. It is Cloudflare's built-in feedback loop for correcting false positives/negatives **and** training the detection models to get smarter over time. Refer to [Submit messages for review](/cloudflare-one/email-security/submissions/#submit-messages-for-review) to learn how to reclassify a message.
### Who can reclassify messages
[Security teams](/cloudflare-one/email-security/submissions/team-submissions/) and [end users](/cloudflare-one/email-security/submissions/user-submissions/) can perform a submission.
### Why you should submit messages
Submissions are critical because:
- **They help improve model accuracy**: Every validated submissions teaches Cloudflare's machine learning to recognise new lures, language, infrastructure, and benign patterns.
- **They reduce alert fatigue**: Correcting Suspicious or Spam emails that users actually want tailors detections to your organization, cutting noise in the dashboard.
- **They close the remediation loop**: When a disposition is upgraded to Malicious, Cloudflare auto-moves those emails out of every inbox (Graph API or Google Workspace API integrations).
- **They can help you log activity taken on any submission**: Each submission displays a submission ID, details about original, requested and final dispositions, and more. Refer to [Submit messages for review](/cloudflare-one/email-security/submissions/#submit-messages-for-review) to learn more about submissions.
To make the most of submissions:
1. Review submissions on a weekly basis.
2. Ensure you have an integration associated with any MX/Inline deployment. When you associate an integration, you will not need to upload the EMLs every time; Cloudflare can use APIs to receive a copy of your email messages.
3. Investigate any increase in [user submissions](/cloudflare-one/email-security/investigation/search-email/#user-submissions) (users may have found a phish that bypassed filters) and confirm that analyst-final dispositions align with your policies.
A correct use of submissions ensures that Email security delivers a stronger protection with less manual tuning.
## 5. Configuration checklist
Follow the below checklist to ensure your email environment is set up correctly:
| Step | Post-delivery | Pre-delivery |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | ------------- |
| Authorize integration ([Graph API](/cloudflare-one/email-security/setup/post-delivery-deployment/api/m365-api/#enable-microsoft-integration) or [Google Workspace](/cloudflare-one/email-security/setup/post-delivery-deployment/bcc-journaling/bcc-setup/gmail-bcc-setup/enable-gmail-integration/)) | Required[^1] | Required [^2] |
| Associate an integration with an MX/Inline domain | | Required |
| Add/verify domains | Required | Required |
| [Update MX records/connector](/cloudflare-one/email-security/setup/pre-delivery-deployment/mx-inline-deployment-setup/), then allow Cloudflare [egress IPs](/cloudflare-one/email-security/setup/pre-delivery-deployment/egress-ips/) on downstream mail server | | Required |
| Populate [impersonation registry](/cloudflare-one/email-security/settings/detection-settings/impersonation-registry/) and [allow](/cloudflare-one/email-security/policies/inbound/allow-policies/)/[block](/cloudflare-one/email-security/policies/inbound/blocked-senders/) lists | Required | Required |
| Configure [partner domain TLS](/cloudflare-one/email-security/setup/pre-delivery-deployment/partner-domain-tls/) and admin quarantine | | Required |
| Configure [text add-ons](/cloudflare-one/email-security/settings/detection-settings/configure-text-add-ons/) and [link actions](/cloudflare-one/email-security/settings/detection-settings/configure-link-actions/) | | Required |
| Send a test email and verify it appears in **Monitoring** > [**Email activity**](/cloudflare-one/email-security/monitoring/#email-activity) with expected disposition | Required | Required |
[^1]: Associating an integration with BCC/Journaling is required for post-delivery but not for pre-delivery.
[^2]: Still used for directory/auto‑move insight if desired as well as authorizing free API CASB.
Now that you know which deployment path to choose, you can begin your onboarding process.
# Manage domains
Once you have deployed your domain, Email security allows you to add, filter and edit domains. You can also choose to stop a domain from being scanned.
## Add domains
To protect a new domain:
1. Log in to [Cloudflare One](https://one.dash.cloudflare.com) > Email security.
2. Select **Settings**, go to **Domains** and select **View**.
3. Select **Add a domain**.
## Filter domains
To filter your domains:
1. Log in to [Cloudflare One](https://one.dash.cloudflare.com/) > **Email security**.
2. Go to **Settings** > **Domain management** > **Domains**, then select **View**.
3. Select **Show filters** > **Configured method**. Choose among the following filters: - **MS Graph API**: To view domains connected via MS Graph API. - **BCC/Journaling**: To view domains connected via BCC/Journaling. - **MX/Inline**: To view domains connected via MX/Inline. - **Retro Scan**: To view domains scanned by Retro Scan.
4. Select **Apply filters**.
## Edit domains
To edit your domains:
1. Log in to [Cloudflare One](https://one.dash.cloudflare.com/) > **Email security**.
2. Go to **Settings** > **Domain management** > **Domains**, then select **View**.
3. On the **Domains** page, locate your domain, select the three dots > **Edit**.
4. If you did not manually add your domain, you will only be able to edit **Hops**. If you manually added your domain, you will be able to edit **Domain name** and **Hops**.
5. Select **Save**.
## Prevent Cloudflare from scanning a domain
To stop scanning domains:
1. Log in to [Cloudflare One](https://one.dash.cloudflare.com/) > **Email security**.
2. Go to **Settings** > **Domain management** > **Domains**, then select **View**.
3. On the **Domains** page, locate your domain, select the three dots > **Stop scanning**.
4. Select **Stop scanning** again to stop Cloudflare from scanning your domain.
# Post-delivery deployment
import { DirectoryListing } from "~/components"
phishing attacks. The following email flow shows how this works:
:::note[Auto-moves for Microsoft Exchange customers]
Microsoft Exchange customers can auto-move if your email service is on-premise and you are using Microsoft Exchange online.
:::
## Configure Inbound Rule
1. Access Exchange's **Management Console**, and go to **Organization Configuration** > **Hub Transport**.
2. On the **Actions** pane, select **New Transport Rule**.
3. Give the transport rule a name and a description and select **Next**.
4. In the **Condition** configuration panel, select the option **from users that are inside or outside the organization** option. In the dropdown that opens, select **Outside the organization**.
5. Still in the same **Condition** configuration panel, add a second condition to the transport rule. Select **sent to users that are inside or outside the organization, or partners**. Keep the default value of **Inside the organization**.
6. Select **Next**.
7. In the **Action** configuration panel, select **Blind carbon copy (Bcc) the message to addresses**. Edit the **addresses** variable to add the addresses you want to copy as BCC.
8. In **Specify Recipient**, select the **down arrow** next to the **Add** button > **External E-Mail Address**.
9. Enter the BCC address provided by Email security. This address is specific to your account.
10. Select **OK** > **OK** to return to the main configuration page of the transport rule.
11. At the main configuration page of the transport rule, select **Next** to continue to the Exception configuration panel.
12. You do not need to configure an exception rule. Select **Next**.
13. In **Create Rule**, select the **New** button.
14. Select **Finish** to close the transport rule configuration panel. This will return you to the Exchange Management Console.
:::note
If you have multiple rules, you may need to change the order of the BCC rule and move it to the right location in your rule sequence. This is needed so you can send BCC messages to Email security. Usually, the Email security BCC rule will be at the top of the ruleset. The configured conditions of the Email security BCC rule will only trigger for inbound messages.
:::
## Email processing and reports
In BCC mode, all emails are put through automated phishing detections by Email security. Emails that trigger phishing detections are logged for reporting via product portal, email and Slack. Emails that do not trigger any detections are deleted.
## Next steps
hops . Then, select **Continue**. Configuring the hop count will determine where you want Cloudflare to sit in the email processing chain.
4. (**Optional**, select **Skip for now** to skip this step) **Move messages**: Refer to [Auto-moves](/cloudflare-one/email-security/settings/detection-settings/auto-moves/) to configure auto-moves. Then, select **Continue**.
5. **Select your processing location**: Configure where you want Cloudflare to process your email. **Global** will be the default option. If you choose **Global**, `@CF-emailsecurity.com` will be your regional service address. Once you have chosen your processing location, select **Continue**. Refer to [Regional processing](/cloudflare-one/email-security/reference/regional-processing/) to learn more.
6. **Review details**: Review your connected domains and service addresses. Then, select **Go to domains.**
Your domains are now added successfully.
On the **Domains** page, select the three dots > **View integration**. The dashboard will display your [domain information](/cloudflare-one/email-security/settings/domains-and-directories/domains/).
Under **Source**, the dashboard will display **Google integration**, along with the **Integration name**.
## Add additional domains
To add additional domains:
1. In [Cloudflare One](https://one.dash.cloudflare.com/), go to **Email security** > **Settings**.
2. Select **Connect an integration** > **BCC/Journaling** > **Integrate with Google** > **Authorize**.
3. **Connect domains**: Select the domains you want to add, then select **Next**.
4. (Optional) Select **Add manual domains**: Enter additional domains manually, then select **Next**.
5. (Optional) Select **Adjust hop count**: Enter the number of hops .
6. **Review details**: Review your selected domains, then use the following email to configure the service address with your third-party email provider:
```txt
@CF-emailsecurity.com
```
7. Select **Save**.
hops . Then, select **Continue**.
4. (**Optional**, select **Skip for now** to skip this step) **Move messages**: Refer to [Auto-moves](/cloudflare-one/email-security/settings/detection-settings/auto-moves/) to configure auto-moves. Then, select **Continue**.
5. **Select your processing location**: Configure where you want Cloudflare to [process your email](/cloudflare-one/email-security/reference/regional-processing/). **Global** will be the default option. If you choose **Global**, `@CF-emailsecurity.com` will be your regional service address. Once you have chosen your processing location, select **Continue**.
6. **Review details**: Review your connected domains and service addresses. Then, select **Go to domains.**
Your domains are now added successfully.
To view your connected domains:
1. Go to **Settings**.
2. Locate your domain, select the three dots > **View domain**. Selecting **View domain** will display information about your domain.
## 2. Configure journal rule
1. Log in to the [Microsoft Purview compliance portal](https://compliance.microsoft.com/homepage).
2. On the sidebar, go to **Settings** (the gear icon) > **Data Lifecycle Management** > **Exchange (legacy)**.
3. In **Send undeliverable journal reports to** enter the email address of a valid user account. Note that you cannot use a team or group address. Select **Save** once you entered the email address.
4. On the sidebar, go to **Solutions** > **Data Lifecycle Management** > **Exchange (legacy)**.
5. Select **Journal rules**.
6. Select **New rule** to configure a journaling rule, and configure it as follows:
- **Send journal reports to**: This is the address you copied and pasted in step 5 of [Connect your domains](/cloudflare-one/email-security/setup/post-delivery-deployment/bcc-journaling/journaling-setup/m365-journaling/#connect-your-domains).
- **Journal rule name**: `Journal Messages to Email security`
- **Journal messages sent or received from**: _Everyone_
- **Type of message to journal**: _External messages only_
7. Select **Next**.
8. Verify the information is correct, and select **Submit** > **Done**.
Once saved, the rule is automatically active. However, it may take a few minutes for the configuration to propagate and start pushing messages to Email security. After it propagates, you can [monitor your inbox](/cloudflare-one/email-security/monitoring/) in the Cloudflare dashboard to check the number of messages processed. This number will grow as journaled messages are sent to Email security from your Exchange server.
hops , and then select **Continue**.
4. **Select your processing location**: Configure where you want Cloudflare to process your email. **Global** will be the default option. If you choose **Global**, `@CF-emailsecurity.com` will be your regional service address. Once you have chosen your processing location, select **Continue**.
5. **Review details**: Review your connected domains and regional service address. Then, select **Go to domains.**
## Users who do not have domains with Cloudflare
If you do not have domains with Cloudflare, the Cloudflare dashboard will display two options:
- Add a domain to Cloudflare.
- Enter domain manually.
### Add a domain to Cloudflare
Selecting **Add a domain to Cloudflare** will redirect you to a new page where you will connect your domain to Cloudflare. Once you have entered an existing domain, select **Continue**.
### Enter domain manually
On the **Set up Email security** page:
1. **Connect domains**: Select at least one domain. Then, select **Continue**.
2. (**Optional**) **Add manual domains**: Manually enter additional domains. Then, select **Continue**.
3. (**Optional**) **Adjust hop count**: Enter the number of hops , and then select **Continue**.
4. **Configure service address with your third party email provider**: Copy and paste the service address into your third-party email provider to allow BCC/Journaling: `@CF-emailsecurity.com`.
5. **Review details**: Review your connected domains. Then, select **Go to domains.**
## Enable auto-moves
To enable auto-move events, you will have to associate an integration.
To associate an integration:
1. Log in to [Cloudflare One](https://one.dash.cloudflare.com/) > **Email security**.
2. Go to **Settings** > **Domain management** > **Domains** > Select **View**.
3. On the **Domain management** page, locate your domain, select the three dots, then select **Associate an integration**.
4. Select **Connect an integration**. Follow the steps to [enable the Microsoft 365 integration](/cloudflare-one/email-security/setup/post-delivery-deployment/api/m365-api/#enable-microsoft-integration).
5. Select the three dots, then select **Associate an integration**. Select the integration, then select **Associate**.
Now that your domain has an associated integration, enable [auto-move events](/cloudflare-one/email-security/settings/detection-settings/auto-moves/) on your domain.
# Egress IPs
When Email Security processes inbound messages through an [MX/Inline deployment](/cloudflare-one/email-security/setup/pre-delivery-deployment/mx-inline-deployment/), it re-delivers the messages to your mailbox from its own IP addresses, known as egress IPs (the source addresses Cloudflare sends outbound mail from). Your existing email provider (such as Microsoft 365 or Google Workspace) needs to be configured to accept connections from these addresses, otherwise it will reject the messages as coming from an unauthorized sender.
Add all of the following addresses to your mail provider's IP allowlist.
:::caution[Additional information for Microsoft 365]
Microsoft 365 does not support IPv6 addresses or the following IPv4 ranges:
- `104.30.32.0/19`
- `134.195.26.0/23`
If you use Microsoft 365, use the individual `/24` blocks (256 addresses each) listed in [Microsoft 365 `/24` addresses](#microsoft-365-24-addresses) instead.
:::
### IPv4
```txt
52.11.209.211
52.89.255.11
52.0.67.109
54.173.50.115
104.30.32.0/19
158.51.64.0/26
158.51.65.0/26
134.195.26.0/23
35.157.195.63
52.58.35.43
```
### IPv6
```txt
2405:8100:c400::/38
```
## Microsoft 365 `/24` addresses
Use these IPv4 addresses for Microsoft 365, instead of the `/19` and `/23` subnets:
```txt
104.30.32.0/24
104.30.33.0/24
104.30.34.0/24
104.30.35.0/24
104.30.36.0/24
104.30.37.0/24
104.30.38.0/24
104.30.39.0/24
104.30.40.0/24
104.30.41.0/24
104.30.42.0/24
104.30.43.0/24
104.30.44.0/24
104.30.45.0/24
104.30.46.0/24
104.30.47.0/24
104.30.48.0/24
104.30.49.0/24
104.30.50.0/24
104.30.51.0/24
104.30.52.0/24
104.30.53.0/24
104.30.54.0/24
104.30.55.0/24
104.30.56.0/24
104.30.57.0/24
104.30.58.0/24
104.30.59.0/24
104.30.60.0/24
104.30.61.0/24
104.30.62.0/24
104.30.63.0/24
134.195.26.0/24
134.195.27.0/24
```
# Pre-delivery deployment
import { DirectoryListing } from "~/components"
SMTP route for the Email security Email Protection Hosts
To add a new SMTP Route:
1. Go to **Network** > **SMTP Routes**.
2. Select **Add Route**.
3. Configure the new SMTP Route as follows:
- **Receiving Domain**: `a1s.mailstream`
- In **Destination Hosts**, select **Add Row**, and add the Email security MX hosts. Refer to the [Geographic locations](#5-geographic-locations) table for more information on which MX hosts to use.
## 3. Create Incoming Content Filters
To manage the mail flow between Email security and Cisco ESA, you need two filters:
- One to direct all incoming messages to Email security.
- One to recognize messages coming back from Email security to route for normal delivery.
### Incoming Content Filter - To Email security
To create a new Content Filter:
1. Go to **Mail Policies** > **Incoming Content Filters**.
2. Select **Add Filter** to create a new filter.
3. Configure the new Incoming Content Filter as follows:
- **Name**: `ESA_to_A1S`
- **Description**: `Redirect messages to Email security for anti-phishing inspection`
- **Order**: This will depend on your other filters.
- **Condition**: No conditions.
- **Actions**:
- For **Action** select **Send to Alternate Destination Host**.
- For **Mail Host** input `a1s.mailstream` (the SMTP route configured in step 2).
### Incoming Content Filter - From Email security
To create a new Content Filter:
1. Go to **Mail Policies** > **Incoming Content Filters**.
2. Select the **Add Filter** button to create a new filter.
3. Configure the new Incoming Content Filter as follows:
- **Name**: `A1S_to_ESA`
- **Description**: `Email security inspected messages for final delivery`
- **Order**: This filter must come before the previously created filter.
- **Conditions**: Add conditions of type **Remote IP/Hostname** with all the IP addresses mentioned in Egress IPs. For example:
| Order | Condition | Rule |
| ----- | -------------------- | -------------------- |
| `1` | `Remote IP/Hostname` | `Remote IP/Hostname` |
| `2` | `Remote IP/Hostname` | `52.89.255.11` |
| `3` | `Remote IP/Hostname` | `52.0.67.109` |
| `4` | `Remote IP/Hostname` | `54.173.50.115` |
| `5` | `Remote IP/Hostname` | `104.30.32.0/19` |
| `6` | `Remote IP/Hostname` | `158.51.64.0/26` |
| `7` | `Remote IP/Hostname` | `158.51.65.0/26` |
- Ensure that the _Apply rule:_ dropdown is set to **If one or more conditions match**.
- **Actions**: Select **Add Action**, and add the following:
| Order | Action | Rule |
| ----- | ----------------------------------------------- | ---------------- |
| --1 | `Skip Remaining Content Filters (Final Action)` | `skip-filters()` |
## 4. Add the Incoming Content Filter to the Inbound Policy table
Assign the Incoming Content Filters created in [step 3](#3-create-incoming-content-filters) to your primary mail policy in the Incoming Mail Policy table. Then, commit your changes to activate the email redirection.
## 5. Geographic locations
phishing emails directly to the mail server. To secure the email flow, you should enforce an email flow where inbound messages are accepted by Google Workspace only when they originate from Email security. This can be done by adding a connector to only allow email from Email security with TLS encryption. This step is optional but recommended.
:::caution[Important]
This step should not be performed until 72 hours after all domains in your Google Workspace have been onboarded to Email security, and Email security is their MX record. If a domain has not been onboarded or DNS is still propagating, you will impact production email flow for that domain.
:::
After 72 hours, the MX record DNS update will have sufficiently propagated across the Internet. It is now safe to secure your email flow. This will ensure that Google Workspace only accepts messages that are first received by Email security. This step is highly recommended to prevent threat actors from using cached MX entries to bypass Email security by injecting messages directly into Google Workspace.
1. Access the [Google Administrative Console](https://admin.google.com/), then select **Apps** > **Google Workspace** > **Gmail**.
2. Select **Spam, Phishing and Malware**.
3. Go to **Inbound gateway** and select **Edit Inbound gateway**.
4. Enable **Reject all mail not from gateway IPs** and select **Save**.
5. Select **Save** once more to commit and activate the configuration change in the Gmail advanced configuration console.
# Prerequisites
import { DirectoryListing } from "~/components"
phishing emails directly to the mail server. To secure the email flow, you should enforce an email flow where inbound messages are accepted by Microsoft 365 only when they originate from Email security. This can be done by adding a connector to only allow email from Email security with TLS encryption. This step is optional but recommended.
:::caution[Important]
This step should not be performed until 72 hours after all domains in your Microsoft 365 organization have been onboarded to Email security, and Email security is their MX record. If a domain has not been onboarded or DNS is still propagating, you will impact production email flow for that domain.
:::
#### Create Connector
1. Go to the new [Exchange admin center](https://admin.exchange.microsoft.com/#/homepage).
2. Go to **Mail flow** > **Connectors**.
3. Select **Add a connector**.
4. Go to **Connection from** > **Partner organization**.
5. Select **Next**.
6. Set the following options:
- **Name** - `Secure M365 Inbound`
- **Description** - `Only accept inbound email from Email security`
7. Select **Next**.
8. Make sure **By Verifying that the sender domain matches one of the following domains** is selected.
9. Enter `*` in the text field, and select **+**.
10. Select **Next**.
11. Make sure **Reject email messages if they aren't sent over TLS** is selected.
12. Still in the same screen, select **Reject email messages if they aren't sent from within this IP address range**, and enter all the egress IPs in the [Egress IPs](/cloudflare-one/email-security/setup/pre-delivery-deployment/egress-ips/) page.
13. Select **Next**.
14. Review your settings and select **Create connector**.
# 5 - Junk email folder and administrative quarantine
import { Render } from "~/components";
In this tutorial, you will learn to deliver `BULK` messages to the user's junk email folder, and `MALICIOUS`, `SPAM`, and `SPOOF` messages to the Administrative Quarantine (this requires an administrator to release the emails).
## Configure anti-spam policies
_Set the Spam Confidence Level (SCL)_ > _5_",
four: "step4-rules.png",
five: "`Email security Admin Managed Host Quarantine`",
six: " `MALICIOUS`, `UCE`, `SPOOF`",
seven: "_Redirect the message to_ > _hosted quarantine_",
eight: "step10-hosted-quarantine-case5.png",
}}
/>
# 4 - User managed quarantine and administrative quarantine
import { Render } from "~/components";
In this tutorial, you will learn to deliver `SPAM` and `SPOOF` messages to the user managed quarantine, and `MALICIOUS` messages to the administrative quarantine (this requires an administrator to release the emails).
## Create quarantine policies
_Set the Spam Confidence Level (SCL)_ > _5_",
four: "step4-rules-case4.png",
five: "`Email security User Quarantine Message Admin Release`",
six: "`MALICIOUS`",
seven:
"_Modify the message properties_ > _Set the Spam Confidence Level (SCL)_ > _9_",
eight: "step10-admin-release-case4.png",
}}
/>
# Use cases
import { DirectoryListing } from "~/components"
_Set the Spam Confidence Level (SCL)_ > _5_",
four: "step4-rules.png",
five: "`Email security User Quarantine Message`",
six: "`MALICIOUS`, `UCE`, `SPOOF`",
seven:
"_Modify the message properties_ > _Set the Spam Confidence Level (SCL)_ > _9_",
eight: "step10-user-quarantine.png",
}}
/>
# 2 - Junk email and user managed quarantine
import { Render } from "~/components";
In this tutorial, you will learn how to deliver `BULK` messages to the user's junk folder, and `SPAM` and `SPOOF` messages to the user managed quarantine.
## Create quarantine policies
_Set the Spam Confidence Level (SCL)_ > _5_",
four: "step4-rules.png",
five: "`Email security User Quarantine Message`",
six: "`UCE`, `SPOOF`",
seven:
"_Modify the message properties_ > _Set the Spam Confidence Level (SCL)_ > _9_",
eight: "step10-user-quarantine.png",
}}
/>
# Submissions
Submitting messages allows you to choose the disposition of your messages if the disposition is incorrect. This helps improve Email security's detection accuracy and ensures proper handling of email threats.
## Submit messages for review
To submit a message for review:
1. In [Cloudflare One](https://one.dash.cloudflare.com/), go to **Email security** and select **Investigation**.
2. On the **Investigation** page, under **Your matching messages**, select the message you want to reclassify.
3. Select the three dots, then select **Submit for review**.
4. Under **New disposition**, select among the following:
- **Malicious**: Traffic invoked multiple phishing verdict triggers, met thresholds for bad behavior, and is associated with active campaigns.
- **Spoof**: Traffic associated with phishing campaigns that is either non-compliant with your email authentication policies (SPF, DKIM, DMARC) or has mismatching Envelope From and `Header From` values.
- **Spam**: Traffic associated with non-malicious, commercial campaigns.
- **Bulk**: Traffic associated with [Graymail](https://en.wikipedia.org/wiki/Graymail_%28email%29), that falls in between the definitions of `SPAM` and `SUSPICIOUS`. For example, a marketing email that intentionally obscures its unsubscribe link.
- **Clean**: Traffic not associated with any phishing campaigns.
5. Select **Save**.
To submit messages in bulk, select **Select all messages** > **Action** > **Request submissions**.
To release messages in bulk, select **Select all messages** > **Action** > **Release**.
## Upload EML files
Email security classifies certain emails as "Clean". If you disagree with the disposition, you can upload an EML file and reclassify the email.
On the **Investigation** page:
1. Go to the email marked as **Clean**.
2. Select the three dots > **Submit for review**.
3. Upload the EML file.
4. Select a new disposition.
5. Select **Save**.
## View submissions
Once you have submitted your messages, you can access those on **Submissions**.
To view submissions:
1. Log in to [Cloudflare One](https://one.dash.cloudflare.com/).
2. Select **Email security** > **Submissions**.
3. Choose from the following submission types:
- [**Team submissions**](/cloudflare-one/email-security/submissions/team-submissions/): View emails your security team submitted for submissions.
- [**User submissions**](/cloudflare-one/email-security/submissions/user-submissions/): View emails your users submitted for submissions.
- [**Invalid submissions**](/cloudflare-one/email-security/submissions/invalid-submissions/): View submissions that could not be processed.
# Invalid submissions
A submission is invalid when:
- A submission has no EML file attached.
- A submission has been made with an incorrect file extension.
- A submission was made to the wrong team or user alias.
To ensure your submission is valid:
- Ensure your submission has a file attached with a `.eml` file extension.
- Ensure you configure the domain you are submitting emails for.
- Ensure policies are configured correctly.
To view invalid submissions:
1. Log in to [Cloudflare One](https://one.dash.cloudflare.com/).
2. Select **Email security** > **Submissions**.
3. Select **Invalid submissions**.
You can search by submission ID or submitted email.
You can filter based on **Date Range** and **Submitted by** (which will list emails that made the invalid submissions). Once you have configured your desired filters, select **Apply filters**.
## Enable notifications
To enable Invalid submission email notifications:
1. Log in to [Cloudflare One](https://one.dash.cloudflare.com/).
2. Select **Email security** > **Settings**.
3. Go to **Invalid submission emails** and turn on **Invalid submission email notifications**.
# Team submissions
Team submissions are the emails your security team submitted for submission. All team submissions receive a human review by Cloudflare.
## View team submissions
To view team submissions:
1. Log in to [Cloudflare One](https://one.dash.cloudflare.com/).
2. Select **Email security** > **Submissions**.
3. Select **Team submissions**.
## Filter team submissions
Select among the following filters:
- **Date Range**: You can select a date range from the last 7, last 30, and last 90 days.
- **Original disposition**: Select among the [available values](/cloudflare-one/email-security/reference/dispositions-and-attributes/#available-values).
- **Submitted as**: Select among the [available values](/cloudflare-one/email-security/reference/dispositions-and-attributes/#available-values).
- **Final disposition**: Select among the [available values](/cloudflare-one/email-security/reference/dispositions-and-attributes/#available-values).
- **Escalation**: Filter by team submissions that have been escalated or not. Select among `Yes`, `No`, or `All`.
Once you have selected all the filters, select **Apply filters**.
The dashboard will populate the table with the list of emails your security team submitted for submission, including a **Submission ID**, and the **Email subject**.
## View submission details
To gain more details on a specific submission:
1. Go to the submission you want to have more details for.
2. Select the three dots > select among **View more**, **View email message** and **View similar details**.
# User submissions
User submissions are the emails your users submitted for submission. User submissions help enhance our detection model, but can be escalated for human review.
Any email that is reported as [phish](/cloudflare-one/email-security/settings/submission-settings/#reclassify-an-email) will be displayed under **User submissions**.
:::note
[PhishGuard](/cloudflare-one/email-security/phishguard/) customers can have submissions analyzed when submitting at either user or team level. Any non-PhishGuard customer can still have submissions analyzed by submitting at team level.
:::
## View user submissions
To view user submissions:
1. Log in to [Cloudflare One](https://one.dash.cloudflare.com/).
2. Select **Email security** > **Submissions**.
3. Select **User submissions**.
## Filter user submissions
Select among the following filters:
- **Date Range**: Select a date range from the last 7, last 30, and last 90 days.
- **Original disposition**: Select among the [available values](/cloudflare-one/email-security/reference/dispositions-and-attributes/#available-values).
- **Submitted as**: Select among the [available values](/cloudflare-one/email-security/reference/dispositions-and-attributes/#available-values).
Once you have selected all the filters, select **Apply filters**.
The dashboard will populate the table with the list of emails your users submitted for submission, including a **Submission ID**, and the **Email subject**.
## View submission details
To gain more details on a specific submission:
1. Go to the submission you want to have more details for.
2. Select the three dots > select among **View more**, **View email message**, **View similar details**, and **Escalate**.
## Escalate a submission
To escalate a submission:
1. Go to the submission you want to escalate.
2. Select the three dots > select **Escalate**.
3. The dashboard will display a message to authorize escalation. Select **Escalate**.
# Identity FAQ
[❮ Back to FAQ](/cloudflare-one/faq/)
## Can Access work with multiple identity providers at the same time?
Yes. Your team can simultaneously use multiple providers, reducing friction when working with partners or contractors. Get started by adding your preferred identity providers as login methods in Zero Trust. Then, when securing a new application behind Access, you'll be able to choose which providers you want your users to log in with to reach that application.
## What if the identity provider my team uses is not listed?
You can add your preferred identity providers to Cloudflare Access even if you do not see them listed in Zero Trust, as long as these providers support SAML 2.0 or [OpenID Connect (OIDC)](/cloudflare-one/integrations/identity-providers/generic-oidc/).
## How do end users log out of an application protected by Access?
Access provides a URL that will end a user's current session.
To force log out of an Access application, go to:
`/cdn-cgi/access/logout`
To log out of an App Launcher session, go to:
`.cloudflareaccess.com/cdn-cgi/access/logout`
For more information, refer to our [session management page](/cloudflare-one/access-controls/access-settings/session-management/#log-out-as-a-user).
# Tunnels FAQ
import { Render } from "~/components";
[❮ Back to FAQ](/cloudflare-one/faq/)
## Can I create a Tunnel for an apex domain?
Yes. With [Named Tunnels](https://blog.cloudflare.com/argo-tunnels-that-live-forever/) you can create a CNAME at the apex that points to the named tunnel.
## Does Cloudflare Tunnel support Websockets?
Yes. Cloudflare Tunnel has full support for Websockets.
## Does Cloudflare Tunnel support gRPC?
Yes.