← Cloudflare One / cloudflare-one / integrations / identity-providers

Generic SAML 2.0

Cloudflare One integrates with any identity provider that supports SAML 2.0. If your identity provider is not listed in the integration list of login methods in Cloudflare One, it can be configured using SAML 2.0 (or OpenID if OIDC based). Generic SAML can also be used if you would like to pass additional SAML headers or claims for an IdP in the integration list.

Prerequisites

Minimum requirements for identity providers:

The IdP must conform to SAML 2.0.
The IdP must provide a Single sign-on URL, an Entity ID or Issuer URL, and a Signing certificate.
The IdP must include the signing public key in the SAML response.

1. Create an application in your identity provider

Most identity providers allow users to create an Application. In this context, an application is a set of parameters that the identity provider will then pass on to Cloudflare to establish an integration.

The typical setup requirements are:

Create a new integration in the identity provider with the type set as SAML.
Set both the Entity/Issuer ID and the Single sign-on URL to:
```
https://<your-team-name>.cloudflareaccess.com/cdn-cgi/access/callback
```
You can find your team name in the Cloudflare dashboard ↗ under Settings > Team name and domain > Team name.
Set the Name ID/Email format to emailAddress.
(Optional) Set the signature policy to Always Sign.

(Optional) Upload SAML metadata

If your identity provider supports metadata file configuration, you can use the default or identity provider specific metadata endpoint:

Default: https://<your-team-name>.cloudflareaccess.com/cdn-cgi/access/saml-metadata
Identity provider specific: https://<your-team-name>.cloudflareaccess.com/cdn-cgi/access/<identity-provider-id>/saml-metadata, where <identity-provider-id> is the id value obtained from List Access identity providers. Use this endpoint if your IdP requires a configuration not defined in the default metadata file.

To download the SAML metadata file, copy-paste the metadata endpoint into a web browser and save the page as an .xml file. Upload this XML file to the identity provider.

2. Add a SAML identity provider to Cloudflare One

In the Cloudflare dashboard ↗, go to Zero Trust > Integrations > Identity providers.
Select Add new identity provider and select SAML.
Choose a descriptive name for your identity provider.
Enter the Single Sign on URL, IdP Entity ID or Issuer URL, and Signing certificate obtained from your identity provider.
(Optional) To enable SCIM, refer to Synchronize users and groups.
(Optional) Under Optional configurations, configure additional SAML options.
Select Save.

Add the following permission to your cloudflare_api_token ↗:
- Access: Organizations, Identity Providers, and Groups Write

Configure the cloudflare_zero_trust_access_identity_provider ↗ resource:

resource "cloudflare_zero_trust_access_identity_provider" "generic_saml_example" {
	account_id = var.cloudflare_account_id
	name       = "Generic SAML example"
	type       = "saml"
	config 		 = {
		sso_target_url = "https://example.com/1234/sso/saml"
		issuer_url = "https://example.com/1234"
		idp_public_certs = ["-----BEGIN CERTIFICATE-----\nXXXXX\n-----END CERTIFICATE-----"]
		sign_request = false
		email_attribute_name = "email"
		attributes = ["employeeID", "groups"]
	}
}

3. Test the connection

You can now test the IdP integration. A success response should return the configured SAML attributes.

Synchronize users and groups

The generic SAML integration allows you to synchronize user groups and automatically deprovision users using SCIM.

SCIM affects Access and Gateway policy evaluation differently.

Access evaluates a user's identity and group membership from the SAML assertion or OIDC token returned by the identity provider during authentication. SCIM provides readable group names in the Access policy builder, but Access does not use SCIM group membership to evaluate a login. If you turn on Enable user deprovisioning, removing a user from the SCIM application revokes their active Access sessions. You can also configure SCIM to revoke sessions after group membership changes. Access evaluates the updated identity provider data when the user authenticates again.

Gateway evaluates identity-based policies against the User Registry identity. SCIM updates this identity when users or group memberships change, without waiting for the user to authenticate again. Cloudflare One Client device profiles use the same synchronized identity.

Prerequisites

Your identity provider must support SCIM version 2.0.

1. Enable SCIM in Cloudflare One

In the Cloudflare dashboard ↗, go to Zero Trust > Integrations > Identity providers.
Find the IdP integration and select Edit.
Turn on Enable SCIM.
(Optional) Configure the following settings:

Enable user deprovisioning: Revoke a user's active session when they are removed from the SCIM application in IdP. This will invalidate all active Access sessions and prompt for reauthentication for any Cloudflare One Client session policies.
Remove user seat on deprovision: Remove a user's seat from your Cloudflare One account when they are removed from the SCIM application in IdP.
SCIM identity update behavior: Choose what happens in Cloudflare One when the user's identity updates in IdP.
- Automatic identity updates: Automatically update the User Registry identity when IdP sends an updated identity or group membership through SCIM. This identity is used for Gateway policies and Cloudflare One Client device profiles; Access will read the user's updated identity when they reauthenticate.
- Group membership change reauthentication: Revoke a user's active session when their group membership changes in IdP. This will invalidate all active Access sessions and prompt for reauthentication for any Cloudflare One Client session policies. Access will read the user's updated group membership when they reauthenticate.
- No action: Update the user's identity the next time they reauthenticate to Access or the Cloudflare One Client.

