Conditional access Auth Context

Example below shows how to use authentication factory when asking for tokens for resources protected by Conditional access with Authentication context.

Note: For more information about this feature, and for guidance how to configure and developp backend application to support step-up authentication, see Microsoft Documentation

Authentication factory for Interactive, DeviceCode and WAM public client flows suports asking for step-up authentication when factoray is created with parameter WithClaimsRequestSupport

Factory created with this paraneter announces its step-up capability, and when asking for tokens for resources that also advertise step-up authentication capability in their applicatiuon manifest, token receives xms_cc claim.

When resource server requires step-up authentication, it returns Unauthorized error along with WWW-Authenticate header, directing client to ask for new token with specific claims representing authentication context required by resource.

Factory is then capable to ask for such claims; claims are passed to factory in parameter WwwAuthenticateParameters. Request for new token with those claims trigger Conditional Access policy associated with requested authentication context that makes sure that all requirements are satisfied. Token with acrs claim containing requested authentication context is issued only when all requirements of conditional access policy are satisfied.

Client can then can use the token provided by step-up authentication again for authorization of request for the resource that previously failed with Unauthorized result - request is expected to succeed because token contains claim with authorization context requested by resource.

# Create factory for public client that has permission to ask tokens for backend API
# Backend API needs to support step-up authentication

new-aadAuthenticationFactory `
    -TenantId mydomain.com `
    -ClientId 9d9c21ed-6c4d-10fb-a283-0af5f902da3c `
    -DefaultScopes 'api://myAppIdUri/.default' `
    -AuthMode Interactive `
    -WithClaimsRequestSupport `
    -name acrCapableClient
# Notice WithClaimsRequestSupport parameter that makes the factory to announce step-up authentication capability

# Retrieve access token to call REST API
$header = Get-AadToken -AsHashTable
# Token is expected to contain xms_cc claim that signalizes support for step-up authentication - check this out
$header | Test-AadToken -PayloadOnly

# Call REST API
# Note: we use ToDoList app from MS samples as resource in this sample
$task = @{
    id = 1
    title = 'Sample task'
    owner = 'John Doe'
}

try
{
    # This call may fail because auth context claim missing in the token
    Invoke-RestMethod `
        -Method Post `
        -Uri 'https://localhost:44351/api/todolist' `
        -Headers $header `
        -Body ($task | ConvertTo-Json) `
        -ContentType 'application/json'
}
catch {
    if($_.Exception.StatusCode -eq 'Unauthorized')
    {
        $claimsChallenge = [Microsoft.Identity.Client.WwwAuthenticateParameters]::CreateFromAuthenticationHeaders($_.exception.Response.Headers)
    }
}

# If resource signalized need for step-up auth, we have $claimsChallenge
if($null -ne $claimsChallenge)
{
    # Ask for token containing auth context requested by server
    $header = Get-AadToken `
        -WwwAuthenticateParameters $claimsChallenge[0] `
        -AsHashTable
    # Upon successful return, token is expected to contain acrs claim
    # containing id of authentication context(s) requested by resource
    # Let's check this out
    $header | Test-AadToken -PayloadOnly

    # Use the token to call server again - now the request shall succeed
        Invoke-RestMethod `
        -Method Post `
        -Uri 'https://localhost:44351/api/todolist' `
        -Headers $header `
        -Body ($task | ConvertTo-Json) `
        -ContentType 'application/json'

}
else
{
    Write-Error 'Could not call the API'
}

Note: ToDoList app REST API we used in the sample above is MS sample app that supports step-up authentication with authentication context and is published in MS GitHub samples repo