Adjust WithExtraQueryParameters APIs and cache key behavior (#5536)

* Add new WithExtraQueryParameters API and behavior affects cache keys, deprecate existing WithExtraQueryParameters APIs

* Fix tests

* Fix test

* More test fixes

* Test fix

* Update src/client/Microsoft.Identity.Client/ApiConfig/BaseAbstractAcquireTokenParameterBuilder.cs

Co-authored-by: Bogdan Gavril <[email protected]>

* PR feedback

* Update tests/Microsoft.Identity.Test.Unit/PublicApiTests/ExtraQueryParametersTests.cs

Co-authored-by: Copilot <[email protected]>

* PR feedback

* PR feedback

---------

Co-authored-by: Bogdan Gavril <[email protected]>
Co-authored-by: Copilot <[email protected]>

Author: 3 people

src/client/Microsoft.Identity.Client/ApiConfig/AbstractAcquireTokenParameterBuilder.cs

@@ -67,6 +67,7 @@ public T WithClaims(string claims)
         /// The string needs to be properly URL-encoded and ready to send as a string of segments of the form <c>key=value</c> separated by an ampersand character.
         /// </param>
         /// <returns>The builder to chain .With methods.</returns>
+        [Obsolete("This method is deprecated. Please use the WithExtraQueryParameters(IDictionary<string, (string value, bool includeInCacheKey)>) method instead, which provides control over which parameters are included in the cache key.", false)]
         public T WithExtraQueryParameters(string extraQueryParameters)
         {
             if (!string.IsNullOrWhiteSpace(extraQueryParameters))

src/client/Microsoft.Identity.Client/ApiConfig/BaseAbstractAcquireTokenParameterBuilder.cs

@@ -89,10 +89,49 @@ public T WithCorrelationId(Guid correlationId)
         /// as a string of segments of the form <c>key=value</c> separated by an ampersand character.
         /// The parameter can be null.</param>
         /// <returns>The builder to chain the .With methods.</returns>
+        [Obsolete("This method is deprecated. Use the WithExtraQueryParameters(IDictionary<string, (string value, bool includeInCacheKey)>) method instead, which provides control over which parameters are included in the cache key.", false)]
         public T WithExtraQueryParameters(Dictionary<string, string> extraQueryParameters)
         {
-            CommonParameters.ExtraQueryParameters = extraQueryParameters ??
-                new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase);
+            return WithExtraQueryParameters(CoreHelpers.ConvertToTupleParameters(extraQueryParameters));
+        }
+
+        /// <summary>
+        /// Sets Extra Query Parameters for the query string in the HTTP authentication request with control over which parameters are included in the cache key
+        /// </summary>
+        /// <param name="extraQueryParameters">This parameter will be appended as is to the query string in the HTTP authentication request to the authority, and merged with those added to the application-level WithExtraQueryParameters API.
+        /// Each dictionary entry maps a parameter name to a tuple containing:
+        /// - Value: The parameter value that will be appended to the query string
+        /// - IncludeInCacheKey: Whether this parameter should be included when computing the token's cache key.
+        /// To help ensure the correct token is returned from the cache, IncludeInCacheKey should be true if the parameter affects token content or validity (e.g., resource-specific claims or parameters).
+        /// The parameter can be null.</param>
+        /// <returns>The builder to chain .With methods.</returns>
+        public T WithExtraQueryParameters(IDictionary<string, (string Value, bool IncludeInCacheKey)> extraQueryParameters)
+        {
+            if (extraQueryParameters == null)
+            {
+                CommonParameters.ExtraQueryParameters = null;
+                return this as T;
+            }
+
+            CommonParameters.ExtraQueryParameters = CommonParameters.ExtraQueryParameters ?? new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase);
+
+            // Add each parameter to ExtraQueryParameters and, if requested, to CacheKeyComponents
+            foreach (var kvp in extraQueryParameters)
+            {
+                CommonParameters.ExtraQueryParameters[kvp.Key] = kvp.Value.Value;
+
+                if (kvp.Value.IncludeInCacheKey)
+                {
+                    CommonParameters.CacheKeyComponents = CommonParameters.CacheKeyComponents ?? new SortedList<string, Func<CancellationToken, Task<string>>>();
+
+                    // Capture the value in a local to avoid closure issues
+                    string valueToCache = kvp.Value.Value;
+
+                    // Add to cache key components - uses a func that returns the value as a task
+                    CommonParameters.CacheKeyComponents[kvp.Key] = (CancellationToken _) => Task.FromResult(valueToCache);
+                }
+            }
+
             return this as T;
         }
 

