[Feature Request] Client capabilities support

[henrik-me]

Smart Session Management (SSM) sometimes referred to as the long lived tokens (LLT) scenario require MSAL to allow developers to resolve challenges (formatted as claims request parameters) to be resolved silently rather than interactively. Current releases of MSAL assume that interaction is required whenever a claims request parameter is included in the request.

This change in behavior requires the client to indicate that it's aware of a new calling pattern relative to the use of MSAL.

API/Design details:
https://identitydivision.visualstudio.com/DevEx/_git/AuthLibrariesApiReview?path=%2FClientCapabilities%2Foverview.md&version=GBdev
Is your feature request related to a problem? Please describe.

Related internal work item:
https://identitydivision.visualstudio.com/Engineering/_workitems/edit/824806

[henrik-me]

CC: @jmprieur

[bgavrilMS]

I investigated this based on the specs and impl of MSAL for Android. To support just client capabilities we would need to:

Support for Client Capabilities

• Public API at application level .WithClientCapabilities(new[] {"cp1", "cp2"})
• Logic to transform claims string to JSON
• Logic to merge client capabilities with other claims passed in by .WithClaims()
• Logic to bypass token cache in AcquireTokenSilent, OBO and Client Creds if Claims are requested

To support a fully typed API for claims

• Public API similar to MSAL Android's https://github.com/AzureAD/microsoft-authentication-library-for-android/blob/dev/docs/claimsrequest.md (separate feature)
• Support for creating Claims objects from an WWWAuthenicateHeader ?
• Expose Claims in Account (separate feature)

Open questions / bugs

• Public API - I'd prefer to have .WithClientCapabilities(new[] {"cp1", "cp2"}) (i.e. string array instead of 1 comma separated string)
• We send claims to the /token (as query param) and /authorize endpoint.
• Bug: we don't send claims in Android broker, only iOS broker. Claims should be sent on the SilentBroker request as well.
• Bug: we serve tokens from the cache even if claims are requested. ADAL skips the cache in this case. Msal Android treats this as "ForceRefresh=true". What is the expected behavior here? - normal claims - skip cache. client capabilitiers - do not skip cache?
• Not sure how to test that the E2E is working. Will reach out to find out.

[bgavrilMS]

~1 week of work (with normal disruption schedule)

[bgavrilMS]

Further clarifications from Shane

1. Please confirm that we should be sending claims to the /token endpoint (as forms param) as well as to the /authorize endpoint
2. [shane] Confirmed. This isn't per the OIDC spec. I would classify as an OIDC extenson that Microsoft Identity Platform is using to allow resource challenges that can be resolved without interaction to be resolved. The feature that introduced this was Secure Session Management (SSM AKA Long Lived tokens [LLT].
3. For AcquireToken* methods that can fetch tokens from the cache (AcquireTokenSilent, AcquireTokenForApplication, OBO), having claims is equivalent to setting ForceRefresh=true, i.e. bypass the cache. Should MSALs really bypass the cache when client capabilities are set (i.e. xms_cc specific claim is set)?
   a. [shane] client capabilities do not bypass cache. They are set once one the public client application. Only bypass the cache when you receive claims as part of the silent request.
   b. Since B2C does not support client capabilities, you do not apply above logic to B2C. Are we saying that B2C will never support client capabilities ?
   c. [shane]I can't speak to the future. As B2C and AAD converge I would expect B2C or whatever it is called then to support this.
4. After sending the claims, MSALs are not required to do anything else?
5. [shane] Confirmed.
6. Is there a way to test this End to End? i.e. some client capability that we can set and observe the difference in the token response
7. [shane] Good question. This was tested on our behalf by the SSM team, i'll try and find out how we can use their tests.

[bgavrilMS]

This is done with the exception of #1651 - I do not know the broker protocol to fix this properly.

[trwalke]

released in 4.9.0
https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/releases/tag/4.9.0