Client capabilities

• Adding client capabilities to your application object is a way to tell the STS what the client is capable of. So, STS can turn on certain features. For example adding client capability CP1 will mean that client is capable of handling claims challenge from the resource. Thus, STS can emit claims in access token that may lead to claims challenge from resource.
• These capabilities are set at the application object using client_capabilities parameter which is a list of client_capability strings.

app = msal.PublicClientApplication(client_id="client_id", authority="your_authority", client_capabilities = ["CP1"])

• Once these are set at the application level they will be sent to all the calls to STS authorize and token endpoints.
• When such a capability(CP1) is set on the application object the client application should make sure that a claims challenge from the resource is handled in the application.
• Claims challenge is a directive in the www-authenticate header that the resource will respond with when an access token is not authorized, and a new access token is required.
• An example claims challenge from resource should look like this:

HTTP 401; Unauthorized 
www-authenticate=Bearer realm="", 
authorization_uri="https://login.microsoftonline.com/common/oauth2/authorize", 
error="insufficient_claims", 
claims="returned_claims"

It consists of HTTP Status code which must be 401 and www-authenticate header which contains the fields mentioned above. More details in about it in this doc. Clients need to extract the claims and then pass it to acquire_token_by_* method.

• If claims parameter returned from the resource is base64-encoded, it needs to be decoded before calling MSAL. MSAL acquire_token methods accept claims as a json string.

claims = "claims returned from resource"
# if claims are encoded, decode them
# decoded_claims = str(base64.b64decode(claims), "utf-8")
# Auth endpoint call for interactive login (you can use auth url helper - BuildAuthUri(..., claims_challenge=claims)
result = app.acquire_token_by_authorization_code(..., claims_challenge=claims)

• This new access token can now be used in the request to resource.