Add OnBeforeAuthHeaderCreation / OnAfterAuthHeaderCreation hooks

src/Microsoft.Identity.Abstractions/DownstreamApi/AuthorizationHeaderProviderOptions.cs

@@ -38,6 +38,8 @@ public AuthorizationHeaderProviderOptions(AuthorizationHeaderProviderOptions oth
             AcquireTokenOptions = other.AcquireTokenOptions.Clone();
             HttpMethod = other.HttpMethod.ToString();
             CustomizeHttpRequestMessage = other.CustomizeHttpRequestMessage;
+            OnBeforeAuthHeaderCreation = other.OnBeforeAuthHeaderCreation;
+            OnAfterAuthHeaderCreation = other.OnAfterAuthHeaderCreation;
             ProtocolScheme = other.ProtocolScheme;
             RequestAppToken = other.RequestAppToken;
         }
@@ -75,6 +77,28 @@ public string HttpMethod
         /// </summary>
         public Action<HttpRequestMessage>? CustomizeHttpRequestMessage { get; set; }
 
+        /// <summary>
+        /// Provides an opportunity for the caller app to customize the <see cref="HttpRequestMessage"/> <b>before</b>
+        /// the authorization header is created. At this point the <c>Authorization</c> header is not yet present.
+        /// Use this to shape the request that a request-binding protocol signs — for example a SignedHttpRequest
+        /// (SHR) that binds the query, headers, or body (the <c>q</c>/<c>h</c>/<c>b</c> claims) to the token — so the
+        /// signature covers the finalized request. To observe or adjust the request <b>after</b> the header has been
+        /// created, use <see cref="OnAfterAuthHeaderCreation"/> (or <see cref="CustomizeHttpRequestMessage"/>).
+        /// </summary>
+        public Action<HttpRequestMessage>? OnBeforeAuthHeaderCreation { get; set; }
+
+        /// <summary>
+        /// Provides an opportunity for the caller app to customize the <see cref="HttpRequestMessage"/> <b>after</b>
+        /// the authorization header (including the <c>Authorization</c> header) has been set, and just before the
+        /// message is sent — the point at which the finalized request can be read or adjusted. Provided for naming
+        /// symmetry with <see cref="OnBeforeAuthHeaderCreation"/>; it shares this timing with the pre-existing
+        /// <see cref="CustomizeHttpRequestMessage"/>, which continues to be invoked for backwards compatibility. When
+        /// both are set they run at the same point, so callers should not depend on their relative order. Do
+        /// not modify material bound by a request-binding protocol (SHR <c>q</c>/<c>h</c>/<c>b</c>) here, since it
+        /// runs after signing; use <see cref="OnBeforeAuthHeaderCreation"/> for that.
+        /// </summary>
+        public Action<HttpRequestMessage>? OnAfterAuthHeaderCreation { get; set; }
+
         /// <summary>
         /// Options related to token acquisition.
         /// </summary>

src/Microsoft.Identity.Abstractions/PublicAPI/net10.0/PublicAPI.Unshipped.txt

@@ -1 +1,5 @@
 #nullable enable
+Microsoft.Identity.Abstractions.AuthorizationHeaderProviderOptions.OnAfterAuthHeaderCreation.get -> System.Action<System.Net.Http.HttpRequestMessage!>?
+Microsoft.Identity.Abstractions.AuthorizationHeaderProviderOptions.OnAfterAuthHeaderCreation.set -> void
+Microsoft.Identity.Abstractions.AuthorizationHeaderProviderOptions.OnBeforeAuthHeaderCreation.get -> System.Action<System.Net.Http.HttpRequestMessage!>?
+Microsoft.Identity.Abstractions.AuthorizationHeaderProviderOptions.OnBeforeAuthHeaderCreation.set -> void

src/Microsoft.Identity.Abstractions/PublicAPI/net462/PublicAPI.Unshipped.txt

@@ -1 +1,5 @@
 #nullable enable
+Microsoft.Identity.Abstractions.AuthorizationHeaderProviderOptions.OnAfterAuthHeaderCreation.get -> System.Action<System.Net.Http.HttpRequestMessage!>?
+Microsoft.Identity.Abstractions.AuthorizationHeaderProviderOptions.OnAfterAuthHeaderCreation.set -> void
+Microsoft.Identity.Abstractions.AuthorizationHeaderProviderOptions.OnBeforeAuthHeaderCreation.get -> System.Action<System.Net.Http.HttpRequestMessage!>?
+Microsoft.Identity.Abstractions.AuthorizationHeaderProviderOptions.OnBeforeAuthHeaderCreation.set -> void

src/Microsoft.Identity.Abstractions/PublicAPI/net8.0/PublicAPI.Unshipped.txt

@@ -1 +1,5 @@
 #nullable enable
+Microsoft.Identity.Abstractions.AuthorizationHeaderProviderOptions.OnAfterAuthHeaderCreation.get -> System.Action<System.Net.Http.HttpRequestMessage!>?
+Microsoft.Identity.Abstractions.AuthorizationHeaderProviderOptions.OnAfterAuthHeaderCreation.set -> void
+Microsoft.Identity.Abstractions.AuthorizationHeaderProviderOptions.OnBeforeAuthHeaderCreation.get -> System.Action<System.Net.Http.HttpRequestMessage!>?
+Microsoft.Identity.Abstractions.AuthorizationHeaderProviderOptions.OnBeforeAuthHeaderCreation.set -> void

