[ZT] Access for SaaS: SAML attributes

src/content/docs/cloudflare-one/applications/configure-apps/saas-apps/generic-saml-saas.mdx

@@ -39,9 +39,9 @@ Obtain the following URLs from your SaaS application account:
 
 8. Select the **Name ID Format** expected by your SaaS application (usually _Email_).
 
-9. Copy the **SSO endpoint**, **Access Entity ID or Issuer**, and **Public key**.
+9. (Optional) Configure any additional [SAML attribute statements](#saml-attributes) required by your SaaS application.
 
-10. If your SaaS application requires additional **SAML attribute statements**, add the mapping of your IdP's attributes you would like to include in the SAML statement sent to the SaaS application.
+10. Copy the **SSO endpoint**, **Access Entity ID or Issuer**, and **Public key**.
 
 :::note[IdP groups]
 
@@ -77,3 +77,157 @@ When acting as a SAML identity provider, Cloudflare will sign both the SAML Resp
 ## 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/identity/idp-integration/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 and 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/identity/idp-integration/generic-saml/#saml-headers-and-attributes) or [OIDC claim](/cloudflare-one/identity/idp-integration/generic-oidc/#oidc-claims) that was configured in a Zero Trust IdP integration.
+	- **Required**: If a claim 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**.
+
+### Transformation
+
+In **Advanced settings** > **Transformation**, you can enter a [JSONata](https://jsonata.org/) script that modifies SAML attributes before they are sent to the SaaS application. This is useful for setting defaults, excluding email addresses, or ensuring usernames meet arbitrary criteria.
+
+For example, the following JSONata script modifies the `groups` attribute:
+
+```jsonata 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, "id": $group.id}
+  }),
+  "iat": iat,
+  "id": id,
+  "idp": idp
+}
+```
+
+Here is an example of an Access for SaaS payload before applying the transform:
+
+```json title= "Before JSONata transform" collapse={2-25, 40-45}
+{
+  "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": "[email protected]",
+  "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"
+  }
+```
+
+Here is the payload after applying the example JSONata transform:
+
+```json title="After JSONata transform" collapse={2-25, 40-45}
+{
+  "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": "[email protected]",
+  "gateway_account_id": "bTSquyUGwLQjYJn8cI8S1h6M6wU",
+  "geo": {
+    "country": "US"
+  },
+  "groups": [
+    {
+      "group_name": "IdentityProtection-RiskyUser-RiskLevel-low",
+      "id": "62fdf91a-fb4f-41b3-995a-de2f72c61d0e"
+    },
+    {
+      "group_name": "Global Administrator",
+      "id": "25928f47-8465-4860-a03f-c2a1513f267b"
+    },
+    {
+      "group_name": "Application Administrator",
+      "id": "55225980-87d7-4917-b0aa-74c01914c40e"
+    }
+  ],
+  "iat": 1659474397,
+  "id": "OidHvkPt-I-13IBSnd77UJ8cHgsrUpjs3W6_4t6ES7M",
+  "idp": {
+    "id": "b08e8c0c-a75d-4b3f-8e7b-cd427b7c7b47",
+    "type": "azureAD"
+  }
+}
+```
+
+In this example, the JSONata transform changed the `group.name` field from `name` to `group_name`. Additionally, we changed the value of `group.id` from ___ to ____.

src/content/docs/cloudflare-one/applications/configure-apps/saas-apps/index.mdx

@@ -10,4 +10,6 @@ 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 or generic OIDC guide and consult your SaaS application's documentation.
+
 <DirectoryListing />