Creating a Conditional access policy with Authentication strength control programmatically

I’ve seen a few questions lately on how to programmatically create a Conditional Access policy with Authentication strength  as one of the “grant” controls. For some reason, the documentation doesn’t directly address this scenario, and in turn people seem to get confused, when in fact, it’s rather simple. So in this article, let’s briefly talk about how to create such a policy, and explore some examples.

To start, we need to understand the schema used by the Conditional access policy resource, or in other words the properties we need to use. Apart from the displayName and state, when creating a new Conditional access policy we need to specify the set of Conditions, i.e. which objects and scenarios the policy will apply to. And we also need to define the actions for the policy, that is the set of grantControls which define whether access will be granted or not, as well as various requirements that need to be met. The Authentication strength control is one such example.

For the purposes of this article, the important thing to understand is how Authentication strength is represented on the API side of things. If you are looking directly at the output generated by the LIST /policies/conditionalAccessPolicies method, it is not immediately clear how the relevant cogs turn. In fact it might be misleading. Here’s an example:

"grantControls": {
    "operator": "OR",
    "builtInControls": [],
    "customAuthenticationFactors": [],
    "termsOfUse": [],
    "authenticationStrength@odata.context": "https://graph.microsoft.com/v1.0/$metadata#policies/conditionalAccessPolicies('72976d8e-b0d4-40c1-a649-cea4eb19f4fc')/grantControls/authenticationStrength/$entity",
    "authenticationStrength": {
        "id": "00000000-0000-0000-0000-000000000003",
        "createdDateTime": "2021-12-01T08:00:00Z",
        "modifiedDateTime": "2021-12-01T08:00:00Z",
        "displayName": "Passwordless MFA",
        "description": "Passwordless methods that satisfy strong authentication, such as Passwordless sign-in with the Microsoft Authenticator",
        "policyType": "builtIn",
        "requirementsSatisfied": "mfa",
        "allowedCombinations": [
            "windowsHelloForBusiness",
            "fido2",
            "x509CertificateMultiFactor",
            "deviceBasedPush"
        ],
        "combinationConfigurations@odata.context": "https://graph.microsoft.com/v1.0/$metadata#policies/conditionalAccessPolicies('72976d8e-b0d4-40c1-a649-cea4eb19f4fc')/grantControls/authenticationStrength/combinationConfigurations",
        "combinationConfigurations": []
    }
}

So we have the grantControls resource, which we already know encompasses any Authentication strength clauses. If you take a look at the documentation on the resource though, you’ll notice that the properties table doesn’t have an entry with an authenticationStrength property. Instead, we see it under relationship, pointing to an authenticationStrengthPolicy resource. The properties listed for said resource do match what we see in the JSON above.

Here’s the kicker. If you try and reuse the (part of) JSON above for creating a new Conditional access policy, the backend will respond with a BadRequest error, with a message along these lines: “1007: Incoming ConditionalAccessPolicy object is null or does not match the schema of ConditionalAccessPolicy type“. It doesn’t directly tell you that the grantControls and more specifically the authenticationStrength node is the issue, but a little trial and error testing will verify that.

So, we cannot just reuse these bits across policies. How do we then create a new Conditional access policy that leverages an authentication strength programmatically? The answer is surprisingly simple – we just need to point to the id of the corresponding Authentication strength policy. None of the other properties are needed! Here’s an example payload:

{
  "displayName": "Policy with Auth strength",
  "state": "enabledForReportingButNotEnforced",
  "conditions": {
    "clientAppTypes": [
      "all"
    ],
    "applications": {
      "includeApplications": [
        "All"
      ]
    },
    "users": {
      "includeUsers": [
        "All"
      ]
    }
  },
  "grantControls": {
    "operator": "OR",
    "authenticationStrength": {
      "id": "00000000-0000-0000-0000-000000000002"
    }
  }
}

Cool, but how do we get that GUID? Well, it’s the id of the corresponding Authentication strength policy object, which we can fetch via the LIST /policies/authenticationStrengthPolicies method. Both built-in and custom-created Authentication strengths do have a matching policy. Thus, if you plan to create a Conditional access policy from scratch, fetch the corresponding Authentication strength policy id first. If you are creating a copy of existing CA policy, strip everything apart from the id value on the authenticationStrength node. As simple as that.

It’s important to understand that all of the built-in Authentication strength policies have the same id across all tenants. This in turn makes it much easier to use them, as you don’t even have to look their ids up. For example, you can use the value of 00000000-0000-0000-0000-000000000002 to reference the built-in “Multifactor authentication” policy, regardless of which tenant you are creating the policy in and how many Authentication strength policies exist within it. Oh, and you can use the Get-MgPolicyAuthenticationStrengthPolicy cmdlet to fetch the policies via the Graph SDK for PowerShell:

To finish of the article, here are full blown examples on how you can create a new Conditional access policy that includes an Authentication strength control. To create such a policy via the Graph API, you have to issue a POST request against the /policies/conditionalAccessPolicies endpoint, with the following JSON as payload:

POST https://graph.microsoft.com/v1.0/policies/conditionalAccessPolicies

{
  "displayName": "MFA for all users",
  "state": "enabledForReportingButNotEnforced",
  "conditions": {
    "applications": {
      "includeApplications": [
        "All"
      ]
    },
    "users": {
      "includeUsers": [
        "All"
      ]
    }
  },
  "grantControls": {
    "operator": "OR",
    "authenticationStrength": {
      "id": "00000000-0000-0000-0000-000000000002"
    }
  }
}

To create a similar policy via the Graph SDK for PowerShell, use the New-MgIdentityConditionalAccessPolicy cmdlet:

$json =
@{
    "conditions" = @{
        "applications" = @{
            "includeApplications" = @("All")
            }
        "clientAppTypes" = @("all")
        "users" = @{
            "includeUsers" = @("All")
        }
    }
    "state" = "enabledForReportingButNotEnforced"
    "displayName" = "Graph SDK example"
    "grantControls" = @{
        "authenticationStrength" = @{
            "id" = "00000000-0000-0000-0000-000000000002"
        }
        "operator" = "OR"
    }
}

New-MgIdentityConditionalAccessPolicy -BodyParameter ($json | ConvertTo-Json -Depth 10)

Both examples use the built-in “Multifactor authentication” Authentication strength policy, with id of 00000000-0000-0000-0000-000000000002. You can replace it with the id of any of the other built-in policies, or any custom ones you have created in the tenant. Remember, it is a reference to an exiting Authentication strength policy, so you do not need to provide any additional bits of its configuration. This of course means that the referred Authentication strength policy must already exist. If you are planning to use a custom combination of authentication methods designed to meet specific needs, make sure to first create the Authentication strength policy object!