src/Microsoft.Identity.Abstractions/PublicAPI/net9.0/PublicAPI.Unshipped.txt

@@ -1 +1,5 @@
 #nullable enable
+Microsoft.Identity.Abstractions.AuthorizationHeaderProviderOptions.OnAfterAuthHeaderCreation.get -> System.Action<System.Net.Http.HttpRequestMessage!>?
+Microsoft.Identity.Abstractions.AuthorizationHeaderProviderOptions.OnAfterAuthHeaderCreation.set -> void
+Microsoft.Identity.Abstractions.AuthorizationHeaderProviderOptions.OnBeforeAuthHeaderCreation.get -> System.Action<System.Net.Http.HttpRequestMessage!>?
+Microsoft.Identity.Abstractions.AuthorizationHeaderProviderOptions.OnBeforeAuthHeaderCreation.set -> void

src/Microsoft.Identity.Abstractions/PublicAPI/netstandard2.0/PublicAPI.Unshipped.txt

@@ -1 +1,5 @@
 #nullable enable
+Microsoft.Identity.Abstractions.AuthorizationHeaderProviderOptions.OnAfterAuthHeaderCreation.get -> System.Action<System.Net.Http.HttpRequestMessage!>?
+Microsoft.Identity.Abstractions.AuthorizationHeaderProviderOptions.OnAfterAuthHeaderCreation.set -> void
+Microsoft.Identity.Abstractions.AuthorizationHeaderProviderOptions.OnBeforeAuthHeaderCreation.get -> System.Action<System.Net.Http.HttpRequestMessage!>?
+Microsoft.Identity.Abstractions.AuthorizationHeaderProviderOptions.OnBeforeAuthHeaderCreation.set -> void

src/Microsoft.Identity.Abstractions/PublicAPI/netstandard2.1/PublicAPI.Unshipped.txt

@@ -1 +1,5 @@
 #nullable enable
+Microsoft.Identity.Abstractions.AuthorizationHeaderProviderOptions.OnAfterAuthHeaderCreation.get -> System.Action<System.Net.Http.HttpRequestMessage!>?
+Microsoft.Identity.Abstractions.AuthorizationHeaderProviderOptions.OnAfterAuthHeaderCreation.set -> void
+Microsoft.Identity.Abstractions.AuthorizationHeaderProviderOptions.OnBeforeAuthHeaderCreation.get -> System.Action<System.Net.Http.HttpRequestMessage!>?
+Microsoft.Identity.Abstractions.AuthorizationHeaderProviderOptions.OnBeforeAuthHeaderCreation.set -> void

test/Microsoft.Identity.Abstractions.Tests/DownstreamApiTests.cs

@@ -47,6 +47,8 @@ public void CloneClonesAllProperties()
                 },
                 BaseUrl = "https://apitocall.domain.com",
                 CustomizeHttpRequestMessage = message => message.Headers.Add("x-sku", "sku-value"),
+                OnBeforeAuthHeaderCreation = message => message.Headers.Add("x-before", "before-value"),
+                OnAfterAuthHeaderCreation = message => message.Headers.Add("x-after", "after-value"),
                 Deserializer = value => value,
                 Serializer = input => (input != null) ? new StringContent(input.ToString()!, Encoding.UTF8
 #if !NETFRAMEWORK
@@ -75,6 +77,8 @@ public void CloneClonesAllProperties()
             Assert.Equal(downstreamApiOptions.Scopes, downstreamApiClone.Scopes!);
             Assert.Equal(downstreamApiOptions.BaseUrl, downstreamApiClone.BaseUrl);
             Assert.Equal(downstreamApiOptions.CustomizeHttpRequestMessage, downstreamApiClone.CustomizeHttpRequestMessage);
+            Assert.Equal(downstreamApiOptions.OnBeforeAuthHeaderCreation, downstreamApiClone.OnBeforeAuthHeaderCreation);
+            Assert.Equal(downstreamApiOptions.OnAfterAuthHeaderCreation, downstreamApiClone.OnAfterAuthHeaderCreation);
             Assert.Equal(downstreamApiOptions.Deserializer, downstreamApiClone.Deserializer);
             Assert.Equal(downstreamApiOptions.Serializer, downstreamApiClone.Serializer);
             Assert.Equal(downstreamApiOptions.HttpMethod, downstreamApiClone.HttpMethod);
@@ -102,7 +106,7 @@ public void CloneClonesAllProperties()
             Assert.Equal(downstreamApiOptions.ExtraQueryParameters, downstreamApiClone.ExtraQueryParameters);
 
             // If this fails, think of also adding a line to test the new property
-            Assert.Equal(14, typeof(DownstreamApiOptions).GetProperties().Length);
+            Assert.Equal(16, typeof(DownstreamApiOptions).GetProperties().Length);
             Assert.Equal(15, typeof(AcquireTokenOptions).GetProperties().Length);
 
             DownstreamApiOptionsReadOnlyHttpMethod options = new DownstreamApiOptionsReadOnlyHttpMethod(downstreamApiOptions, HttpMethod.Delete.ToString());