Configure conditional access policy with Authentication context

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.
In this demo we use the Microsoft Entra Conditional Access engine's authentication context to trigger a demand for step-up authentication from within your application. For example when the sum of the items in the cart is higher than usual (50$) it requires the user to sign-in with a second factor authentication.

Switch to Microsoft Entra admin center
Switch to Graph API

Prerequisites

Before you start make sure you have configured the following:
  1. Create a tenant and add admin accounts
  2. Register a web application
  3. Create a user flow

To add an authentication context, sign in to the Microsoft Entra admin center and browse to Protection > Conditional Access. Then, select New authentication context.

Enter a name and description and select the Publish to apps check box. Then, select and ID. Values C1-C25 are available for use as Auth Context IDs in your tenant. Examples of auth context may be: C1 - Require strong authentication, C2 - Require trusted locations, and so on. In this exampe we selected C1. Select Save to add the authentication context.

In the next steps you create a Conditional Access policy to secure the application. The conditional access policy Target resources is the authentication context we created. From the meun, select Policies and then select New policy.

Give your policy a name and select the users in the Assignments. Then, go to Target resources and under what this policy applies to, choose Authentication context.

Select the check box for the authentication context that you created. In this example, we selected the Require strong authentication.

Under Access controls > Grant, select Grant access. Then select Require multifactor authentication. With this grant type, users must complete additional security requirements like email, phone call, or text message. Confirm your settings and set Enable policy to On. Select Create to create your policy.

For your application to receive information about whether users completed the MFA, the Conditional Access may issue an ACRS in a token's claims when all Conditional Access policy assigned to the ACRS value has been satisfied. In the next steps you configure the Woodgrove application to include the acrs claim in the access token. From the menu, select App registrations and select your application. In this example we select the Woodgrove Groceries application.

Under Manage, select Manifest. A web-based manifest editor opens, allowing you to edit the manifest. Add the following option claim to both ID token and access token. When finished, select Save.

In the Woodgrove example, users sign-in to the app. In the home page, they add some items to the shopping cart, until the total is more that 50$. When they select the checkout button, if they have not signed-in with MFA, users will be asked to do so. The Woodgrove application runs the following business logic:

  1. The code first checks if there is any risk. So, if the total is more that 50$ it's considered a risk.
  2. The code then evaluate the user's security token . If the acrs claim is equal to c1.
  3. If the If the acrs claim is not equal to c1, the Woodgrove app starts a new authentication request. The request contains the claims extra query string parameter. Tha value of the claims parameter is {"access_token":{"acrs":{"essential":true,"value":"c1"}}}.
Note, your application should always evaluate the access token acrs claim. So, if users remove the claims query string parameter, the acrs claim will not be stasfied (c1 value) and will not be able to complete the check out or any other action.

Dependencies

This script is self contained.

Create authentication context

To create authentication context, run the following Microsoft Graph.

POST https://graph.microsoft.com/v1.0/identity/conditionalAccess/authenticationContextClassReferences 
{
    "id": "c1",
    "displayName": "Require strong authentication",
    "description": "Require strong authentication for risky actions",
    "isAvailable": true
}

Create conditional access policy

Next create conditional access policy. The following example includes all users and excludes tenant global administrator.

POST https://graph.microsoft.com/v1.0/identity/conditionalAccess/policies 
{
    "templateId": null,
    "displayName": "Woodgrove step up authentication",
    "state": "enabled",
    "sessionControls": null,
    "conditions": {
        "userRiskLevels": [],
        "signInRiskLevels": [],
        "clientAppTypes": [
            "all"
        ],
        "platforms": null,
        "locations": null,
        "times": null,
        "deviceStates": null,
        "devices": null,
        "clientApplications": null,
        "applications": {
            "includeApplications": [],
            "excludeApplications": [],
            "includeUserActions": [],
            "includeAuthenticationContextClassReferences": [
                "c1"
            ],
            "applicationFilter": null
        },
        "users": {
            "includeUsers": [
                "All"
            ],
            "excludeUsers": [],
            "includeGroups": [],
            "excludeGroups": [],
            "includeRoles": [],
            "excludeRoles": [
                "62e90394-69f5-4237-9190-012177145e10"
            ],
            "includeGuestsOrExternalUsers": null,
            "excludeGuestsOrExternalUsers": null
        }
    },
    "grantControls": {
        "operator": "OR",
        "builtInControls": [
            "mfa"
        ],
        "customAuthenticationFactors": [],
        "termsOfUse": [],
        "authenticationStrength": null
    }
}

Configure the app to include the ACRS claim in the security tokens

For your application to receive information about whether users completed the MFA, the Conditional Access may issue an ACRS in a token's claims when all Conditional Access policy assigned to the ACRS value has been satisfied. In the next steps you configure the Woodgrove application to include the acrs claim in the access token. To emit the ACRS claim in security tokens, update the app. In the following JSON, replace the {App-ID} with your application ID (not object ID).

PATCH https://graph.microsoft.com/v1.0/applications(appId='{App-ID}') 
{
    "groupMembershipClaims": "SecurityGroup",
    "optionalClaims": {
        "idToken": [
            {
                "name": "groups",
                "source": null,
                "essential": false,
                "additionalProperties": []
            },
            {
                "name": "acrs",
                "source": null,
                "essential": false,
                "additionalProperties": []
            }
        ],
        "accessToken": [
            {
                "name": "groups",
                "source": null,
                "essential": false,
                "additionalProperties": []
            },
            {
                "name": "acrs",
                "source": null,
                "essential": false,
                "additionalProperties": []
            }
        ],
        "saml2Token": [
            {
                "name": "groups",
                "source": null,
                "essential": false,
                "additionalProperties": []
            }
        ]
    }
}