new-feature

Author: GladwinJohnson

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

@@ -158,6 +158,26 @@ public AcquireTokenForClientParameterBuilder WithFmiPath(string pathSuffix)
             return this;
         }
 
+        /// <summary>
+        /// Specifies that the token refresh should only occur if the specified SHA-256 hash
+        /// of the previously issued access token matches a cached token.
+        /// If the hash does not match, the existing cached token is returned without refresh.
+        /// </summary>
+        /// <param name="hash">The SHA-256 hash of the access token to refresh.</param>
+        /// <returns>The builder to chain the .With methods</returns>
+        public AcquireTokenForClientParameterBuilder WithAccessTokenSha256ToRefresh(string hash)
+        {
+            ValidateUseOfExperimentalFeature();
+
+            if (string.IsNullOrWhiteSpace(hash))
+            {
+                throw new ArgumentNullException(nameof(hash), "Access token hash cannot be null or empty.");
+            }
+
+            Parameters.AccessTokenHashToRefresh = hash;
+            return this;
+        }
+
         /// <inheritdoc/>
         internal override Task<AuthenticationResult> ExecuteInternalAsync(CancellationToken cancellationToken)
         {
@@ -198,6 +218,14 @@ protected override void Validate()
 
             base.Validate();
 
+            // Force refresh + AccessTokenHashToRefresh APIs cannot be used together
+            if (Parameters.ForceRefresh && !string.IsNullOrEmpty(Parameters.AccessTokenHashToRefresh))
+            {
+                throw new MsalClientException(
+                    MsalError.ForceRefreshNotCompatibleWithTokenHash,
+                    MsalErrorMessage.ForceRefreshAndTokenHasNotCompatible);
+            }
+
             if (Parameters.SendX5C == null)
             {
                 Parameters.SendX5C = this.ServiceBundle.Config.SendX5C;

src/client/Microsoft.Identity.Client/ApiConfig/Parameters/AcquireTokenForClientParameters.cs

@@ -9,9 +9,13 @@ namespace Microsoft.Identity.Client.ApiConfig.Parameters
 {
     internal class AcquireTokenForClientParameters : AbstractAcquireTokenConfidentialClientParameters, IAcquireTokenParameters
     {
+        public bool ForceRefresh { get; set; }
+
         /// <summary>
+        /// The SHA-256 hash of the access token that should be refreshed.
+        /// If set, token refresh will occur only if a matching token is found in cache.
         /// </summary>
-        public bool ForceRefresh { get; set; }
+        public string AccessTokenHashToRefresh { get; set; }
 
         /// <inheritdoc/>
         public void LogParameters(ILoggerAdapter logger)

src/client/Microsoft.Identity.Client/Internal/Requests/ClientCredentialRequest.cs

@@ -1,7 +1,10 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT License.
 
+using System;
 using System.Collections.Generic;
+using System.Security.Cryptography;
+using System.Text;
 using System.Threading;
 using System.Threading.Tasks;
 using Microsoft.Identity.Client.ApiConfig.Parameters;
@@ -47,8 +50,12 @@ protected override async Task<AuthenticationResult> ExecuteAsync(CancellationTok
 
             AuthenticationResult authResult;
 
+            bool skipCache = _clientParameters.ForceRefresh || 
+                (!string.IsNullOrEmpty(AuthenticationRequestParameters.Claims) && 
+                string.IsNullOrEmpty(_clientParameters.AccessTokenHashToRefresh));
+
             // Skip checking cache when force refresh or claims are specified
-            if (_clientParameters.ForceRefresh || !string.IsNullOrEmpty(AuthenticationRequestParameters.Claims))
+            if (skipCache)
             {
                 AuthenticationRequestParameters.RequestContext.ApiEvent.CacheInfo = CacheRefreshReason.ForceRefreshOrClaims;
                 logger.Info("[ClientCredentialRequest] Skipped looking for a cached access token because ForceRefresh or Claims were set.");
@@ -193,6 +200,18 @@ private async Task<MsalAccessTokenCacheItem> GetCachedAccessTokenAsync()
 
             if (cachedAccessTokenItem != null && !_clientParameters.ForceRefresh)
             {
+                if (!string.IsNullOrEmpty(_clientParameters.AccessTokenHashToRefresh))
+                {
+                    string cachedTokenHash = ComputeSHA256(cachedAccessTokenItem.Secret);
+
+                    if (string.Equals(cachedTokenHash, _clientParameters.AccessTokenHashToRefresh, StringComparison.Ordinal))
+                    {
+                        AuthenticationRequestParameters.RequestContext.Logger.Info(
+                            "[ClientCredentialRequest] Found the 'bad' token in the cache. Skipping cache usage.");
+                        return null; // triggers a new token acquisition
+                    }
+                }
+
                 AuthenticationRequestParameters.RequestContext.ApiEvent.IsAccessTokenCacheHit = true;
                 Metrics.IncrementTotalAccessTokensFromCache();
                 return cachedAccessTokenItem;
@@ -201,6 +220,20 @@ private async Task<MsalAccessTokenCacheItem> GetCachedAccessTokenAsync()
             return null;
         }
 
+        private static string ComputeSHA256(string token)
+        {
+#if NET6_0_OR_GREATER
+            byte[] hashBytes = SHA256.HashData(Encoding.UTF8.GetBytes(token));
+            return Convert.ToBase64String(hashBytes);
+#else
+            using (var sha256 = SHA256.Create())
+            {
+                byte[] hashBytes = sha256.ComputeHash(Encoding.UTF8.GetBytes(token));
+                return Convert.ToBase64String(hashBytes);
+            }
+#endif
+        }
+
         private AuthenticationResult CreateAuthenticationResultFromCache(MsalAccessTokenCacheItem cachedAccessTokenItem)
         {
             AuthenticationResult authResult = new AuthenticationResult(

src/client/Microsoft.Identity.Client/MsalError.cs

@@ -1177,5 +1177,16 @@ public static class MsalError
         /// <para>Mitigation:</para> Ensure that the AzureRegion configuration is set when using mTLS PoP as it requires a regional endpoint.
         /// </summary>
         public const string RegionRequiredForMtlsPop = "region_required_for_mtls_pop";
+
+        /// <summary>
+        /// <para>What happened?</para> The operation attempted to force a token refresh while also using a token hash. 
+        /// These two options are incompatible because forcing a refresh bypasses token caching, 
+        /// which conflicts with token hash validation.
+        /// <para>Mitigation:</para>
+        /// - Ensure that `force_refresh` is not set to `true` when using a token hash.
+        /// - Review the request parameters to ensure they are not conflicting.
+        /// - If token hashing is required, allow the cached token to be used instead of forcing a refresh.
+        /// </summary>
+        public const string ForceRefreshNotCompatibleWithTokenHash = "force_refresh_and_token_hash_not_compatible";
     }
 }

src/client/Microsoft.Identity.Client/MsalErrorMessage.cs

@@ -437,5 +437,6 @@ public static string InvalidTokenProviderResponseValue(string invalidValueName)
         public const string MtlsInvalidAuthorityTypeMessage = "mTLS PoP is only supported for AAD authority type. See https://aka.ms/msal-net-pop for details.";
         public const string MtlsNonTenantedAuthorityNotAllowedMessage = "mTLS authentication requires a tenanted authority. Using 'common', 'organizations', or similar non-tenanted authorities is not allowed. Please provide an authority with a specific tenant ID (e.g., 'https://login.microsoftonline.com/{tenantId}'). See https://aka.ms/msal-net-pop for details.";
         public const string RegionRequiredForMtlsPopMessage = "Regional auto-detect failed. mTLS Proof-of-Possession requires a region to be specified, as there is no global endpoint for mTLS. See https://aka.ms/msal-net-pop for details.";
+        public const string ForceRefreshAndTokenHasNotCompatible = "Cannot specify ForceRefresh and AccessTokenSha256ToRefresh in the same request.";
     }
 }

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

@@ -0,0 +1,2 @@
+const Microsoft.Identity.Client.MsalError.ForceRefreshNotCompatibleWithTokenHash = "force_refresh_and_token_hash_not_compatible" -> string
+Microsoft.Identity.Client.AcquireTokenForClientParameterBuilder.WithAccessTokenSha256ToRefresh(string hash) -> Microsoft.Identity.Client.AcquireTokenForClientParameterBuilder

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

@@ -0,0 +1,2 @@
+const Microsoft.Identity.Client.MsalError.ForceRefreshNotCompatibleWithTokenHash = "force_refresh_and_token_hash_not_compatible" -> string
+Microsoft.Identity.Client.AcquireTokenForClientParameterBuilder.WithAccessTokenSha256ToRefresh(string hash) -> Microsoft.Identity.Client.AcquireTokenForClientParameterBuilder

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

@@ -0,0 +1,2 @@
+const Microsoft.Identity.Client.MsalError.ForceRefreshNotCompatibleWithTokenHash = "force_refresh_and_token_hash_not_compatible" -> string
+Microsoft.Identity.Client.AcquireTokenForClientParameterBuilder.WithAccessTokenSha256ToRefresh(string hash) -> Microsoft.Identity.Client.AcquireTokenForClientParameterBuilder

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

@@ -0,0 +1,2 @@
+const Microsoft.Identity.Client.MsalError.ForceRefreshNotCompatibleWithTokenHash = "force_refresh_and_token_hash_not_compatible" -> string
+Microsoft.Identity.Client.AcquireTokenForClientParameterBuilder.WithAccessTokenSha256ToRefresh(string hash) -> Microsoft.Identity.Client.AcquireTokenForClientParameterBuilder

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

@@ -0,0 +1,2 @@
+const Microsoft.Identity.Client.MsalError.ForceRefreshNotCompatibleWithTokenHash = "force_refresh_and_token_hash_not_compatible" -> string
+Microsoft.Identity.Client.AcquireTokenForClientParameterBuilder.WithAccessTokenSha256ToRefresh(string hash) -> Microsoft.Identity.Client.AcquireTokenForClientParameterBuilder