Merge pull request #218407 from MicrosoftGuyJFlo/UpdateDevConditionalAccess

[Azure AD] Developer - Conditional Access Update

Author: Court72

articles/active-directory/develop/developer-guide-conditional-access-authentication-context.md

@@ -6,28 +6,29 @@ services: active-directory
 ms.service: active-directory
 ms.subservice: develop
 ms.topic: conceptual
-ms.date: 05/18/2021
+ms.date: 11/15/2022
 
-ms.author: joflore
-author: MicrosoftGuyJFlo
+ms.author: kkrishna
+author: kalyankrishna1
 manager: CelesteDG
-ms.reviewer: kkrishna
+ms.reviewer: joflore
 
 ms.workload: identity
 
 ms.custom: aaddev
 ---
+
 # Developer guide to Conditional Access authentication context
 
-[Conditional Access](../conditional-access/overview.md) is the Zero Trust control plane that allows you to target policies for access to all your apps – old or new, private, or public, on-premises, or multi-cloud. With [Conditional Access authentication context](../conditional-access/concept-conditional-access-cloud-apps.md#authentication-context), you can apply different policies within those apps.
+[Conditional Access](../conditional-access/overview.md) is the Zero Trust control plane that allows you to target policies for access to all your apps – old or new, private, or public, on-premises, or multicloud. With [Conditional Access authentication context](../conditional-access/concept-conditional-access-cloud-apps.md#authentication-context), you can apply different policies within those apps.
 
 Conditional Access authentication context (auth context) allows you to apply granular policies to sensitive data and actions instead of just at the app level. You can refine your Zero Trust policies for least privileged access while minimizing user friction and keeping users more productive and your resources more secure. Today, it can be used by applications using [OpenId Connect](https://openid.net/specs/openid-connect-core-1_0.html) for authentication developed by your company to protect sensitive resources, like high-value transactions or viewing employee personal data.
 
 Use the Azure AD Conditional Access engine's new auth context feature to trigger a demand for step-up authentication from within your application and services. Developers now have the power to demand enhanced stronger authentication, selectively, like MFA from their end users from within their applications. This feature helps developers build smoother user experiences for most parts of their application, while access to more secure operations and data remains behind stronger authentication controls.
 
 ## Problem statement
 
-The IT administrators and regulators often struggle between balancing prompting their users with additional factors of authentication too frequently and achieving adequate security and policy adherence for applications and services where parts of them contain sensitive data and operations. It can be a choice between a strong policy that impacts users' productivity when they access most data and actions or a policy that is not strong enough for sensitive resources.
+The IT administrators and regulators often struggle between balancing prompting their users with additional factors of authentication too frequently and achieving adequate security and policy adherence for applications and services where parts of them contain sensitive data and operations. It can be a choice between a strong policy that impacts users' productivity when they access most data and actions or a policy that isn't strong enough for sensitive resources.
 
 So, what if apps were able to mix both, where they can function with a relatively lesser security and less frequent prompts for most users and operations and yet conditionally stepping up the security requirement when the users accessed more sensitive parts?
 
@@ -41,7 +42,7 @@ For example, while users may sign in to SharePoint using multi-factor authentica
 
 **Second**, [Conditional Access](../conditional-access/overview.md) requires Azure AD Premium P1 licensing. More information about licensing can be found on the [Azure AD pricing page](https://www.microsoft.com/security/business/identity-access-management/azure-ad-pricing).
 
-**Third**, today it is only available to applications that sign-in users. Applications that authenticate as themselves are not supported. Use the [Authentication flows and application scenarios guide](authentication-flows-app-scenarios.md) to learn about the supported authentication app types and flows in the Microsoft Identity Platform.
+**Third**, today it's only available to applications that sign-in users. Applications that authenticate as themselves aren't supported. Use the [Authentication flows and application scenarios guide](authentication-flows-app-scenarios.md) to learn about the supported authentication app types and flows in the Microsoft Identity Platform.
 
 ## Integration steps
 
@@ -71,7 +72,7 @@ Create or modify your Conditional Access policies to use the Conditional Access
 
 1. Identity actions in the code that can be made available to map against auth context Ids.
 1. Build a screen in the admin portal of the app (or an equivalent functionality) that IT admins can use to map sensitive actions against an available auth context ID.
-1. See the code sample, [Use the Conditional Access Auth Context to perform step-up authentication](https://github.com/Azure-Samples/ms-identity-ca-auth-context/blob/main/README.md) for an example on how it is done.
+1. See the code sample, [Use the Conditional Access Auth Context to perform step-up authentication](https://github.com/Azure-Samples/ms-identity-ca-auth-context/blob/main/README.md) for an example on how it's done.
 
 These steps are the changes that you need to carry in your code base. The steps broadly comprise of
 
@@ -93,7 +94,7 @@ These steps are the changes that you need to carry in your code base. The steps
 
       - Checks if the application's action being called requires step-up authentication. It does so by checking its database for a saved mapping for this method
       - If this action indeed requires an elevated auth context, it checks the **acrs** claim for an existing, matching Auth Context ID.
-      - If a matching Auth Context ID is not found, it raises a [claims challenge](claims-challenge.md#claims-challenge-header-format).
+      - If a matching Auth Context ID isn't found, it raises a [claims challenge](claims-challenge.md#claims-challenge-header-format).
 
       ```csharp
       public void CheckForRequiredAuthContext(string method)
@@ -207,15 +208,72 @@ These steps are the changes that you need to carry in your code base. The steps
 
 ## Caveats and recommendations
 
-Do not hard-code Auth Context values in your app. Apps should read and apply auth context [using MS Graph calls](/graph/api/resources/authenticationcontextclassreference). This practice is critical for [multi-tenant applications](howto-convert-app-to-be-multi-tenant.md). The Auth Context values will vary between Azure AD tenants will not available in Azure AD free edition. For more information on how an app should query, set, and use auth context in their code, see the code sample, [Use the Conditional Access auth context to perform step-up authentication](https://github.com/Azure-Samples/ms-identity-ca-auth-context/blob/main/README.md) as how an app should query, set and use auth context in their code.
+Don't hard-code Auth Context values in your app. Apps should read and apply auth context [using MS Graph calls](/graph/api/resources/authenticationcontextclassreference). This practice is critical for [multi-tenant applications](howto-convert-app-to-be-multi-tenant.md). The Auth Context values will vary between Azure AD tenants and won't be available in Azure AD free edition. For more information on how an app should query, set, and use auth context in their code, see the code sample, [Use the Conditional Access auth context to perform step-up authentication](https://github.com/Azure-Samples/ms-identity-ca-auth-context/blob/main/README.md) as how an app should query, set and use auth context in their code.
 
-Do not use auth context where the app itself is going to be a target of Conditional Access policies. The feature works best when parts of the application require the user to meet a higher bar of authentication.
+Don't use auth context where the app itself is going to be a target of Conditional Access policies. The feature works best when parts of the application require the user to meet a higher bar of authentication.
 
 ## Code samples
 
 - [Use the Conditional Access auth context to perform step-up authentication for high-privilege operations in a web app](https://github.com/Azure-Samples/ms-identity-dotnetcore-ca-auth-context-app/blob/main/README.md)
 - [Use the Conditional Access auth context to perform step-up authentication for high-privilege operations in a web API](https://github.com/Azure-Samples/ms-identity-ca-auth-context/blob/main/README.md)
 
+## Authentication context [ACRs] in Conditional Access expected behavior
+
+## Explicit auth context satisfaction in requests
+
+A client can explicitly ask for a token with an Auth Context (ACRS) through the claims in the request's body. If an ACRS was requested, Conditional Access will allow issuing the token with the requested ACRS if all challenges were completed.
+
+## Expected behavior when an auth context isn't protected by Conditional Access in the tenant
+
+Conditional Access may issue an ACRS in a token's claims when all Conditional Access policy assigned to the ACRS value has been satisfied. If no Conditional Access policy is assigned to an ACRS value the claim may still be issued, because all policy requirements have been satisfied.
+
+## Summary table for expected behavior when ACRS are explicitly requested
+
+ACRS requested | Policy applied | Control satisfied | ACRS added to claims |
+|--|--|--|--|--|
+|Yes | No | Yes | Yes |
+|Yes | Yes | No | No |
+|Yes | Yes | Yes | Yes |
+|Yes | No policies configured with ACRS | Yes | Yes |
+
+## Implicit auth context satisfaction by opportunistic evaluation
+
+A resource provider may opt in to the optional 'acrs' claim. Conditional Access will try to add ACRS to the token claims opportunistically in order to avoid round trips to acquire new tokens to Azure AD. In that evaluation, Conditional Access will check if the policies protecting Auth Context challenges are already satisfied and will add the ACRS to the token claims if so.
+
+> [!NOTE]
+> Each token type will need to be individually opted-in (ID token, Access token).
+>
+> If a resource provider doesn't opt in to the optional 'acrs' claim, the only way to get an ACRS in the token will be to explicitly ask for it in a token request. It will not get the benefits of the opportunistic evaluation, therefore every time that the required ACRS will be missing from the token claims, the resource provider will challenge the client to acquire a new token containing it in the claims.
+
+## Expected behavior with auth context and session controls for implicit ACRS opportunistic evaluation
+
+### Sign-in frequency by interval
+
+Conditional Access will consider "sign-in frequency by interval" as satisfied for opportunistic ACRS evaluation when all the present authentication factors auth instants are within the sign-in frequency interval. In case that the first factor auth instant is stale, or if the second factor (MFA) is present and its auth instant is stale, the sign-in frequency by interval won't be satisfied and the ACRS won't be issued in the token opportunistically.
+
+### Cloud App Security (CAS)
+
+Conditional Access will consider CAS session control as satisfied for opportunistic ACRS evaluation, when a CAS session was established during that request. For example, when a request comes in and any Conditional Access policy applied and enforced a CAS session, and in addition there's a Conditional Access policy that also requires a CAS session, since the CAS session will be enforced, that will satisfy the CAS session control for the opportunistic evaluation.
+
+## Expected behavior when a tenant contain Conditional Access policies protecting auth context
+
+The table below will show all corner cases where ACRS is added to the token's claims by opportunistic evaluation.
+
+**Policy A**: Require MFA from all users, excluding the user "Ariel", when asking for "c1" acrs.
+**Policy B**: Block all users, excluding user "Jay", when asking for "c2", or "c3" acrs.
+
+| Flow | ACRS requested | Policy applied | Control satisfied | ACRS added to claims |
+|--|--|--|--|--|
+| Ariel requests for an access token | "c1" | None | Yes for "c1". No for "c2" and "c3" | "c1" (requested) |
+| Ariel requests for an access token | "c2" | Policy B | Blocked by policy B | None  |
+| Ariel requests for an access token | None  | None | Yes for "c1". No for "c2" and "c3"  | "c1" (opportunistically added from policy A) |
+| Jay requests for an access token (without MFA) | "c1" | Policy A | No | None  |
+| Jay requests for an access token (with MFA) | "c1" | Policy A | Yes | "c1" (requested), "c2" (opportunistically added from policy B), "c3" (opportunistically added from policy B)|
+| Jay requests for an access token (without MFA) | "c2" | None  | Yes for "c2" and "c3". No for "c1" | "c2" (requested), "c3" (opportunistically added from policy B) |
+| Jay requests for an access token (with MFA)  | "c2" | None | Yes for "c1", "c2" and "c3"  | "c1" (best effort from A), "c2" (requested), "c3" (opportunistically added from policy B) |
+| Jay requests for an access token (with MFA)  | None | None | Yes for "c1", "c2" and "c3"  | "c1", "c2", "c3" all opportunistically added |
+| Jay requests for an access token (without MFA)  | None | None | Yes for "c2" and "c3". No for "c1"| "c2", "c3" all opportunistically added |
+
 ## Next steps
 
 - [Granular Conditional Access for sensitive data and actions (Blog)](https://techcommunity.microsoft.com/t5/azure-active-directory-identity/granular-conditional-access-for-sensitive-data-and-actions/ba-p/1751775)