Add an api which will enable developers to cache additional values in the token response in the Access token

[trwalke]

Summary

Certain scenarios in Entra Id will result in additional data being returned to MSAL which is not always present in the authentication response. These values are not known by MSAL and are collected and stored in the AuthenticationResult.AdditionalResponseParameters. The idea here is to enable customers to specify which values in the AdditionalResponseParameters can be cached in the MSAL access token so that they can be re-acquired when accessing the cached token.

Motivation and goals

With the current push to migrate customers to MISE and the desire to make MSAL more extendable, we are considering enabling MISE as well as other auth SDK libraries to inject functionality into MSAL. Certain features, such as CDT, which is the feature driving this proposal, require additional data to be captured by MSAL and stored in the cache for later use. Rather than hard coding these additional cache values which will only be usable in the extensibility features added to MSAL, this feature will work along side the extended features in order to provide a more seamless E2E experience.

The goals here are as follows:

• Enable developers to specify additional parameters to be cached using a new api. WithAdditionalCacheParameters(IEnumerable<string> parameters)
• Compare the provided additional parameters with the additional parameters returned by ESTS and cache the ones that match in the MSALAccessTokenCacheItem
• Modify the AuthenticationResult.AdditionalResponseParameters parameter to reflect what is cached so that developers can verify which additional parameters are stored and acquire them as needed. if no values are specified, the AdditionalResponseParameters will return all of the additional parameters in the response and none will be cached.
• Limit this functionality to confidential clients

In scope

All confidential client scenarios will be able to take advantage of this new feature

Out of scope

Public client scenarios

Risks / unknowns

• Developers might want to cache values that are already present in the msal access token cache item
• it is not clear if this should be added to the access token cache key. At the moment, I see no reason to add it but this might change in the future. Because of this, acquiring a new token without re-specifying the parameters will overwite the cached values with null
• This feature will slightly modify the behavior of AuthenticationResult.AdditionalResponseParameters when enabled but it should not affect many people since this parameter is most likely not used very often.

Examples

                //Acquire token from endpoint
                var result = await app.AcquireTokenForClient(TestConstants.s_scope.ToArray())
                    .WithAdditionalCacheParameters(new List<string> { "additional_param1", "additional_param2", "additional_param3", "additional_param4" })
                    .ExecuteAsync()
                    .ConfigureAwait(false);

               //result.AdditionalResponseParameters will contain specified values
               //result.AdditionalResponseParameters[1] = key("additional_param1"), value("value from ESTS")

               //Acquire token from cache
                var result = await app.AcquireTokenForClient(TestConstants.s_scope.ToArray())
                    .WithAdditionalCacheParameters(new List<string> { "additional_param1", "additional_param2", "additional_param3", "additional_param4" })
                    .ExecuteAsync()
                    .ConfigureAwait(false);

               //result.AdditionalResponseParameters will still contain specified values instead of the usual null

Acceptance tests:

Test:

• Scenario: The user calls WithAdditionalCacheParameters("additional_param1", "additional_param2", "additional_param3", "additional_param4") and these 4 parameters are retuned in the authentication response
• Expected Result: All of the parameters should be cached in the access token and provided via AuthenticationResult.AdditionalResponseParameters. The values in AuthenticationResult.AdditionalResponseParameters should match what was provided in the authentication response.

Test:

• Scenario: The user calls WithAdditionalCacheParameters("additional_param1", "additional_param2", "additional_param3", "additional_param4") and these 4 parameters were cached in a previous access token.
• Expected Result: All of the parameters should be returned from the previously cached access token and provided via AuthenticationResult.AdditionalResponseParameters. The values in AuthenticationResult.AdditionalResponseParameters should match what was in the cached access token.

Test:

• Scenario: The user attempts to retrieve a token from the cache and "additional_param1", "additional_param2", "additional_param3", "additional_param4" were cached in a previous access token. The user does not use WithAdditionalCacheParameters()
• Expected Result: All of the parameters should be returned from the previously cached access token and provided via AuthenticationResult.AdditionalResponseParameters. The values in AuthenticationResult.AdditionalResponseParameters should match what was in the cached access token.

Test:

• Scenario: The user calls WithAdditionalCacheParameters("additional_param1", "additional_param4") and "additional_param1", "additional_param2", "additional_param3", "additional_param4" are retuned in the authentication response.
• Expected Result: Only "additional_param1", "additional_param4" should be cached in the access token and provided via AuthenticationResult.AdditionalResponseParameters. The values in AuthenticationResult.AdditionalResponseParameters should match what was provided in the authentication response.

Test:

• Scenario: The user calls WithAdditionalCacheParameters("additional_param5") and "additional_param1", "additional_param2", "additional_param3", "additional_param4" are retuned in the authentication response.
• Expected Result: No additional parameters should be cached in the access token and AuthenticationResult.AdditionalResponseParameters should contain all of the parameters returned in the authentication response. The values in AuthenticationResult.AdditionalResponseParameters should match what was provided in the authentication response.

[bgavrilMS]

LGTM. In the interest of time, I recommend keeping this API at the request level only. It's also consistent with the other extensibility points. We can always add the app level API later.

[rayluo]

Overall LGTM. What is the difference between test case 2 and case 3?