Support client capabilities and claims

[chlowell]

Closes #263 by adding a WithClientCapabilities option for client constructors and a WithClaims option for token acquisition methods. Usage looks like this:

client, err := New("id", cred, WithClientCapabilities([]string{"CP1"}))
token, err := client.AcquireTokenByCredential(ctx, scope, WithClaims("some JSON"))

(confidential and public clients have the same options)

I believe I've covered all the bases here (see the e2e tests) but please look closely; many code paths are impacted. Let me highlight a few subtleties:

• capabilities must interpolate into a valid JSON array but otherwise we have no opinion on their validity
• claims must be valid JSON. Callers are responsible for decoding challenges. This is documented and the error returned for invalid JSON calls this out.
• AcquireTokenSilent(..., WithClaims("...")) won't return a cached access token. This means it always fails for confidential clients. It can succeed for public clients that have a refresh token for the account. Similarly, AcquireTokenOnBehalfOf can succeed silently for confidential clients.

[sonarcloud]

Kudos, SonarCloud Quality Gate passed!   

0 Bugs
0 Vulnerabilities
0 Security Hotspots
8 Code Smells

No Coverage information
0.5% Duplication

[rayluo]

Overall LGTM. Leaving a couple minor comments below.

[rayluo]

Outside of the scope of this PR, but a FYI: MSALs are allowing confidential clients to use password flow (internal work item).

[bgavrilMS]

That is a great unit test, very easy to read and understand.

[richardpark-msft]

Is it WithClaims() that adds this in? If so, maybe we shouldn't mention it as one of the Options since it will lead immediately into an error.

[chlowell]

You raise a good point. It will one day be possible for this method to succeed when given claims; we can add the option then. The value of taking the option today is in maintaining the calling pattern used in all other cases (see e.g. azidentity):

1. call AcquireTokenSilent (check the cache)
2. if that returned an error, call AcquireTokenBy* (request a new token)

Applications expect errors from AcquireTokenSilent because it commonly returns them, which is okay because that's just a cache miss. Having an option that guarantees it will return an error therefore doesn't make users write more, different, or tricky code. On the other hand, if this method doesn't take claims, the probably miniscule population of users who use this feature will have to write conditional code around it, then rewrite that code when this method does take claims. But sure, it's weird to have an anti-useful option.

Edit: whoops, I buried the lede there: having this option steers users away from an authorization failure loop. When a user presents an access token to some RP and receives a claims challenge in response, that means the token isn't valid, even if it hasn't yet expired; the user must acquire a new token having the requested claims. The MSAL client doesn't know this because it doesn't observe requests to the RP. So, a user who receives a claims challenge and proceeds to call AcquireTokenSilent will probably get an invalid token. This is what I was getting at above when I wrote that not having this option compels users to write conditional code: they would have to know not to call AcquireTokenSilent when handling a claims challenge.

[richardpark-msft]

I think I get what you mean - it's definitely not a straightforward case and it sounds like it's critical to consider that it's running as part of an overall pattern of calls, not just on its own (if I'm following your logic).

Resolving for now, explanation makes sense to me.