src/client/Microsoft.Identity.Client/AppConfig/AbstractApplicationBuilder.cs

@@ -292,10 +292,10 @@ protected T WithOptions(ApplicationOptions applicationOptions)
         /// as a string of segments of the form <c>key=value</c> separated by an ampersand character.
         /// The parameter can be null.</param>
         /// <returns>The builder to chain the .With methods</returns>
+        [Obsolete("This method is deprecated. Please use the WithExtraQueryParameters(IDictionary<string, (string value, bool includeInCacheKey)>) method instead, which provides control over which parameters are included in the cache key.", false)]
         public T WithExtraQueryParameters(IDictionary<string, string> extraQueryParameters)
         {
-            Config.ExtraQueryParameters = extraQueryParameters;
-            return this as T;
+            return WithExtraQueryParameters(CoreHelpers.ConvertToTupleParameters(extraQueryParameters));
         }
 
         /// <summary>
@@ -305,6 +305,7 @@ public T WithExtraQueryParameters(IDictionary<string, string> extraQueryParamete
         /// The string needs to be properly URL-encoded and ready to send as a string of segments of the form <c>key=value</c> separated by an ampersand character.
         /// </param>
         /// <returns></returns>
+        [Obsolete("This method is deprecated. Please use the WithExtraQueryParameters(IDictionary<string, (string value, bool includeInCacheKey)>) method instead, which provides control over which parameters are included in the cache key.", false)]
         public T WithExtraQueryParameters(string extraQueryParameters)
         {
             if (!string.IsNullOrWhiteSpace(extraQueryParameters))
@@ -314,6 +315,44 @@ public T WithExtraQueryParameters(string extraQueryParameters)
             return this as T;
         }
 
+        /// <summary>
+        /// Sets Extra Query Parameters for the query string in the HTTP authentication request with control over which parameters are included in the cache key
+        /// </summary>
+        /// <param name="extraQueryParameters">This parameter will be appended as is to the query string in the HTTP authentication request to the authority, and merged with those added to the request-level WithExtraQueryParameters API.
+        /// Each dictionary entry maps a parameter name to a tuple containing:
+        /// - Value: The parameter value that will be appended to the query string
+        /// - IncludeInCacheKey: Whether this parameter should be included when computing the token's cache key.
+        /// To help ensure the correct token is returned from the cache, IncludeInCacheKey should be true if the parameter affects token content or validity (e.g., resource-specific claims or parameters).
+        /// The parameter can be null.</param>
+        /// <returns>The builder to chain .With methods.</returns>
+        public T WithExtraQueryParameters(IDictionary<string, (string Value, bool IncludeInCacheKey)> extraQueryParameters)
+        {
+            if (extraQueryParameters == null)
+            {
+                Config.ExtraQueryParameters = null;
+                return this as T;
+            }
+
+            // Add each parameter to ExtraQueryParameters and, if requested, to CacheKeyComponents
+            foreach (var kvp in extraQueryParameters)
+            {
+                Config.ExtraQueryParameters = Config.ExtraQueryParameters ?? new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase);
+                
+                Config.ExtraQueryParameters[kvp.Key] = kvp.Value.Value;
+
+                if (kvp.Value.IncludeInCacheKey)
+                {
+                    // Initialize the cache key components if needed
+                    Config.CacheKeyComponents = Config.CacheKeyComponents ?? new SortedList<string, string>();
+
+                    // Add to cache key components - uses a func that returns the value as a task
+                    Config.CacheKeyComponents[kvp.Key] = kvp.Value.Value;
+                }
+            }
+
+            return this as T;
+        }
+
         /// <summary>
         /// Microsoft Identity specific OIDC extension that allows resource challenges to be resolved without interaction. 
         /// Allows configuration of one or more client capabilities, e.g. "llt"

src/client/Microsoft.Identity.Client/Microsoft.Identity.Client.csproj

@@ -154,6 +154,7 @@
 
   <ItemGroup>
     <PackageReference Include="Microsoft.IdentityModel.Abstractions" />