Select Regenerate Secret. Copy the SCIM Endpoint and SCIM Secret. You will need to enter these values into IdP.
Select Save.

The SCIM secret never expires, but you can manually regenerate the secret at any time.

2. Configure SCIM in the IdP

Setup instructions vary depending on the identity provider. In your identity provider, you will either need to edit the original SSO application or create a new SCIM application. Refer to your identity provider's documentation for more details. For example instructions, refer to our Okta or JumpCloud guides.

IdP groups

If you would like to build policies based on IdP groups:

Ensure that your IdP sends a groups field. The naming must match exactly (case insensitive). All other values will be sent as a SAML attribute.
If your IdP requires a new SCIM application, ensure that its groups match the groups in the original SSO application. Matching the groups keeps the Gateway identity synchronized with the groups that the IdP returns when the user authenticates to Access.

3. Verify SCIM provisioning

To check if user identities were updated in Cloudflare One, view your SCIM provisioning logs.

Optional configurations

SAML integrations support additional security and configuration options.

Encrypt SAML assertions

SAML assertion encryption ensures that SAML assertions sent from your identity provider to Cloudflare Access are encrypted end-to-end.

Without encryption, SAML assertions are transmitted in plaintext after TLS termination, which means they could be visible to browser extensions or client-side malware. With encryption turned on, your IdP encrypts the assertion using a public certificate from Cloudflare, and only Access can decrypt it with the corresponding private key.

To turn on SAML assertion encryption:

In the Cloudflare dashboard ↗, go to Zero Trust > Integrations > Identity providers.
Select your SAML identity provider and select Edit.
Under SAML encryption, turn on the Enable SAML encryption toggle. Access will automatically generate an encryption certificate.
Copy the displayed certificate (in PEM format) or the certificate set ID.
In your identity provider, upload the Cloudflare encryption certificate and turn on assertion encryption. Refer to your IdP documentation for the exact configuration steps.
Select Save.

After you turn on encryption, Access will reject any unencrypted assertions from the configured IdP. If you turn off encryption, Access will reject any encrypted assertions until encryption is turned back on.

Supported encryption algorithms

Access supports the following encryption algorithms:

Algorithm type	Supported values
Content encryption	AES-128-CBC, AES-256-CBC, AES-128-GCM, AES-256-GCM
Key transport	RSA-OAEP (XML Encryption 1.0 and 1.1), RSA-1.5

Rotate encryption certificates

Encryption certificates are valid for one year. Thirty days before a certificate expires, Access automatically generates a replacement certificate. The expiring certificate remains valid until its expiration date, giving you time to upload the new certificate to your IdP.

To manually rotate a certificate:

In the Cloudflare dashboard ↗, go to Zero Trust > Integrations > Identity providers.
Select your SAML identity provider and select Edit.
Under SAML encryption, select Rotate certificate.
Upload the new certificate to your identity provider.

Sign SAML authentication request

This optional configuration signs the Access JWT with the Cloudflare Access public key to ensure that the JWT is coming from a legitimate source. The Cloudflare public key can be obtained at https://<your-team-name>.cloudflareaccess.com/cdn-cgi/access/certs.

Email attribute name

Many Access policies depend on a user's email address. Some identity providers have a different naming for the email address attribute (for example, Email, e-mail, emailAddress). This can typically be checked in the identity provider's SAML test option.

Example in Okta:

Preview the SAML assertion from the Okta dashboard

Determine the email attribute name from the SAML assertion

SAML headers and attributes

Cloudflare Access supports SAML (Security Assertion Markup Language) attributes and SAML headers for all SAML IdP integrations.

SAML attributes refer to specific data points or characteristics that the IdP shares about the authenticated user. These attributes often include details like email address, name, or role, and are passed along to the service provider upon successful authentication.

SAML headers are metadata in the SAML protocol communication which convey information about the sender, recipient, and the message itself. These headers can be leveraged to provide extra context or control over the communication.

SAML attributes

SAML attributes are added to the Access JWT. These attributes can then be consumed by self-hosted or SaaS applications connected to Access. Any SAML attribute configured in the SAML integration must also be sent from the IdP.

Example in Okta:

How to receive these SAML attributes in Cloudflare:

Configure Cloudflare to receive SAML attributes

SAML headers

If an application specifically requires SAML attributes upon sign-in, then the attributes can be passed as headers. The Attribute name should be the value coming from your IdP (for example, department). You can assign any Header name to the attribute. The header name will appear in the response headers when Access makes the initial authorization request to https://<your-team-name>.cloudflareaccess.com/cdn-cgi/access/callback.

Multi-record SAML attributes

Cloudflare Access extends support for multi-record SAML attributes such as groups. These attributes are parsed out and can be individually referenced in policies. This feature enables granular access control and precise user authorization in applications.

Cloudflare Access does not currently support partial attribute value references.