Skip to content

Commit 1369e58

Browse files
ranbelranbel
committed
SAML attribute features
1 parent d614346 commit 1369e58

File tree

2 files changed

+158
-2
lines changed

2 files changed

+158
-2
lines changed

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

Lines changed: 156 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -39,9 +39,9 @@ Obtain the following URLs from your SaaS application account:
3939

4040
8. Select the **Name ID Format** expected by your SaaS application (usually _Email_).
4141

42-
9. Copy the **SSO endpoint**, **Access Entity ID or Issuer**, and **Public key**.
42+
9. (Optional) Configure any additional [SAML attribute statements](#saml-attributes) required by your SaaS application.
4343

44-
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.
44+
10. Copy the **SSO endpoint**, **Access Entity ID or Issuer**, and **Public key**.
4545

4646
:::note[IdP groups]
4747

@@ -77,3 +77,157 @@ When acting as a SAML identity provider, Cloudflare will sign both the SAML Resp
7777
## 4. Test the integration
7878

7979
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.
80+
81+
## SAML attributes
82+
83+
[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:
84+
- `id` - UUID of the user's Access identity
85+
- `name` - Full name of the user (for example, `John Doe`)
86+
- `email` - User's email address
87+
- `groups` - Identity provider group membership
88+
89+
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.
90+
91+
### SAML attribute statements
92+
93+
To send additional SAML attributes to your SaaS application, configure the following fields for each attribute:
94+
95+
- **Name**: SAML attribute name
96+
- **SAML friendly name**: (Optional) A human readable name for the SAML attribute
97+
- **Name format**: Specify the **Name** format expected by the SaaS application:
98+
- `Unspecified`: (default) No specific format required.
99+
- `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`.
100+
- `Basic`: Name is a normal string such as `userName`.
101+
- **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.
102+
- **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.
103+
- **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**.
104+
105+
### Transformation
106+
107+
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.
108+
109+
For example, the following JSONata script modifies the `groups` attribute:
110+
111+
```jsonata title="JSONata expression"
112+
{
113+
"account_id": account_id,
114+
"amr": amr,
115+
"auth_status": auth_status,
116+
"common_name": common_name,
117+
"devicePosture": devicePosture,
118+
"device_id": device_id,
119+
"device_sessions": device_sessions,
120+
"email": email,
121+
"gateway_account_id": gateway_account_id,
122+
"geo": geo,
123+
"groups": $map($.groups, function($group) {
124+
{"group_name": $group.name, "id": $group.id}
125+
}),
126+
"iat": iat,
127+
"id": id,
128+
"idp": idp
129+
}
130+
```
131+
132+
Here is an example of an Access for SaaS payload before applying the transform:
133+
134+
```json title= "Before JSONata transform" collapse={2-25, 40-45}
135+
{
136+
"account_id": "699d98642c564d2e855e9661899b7252",
137+
"amr": [
138+
"pwd"
139+
],
140+
"auth_status": "NONE",
141+
"common_name": "",
142+
"device_id": "c1744f8b-faa1-48a4-9e5c-02ac921467fa",
143+
"device_sessions": {
144+
"49e653db-991e-11ee-af26-2243bf8c3428": {
145+
"last_authenticated": 1703004275
146+
}
147+
},
148+
"devicePosture": {
149+
"8534a230-e85e-4183-8964-a4b7dcf72986": {
150+
"rule_name": "Warp",
151+
"success": true,
152+
"type": "warp"
153+
}
154+
},
155+
"email": "[email protected]",
156+
"gateway_account_id": "bTSquyUGwLQjYJn8cI8S1h6M6wU",
157+
"geo": {
158+
"country": "US"
159+
},
160+
"groups": [
161+
{
162+
"id": "12fdf91a-fb23-41b3-995a-de2f72c61d0e",
163+
"name": "IdentityProtection-RiskyUser-RiskLevel-low"
164+
},
165+
{
166+
"id": "12348f47-8234-4860-a03f-c2a1513f267b",
167+
"name": "Global Administrator"
168+
},
169+
{
170+
"id": "11235980-87d7-4917-b0aa-74c01914c40e",
171+
"name": "Application Administrator"
172+
}
173+
],
174+
"iat": 1659474397,
175+
"id": "OidHvkPt-I-13IBSnd77UJ8cHgsrUpjs3W6_4t6ES7M",
176+
"idp": {
177+
"id": "b08e8c0c-a75d-4b3f-8e7b-cd427b7c7b47",
178+
"type": "azureAD"
179+
}
180+
```
181+
182+
Here is the payload after applying the example JSONata transform:
183+
184+
```json title="After JSONata transform" collapse={2-25, 40-45}
185+
{
186+
"account_id": "699d98642c564d2e855e9661899b7252",
187+
"amr": [
188+
"pwd"
189+
],
190+
"auth_status": "NONE",
191+
"common_name": "",
192+
"devicePosture": {
193+
"8534a230-e85e-4183-8964-a4b7dcf72986": {
194+
"rule_name": "Warp",
195+
"success": true,
196+
"type": "warp"
197+
}
198+
},
199+
"device_id": "c1744f8b-faa1-48a4-9e5c-02ac921467fa",
200+
"device_sessions": {
201+
"49e653db-991e-11ee-af26-2210bf8c3428": {
202+
"last_authenticated": 1703004275
203+
}
204+
},
205+
"email": "[email protected]",
206+
"gateway_account_id": "bTSquyUGwLQjYJn8cI8S1h6M6wU",
207+
"geo": {
208+
"country": "US"
209+
},
210+
"groups": [
211+
{
212+
"group_name": "IdentityProtection-RiskyUser-RiskLevel-low",
213+
"id": "62fdf91a-fb4f-41b3-995a-de2f72c61d0e"
214+
},
215+
{
216+
"group_name": "Global Administrator",
217+
"id": "25928f47-8465-4860-a03f-c2a1513f267b"
218+
},
219+
{
220+
"group_name": "Application Administrator",
221+
"id": "55225980-87d7-4917-b0aa-74c01914c40e"
222+
}
223+
],
224+
"iat": 1659474397,
225+
"id": "OidHvkPt-I-13IBSnd77UJ8cHgsrUpjs3W6_4t6ES7M",
226+
"idp": {
227+
"id": "b08e8c0c-a75d-4b3f-8e7b-cd427b7c7b47",
228+
"type": "azureAD"
229+
}
230+
}
231+
```
232+
233+
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‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,4 +10,6 @@ import { DirectoryListing } from "~/components"
1010

1111
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.
1212

13+
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.
14+
1315
<DirectoryListing />

0 commit comments

Comments
 (0)