+    <PackageReference Include="System.ValueTuple" />
   </ItemGroup>
 
   <ItemGroup Label="For public api analyzer support">

src/client/Microsoft.Identity.Client/PublicApi/net462/PublicAPI.Unshipped.txt

@@ -1,3 +1,5 @@
+Microsoft.Identity.Client.AbstractApplicationBuilder<T>.WithExtraQueryParameters(System.Collections.Generic.IDictionary<string, (string Value, bool IncludeInCacheKey)> extraQueryParameters) -> T
+Microsoft.Identity.Client.BaseAbstractAcquireTokenParameterBuilder<T>.WithExtraQueryParameters(System.Collections.Generic.IDictionary<string, (string Value, bool IncludeInCacheKey)> extraQueryParameters) -> T
 const Microsoft.Identity.Client.MsalError.CannotSwitchBetweenImdsVersionsForPreview = "cannot_switch_between_imds_versions_for_preview" -> string
 const Microsoft.Identity.Client.MsalError.InvalidCertificate = "invalid_certificate" -> string
 const Microsoft.Identity.Client.MsalError.MtlsNotSupportedForManagedIdentity = "mtls_not_supported_for_managed_identity" -> string
@@ -7,4 +9,4 @@ Microsoft.Identity.Client.IMsalMtlsHttpClientFactory.GetHttpClient(System.Securi
 Microsoft.Identity.Client.ManagedIdentityApplication.GetManagedIdentitySourceAsync() -> System.Threading.Tasks.Task<Microsoft.Identity.Client.ManagedIdentity.ManagedIdentitySource>
 Microsoft.Identity.Client.ManagedIdentity.ManagedIdentitySource.ImdsV2 = 8 -> Microsoft.Identity.Client.ManagedIdentity.ManagedIdentitySource
 Microsoft.Identity.Client.ManagedIdentityApplicationBuilder.WithExtraQueryParameters(System.Collections.Generic.IDictionary<string, string> extraQueryParameters) -> Microsoft.Identity.Client.ManagedIdentityApplicationBuilder
-static Microsoft.Identity.Client.ApplicationBase.ResetStateForTest() -> void
+static Microsoft.Identity.Client.ApplicationBase.ResetStateForTest() -> void

src/client/Microsoft.Identity.Client/PublicApi/net472/PublicAPI.Unshipped.txt

@@ -1,3 +1,5 @@
+Microsoft.Identity.Client.AbstractApplicationBuilder<T>.WithExtraQueryParameters(System.Collections.Generic.IDictionary<string, (string Value, bool IncludeInCacheKey)> extraQueryParameters) -> T
+Microsoft.Identity.Client.BaseAbstractAcquireTokenParameterBuilder<T>.WithExtraQueryParameters(System.Collections.Generic.IDictionary<string, (string Value, bool IncludeInCacheKey)> extraQueryParameters) -> T
 const Microsoft.Identity.Client.MsalError.CannotSwitchBetweenImdsVersionsForPreview = "cannot_switch_between_imds_versions_for_preview" -> string
 const Microsoft.Identity.Client.MsalError.InvalidCertificate = "invalid_certificate" -> string
 const Microsoft.Identity.Client.MsalError.MtlsNotSupportedForManagedIdentity = "mtls_not_supported_for_managed_identity" -> string

src/client/Microsoft.Identity.Client/PublicApi/net8.0-android/PublicAPI.Unshipped.txt

@@ -1,3 +1,5 @@
+Microsoft.Identity.Client.AbstractApplicationBuilder<T>.WithExtraQueryParameters(System.Collections.Generic.IDictionary<string, (string Value, bool IncludeInCacheKey)> extraQueryParameters) -> T
+Microsoft.Identity.Client.BaseAbstractAcquireTokenParameterBuilder<T>.WithExtraQueryParameters(System.Collections.Generic.IDictionary<string, (string Value, bool IncludeInCacheKey)> extraQueryParameters) -> T
 const Microsoft.Identity.Client.MsalError.CannotSwitchBetweenImdsVersionsForPreview = "cannot_switch_between_imds_versions_for_preview" -> string
 const Microsoft.Identity.Client.MsalError.InvalidCertificate = "invalid_certificate" -> string
 const Microsoft.Identity.Client.MsalError.MtlsNotSupportedForManagedIdentity = "mtls_not_supported_for_managed_identity" -> string
@@ -7,4 +9,4 @@ Microsoft.Identity.Client.IMsalMtlsHttpClientFactory.GetHttpClient(System.Securi
 Microsoft.Identity.Client.ManagedIdentityApplication.GetManagedIdentitySourceAsync() -> System.Threading.Tasks.Task<Microsoft.Identity.Client.ManagedIdentity.ManagedIdentitySource>
 Microsoft.Identity.Client.ManagedIdentity.ManagedIdentitySource.ImdsV2 = 8 -> Microsoft.Identity.Client.ManagedIdentity.ManagedIdentitySource
 Microsoft.Identity.Client.ManagedIdentityApplicationBuilder.WithExtraQueryParameters(System.Collections.Generic.IDictionary<string, string> extraQueryParameters) -> Microsoft.Identity.Client.ManagedIdentityApplicationBuilder
-static Microsoft.Identity.Client.ApplicationBase.ResetStateForTest() -> void
+static Microsoft.Identity.Client.ApplicationBase.ResetStateForTest() -> void

src/client/Microsoft.Identity.Client/PublicApi/net8.0-ios/PublicAPI.Unshipped.txt

@@ -1,3 +1,5 @@
+Microsoft.Identity.Client.AbstractApplicationBuilder<T>.WithExtraQueryParameters(System.Collections.Generic.IDictionary<string, (string Value, bool IncludeInCacheKey)> extraQueryParameters) -> T
+Microsoft.Identity.Client.BaseAbstractAcquireTokenParameterBuilder<T>.WithExtraQueryParameters(System.Collections.Generic.IDictionary<string, (string Value, bool IncludeInCacheKey)> extraQueryParameters) -> T
 const Microsoft.Identity.Client.MsalError.CannotSwitchBetweenImdsVersionsForPreview = "cannot_switch_between_imds_versions_for_preview" -> string
 const Microsoft.Identity.Client.MsalError.InvalidCertificate = "invalid_certificate" -> string
 const Microsoft.Identity.Client.MsalError.MtlsNotSupportedForManagedIdentity = "mtls_not_supported_for_managed_identity" -> string

src/client/Microsoft.Identity.Client/PublicApi/net8.0/PublicAPI.Unshipped.txt

@@ -1,3 +1,5 @@
+Microsoft.Identity.Client.AbstractApplicationBuilder<T>.WithExtraQueryParameters(System.Collections.Generic.IDictionary<string, (string Value, bool IncludeInCacheKey)> extraQueryParameters) -> T
+Microsoft.Identity.Client.BaseAbstractAcquireTokenParameterBuilder<T>.WithExtraQueryParameters(System.Collections.Generic.IDictionary<string, (string Value, bool IncludeInCacheKey)> extraQueryParameters) -> T
 const Microsoft.Identity.Client.MsalError.CannotSwitchBetweenImdsVersionsForPreview = "cannot_switch_between_imds_versions_for_preview" -> string
 const Microsoft.Identity.Client.MsalError.InvalidCertificate = "invalid_certificate" -> string
 const Microsoft.Identity.Client.MsalError.MtlsNotSupportedForManagedIdentity = "mtls_not_supported_for_managed_identity" -> string

src/client/Microsoft.Identity.Client/PublicApi/netstandard2.0/PublicAPI.Unshipped.txt

@@ -1,3 +1,5 @@
+Microsoft.Identity.Client.AbstractApplicationBuilder<T>.WithExtraQueryParameters(System.Collections.Generic.IDictionary<string, (string Value, bool IncludeInCacheKey)> extraQueryParameters) -> T
+Microsoft.Identity.Client.BaseAbstractAcquireTokenParameterBuilder<T>.WithExtraQueryParameters(System.Collections.Generic.IDictionary<string, (string Value, bool IncludeInCacheKey)> extraQueryParameters) -> T
 const Microsoft.Identity.Client.MsalError.CannotSwitchBetweenImdsVersionsForPreview = "cannot_switch_between_imds_versions_for_preview" -> string
 const Microsoft.Identity.Client.MsalError.InvalidCertificate = "invalid_certificate" -> string
 const Microsoft.Identity.Client.MsalError.MtlsNotSupportedForManagedIdentity = "mtls_not_supported_for_managed_identity" -> string