[ZT] Access for SaaS OIDC (#20603)

ranbel · ajholland · patriciasantaana · web-flow · commit 5190ca1d5438 · 2025-03-11T11:07:12.000-04:00
* add oidc claim section

* oidc features

* Update src/content/docs/cloudflare-one/applications/configure-apps/saas-apps/generic-oidc-saas.mdx

Co-authored-by: Alex Holland &lt;ajholland77@gmail.com&gt;

* Update src/content/docs/cloudflare-one/applications/configure-apps/saas-apps/generic-oidc-saas.mdx

Co-authored-by: Alex Holland &lt;ajholland77@gmail.com&gt;

* Update src/content/docs/cloudflare-one/applications/configure-apps/saas-apps/generic-oidc-saas.mdx

Co-authored-by: Alex Holland &lt;ajholland77@gmail.com&gt;

* add oidc flow details

* Update src/content/docs/cloudflare-one/applications/configure-apps/saas-apps/generic-oidc-saas.mdx

Co-authored-by: Patricia Santa Ana &lt;103445940+patriciasantaana@users.noreply.github.com&gt;

---------

Co-authored-by: Alex Holland &lt;ajholland77@gmail.com&gt;
Co-authored-by: Patricia Santa Ana &lt;103445940+patriciasantaana@users.noreply.github.com&gt;
diff --git a/src/content/docs/cloudflare-one/applications/configure-apps/saas-apps/generic-oidc-saas.mdx b/src/content/docs/cloudflare-one/applications/configure-apps/saas-apps/generic-oidc-saas.mdx
@@ -37,14 +37,7 @@ Some SaaS applications provide the Redirect URL after you [configure the SSO pro
 
 6. Select **Add application**.
 
-7. In **Scopes**, select the attributes that you want Access to send in the ID token.
-
-   | Scope     | Description                                          |
-   | --------- | ---------------------------------------------------- |
-   | `openid`  | Include a unique identifier for the user (required). |
-   | `email`   | Include the user's email address.                    |
-   | `profile` | Include all custom OIDC claims from the IdP.         |
-   | `groups`  | Include the user's IdP group membership.             |
+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.
 
@@ -81,3 +74,62 @@ Next, configure your SaaS application to require users to log in through Cloudfl
 ## 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.
+
+## OIDC claims
+
+OIDC claims refer to the user identity characteristics that Cloudflare Access shares with your OIDC SaaS application upon successful authentication. An OIDC scope defines a set of OIDC claims. By default, Cloudflare Access passes all [standard claims](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims) that are included in the `openid`, `email`, `profile`, and `groups` scopes (if available).
+
+   | Scope     | Description                                          |
+   | --------- | ---------------------------------------------------- |
+   | `openid`  | Includes a unique identifier for the user (required). |
+   | `email`   | Includes the user's email address.                    |
+   | `profile` | Includes the user's name and all custom OIDC claims from the IdP.         |
+   | `groups`  | Include the user's IdP group membership.             |
+
+In your Access application, you can configure the OIDC scopes and claims that Access sends to the SaaS provider. For example, you can remove the `groups` scope if your SaaS application does not need to receive user group information.
+
+### Filter groups
+
+In **Group filter regex**, you can enter a regular expression to define the identity provider groups that you want to include in the `groups` scope. For example, if you enter the expression `(^TEAM-Engineering-.$)|(^TEAM-Product-.$)`, only groups with names like TEAM-Engineering-A or TEAM-Product-B would get passed to the SaaS application.
+
+### Add claims
+
+To add additional OIDC claims onto the ID token sent to your SaaS application, configure the following fields for each claim:
+
+	- **Name**: OIDC claim name
+	- **Scope**: Select the OIDC scope where this claim should be included. In most cases, we recommend selecting `profile` since it already includes other custom claims from the IdP.
+	- **IdP claim**: The identity provider value that should map to this OIDC claim. 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**.
+
+## Advanced settings
+
+### Access token lifetime
+
+The OIDC Access token authorizes users to connect to the SaaS application through Cloudflare Access. You can set an **Access token lifetime** to determine the window in which the token can be used to establish authentication with the SaaS application — if it expires, the user must re-authenticate through Cloudflare Access. To balance security and user convenience, Cloudflare recommends configuring a short Access token lifetime in conjunction with a longer **Refresh token lifetime** (if supported by your application). When the access token expires, Cloudflare will use the refresh token to obtain a new access token after checking the user's identity against your Access policies. When the refresh token expires, the user will need to log back in to the identity provider. The refresh token lifetime should be less than your [global session duration](/cloudflare-one/identity/users/session-management/), otherwise the global session would take precedence.
+
+:::note
+<Render file="access/saas-apps/saas-sessions" params={{ session: "OIDC Access tokens", token: "Access token"}} />
+:::
+
+### OIDC flows
+
+Some SaaS applications require SSO providers to provide tokens to the browser without backend authentication. Access for SaaS supports the following OIDC flows:
+
+- **No additional OIDC flows**: (Default) Recommended unless your application requires additional flows.
+- **Hybrid flows**: Used by applications that require information from the ID token before authenticating the user.
+- **Implicit flows**: (Not recommended) Typically used by frontend applications that cannot store secrets and which do not support **PKCE without client secret**.
+
+Cloudflare allows various `response_type` values in the authorization request depending on the selected flow. For example, the implicit flow allows Cloudflare to return the ID token, Access token, or both the ID token and Access token from the Authorization endpoint.
+
+| `response_type` values | Default flow | Hybrid flow | Implicit flow |
+| -------------- | -- | -- | -- |
+| `code` | ✅ | ✅ | ❌ |
+| `id_token` | ❌ |✅  | ✅ |
+| `token` | ❌| ✅ |✅  |
+
+To include `id_token` in the authorization request, turn on **Return ID Token from Authorization Endpoint**. To include `token`, turn on **Return Access Token from Authorization Endpoint**
+
+:::note
+[Refresh tokens](#access-token-lifetime) are not supported with Hybrid or Implicit flows.
+:::
diff --git a/src/content/docs/cloudflare-one/applications/configure-apps/saas-apps/generic-saml-saas.mdx b/src/content/docs/cloudflare-one/applications/configure-apps/saas-apps/generic-saml-saas.mdx
@@ -100,7 +100,7 @@ To send additional SAML attributes to your SaaS application, configure the follo
 			- `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.
+	- **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 transforms
diff --git a/src/content/docs/cloudflare-one/identity/users/session-management.mdx b/src/content/docs/cloudflare-one/identity/users/session-management.mdx
@@ -49,7 +49,7 @@ The application token will expire after this period of time (unless you have set
 
 #### SaaS application sessions
 
-Access session durations only control the front door to a SaaS app; Access does not control how long the user can stay in the SaaS app itself. For example, if the user logs out of the SaaS app and then comes back to it, a valid Access application token allows them to re-authenticate without another login. The SaaS app issues its own authorization cookie that manages the user's session within the app.
+<Render file="access/saas-apps/saas-sessions" params={{ session: "Access session durations", token: "Access application token"}} />
 
 ### Set policy session duration
 
diff --git a/src/content/partials/cloudflare-one/access/saas-apps/saas-sessions.mdx b/src/content/partials/cloudflare-one/access/saas-apps/saas-sessions.mdx
@@ -0,0 +1,7 @@
+---
+params:
+  - session
+  - token
+---
+
+{props.session} only control the front door to a SaaS app; Access does not control how long the user can stay in the SaaS app itself. For example, if the user logs out of the SaaS app and then comes back to it, a valid {props.token} allows them to re-authenticate without another login. The SaaS app issues its own authorization cookie that manages the user's session within the app.

-Original file line number
+Diff line change
@@ @@ -0,0 +1,7 @@ @@
 +---
 +params:
 +  - session
 +  - token
 +---
++
 +{props.session} only control the front door to a SaaS app; Access does not control how long the user can stay in the SaaS app itself. For example, if the user logs out of the SaaS app and then comes back to it, a valid {props.token} allows them to re-authenticate without another login. The SaaS app issues its own authorization cookie that manages the user's session within the app.