Add ExtraHeaderParameters and ExtraQueryParameters to DownstreamApiOptions

.clinerules/abstractions-guidelines.md

@@ -70,6 +70,7 @@ Through its well-designed abstractions and interfaces, Microsoft.Identity.Abstra
   3. Include complete API signatures
   4. Consider backward compatibility impacts
   5. Document breaking changes clearly
+  6. Update the mermaid diagrams in the Readme.md file to reflect the changes to the public API.
 
 Example format:
 ```diff

Microsoft.Identity.Abstractions.sln

@@ -8,6 +8,8 @@ EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Items", "Solution Items", "{97E0DF27-D88E-453A-AFF6-3B656AB8F46B}"
 	ProjectSection(SolutionItems) = preProject
 		.editorconfig = .editorconfig
+		.clinerules\abstractions-guidelines.md = .clinerules\abstractions-guidelines.md
+		.github\copilot-instructions.md = .github\copilot-instructions.md
 		Directory.Build.props = Directory.Build.props
 		NuGet.config = NuGet.config
 		README.md = README.md

README.md

@@ -167,6 +167,8 @@ classDiagram
     <<rw>> +Func<HttpContent, Object> Deserializer
     <<rw>> +string AcceptHeader
     <<rw>> +string ContentType
+    <<rw>> +string ExtraQueryParameters
+    <<rw>> +string ExtraHeadersParameters
     }
     class DownstreamApiOptionsReadOnlyHttpMethod {
     +DownstreamApiOptionsReadOnlyHttpMethod Clone()
@@ -419,6 +421,8 @@ It's also possible (and recommended) to use higher level APIs:
     <<rw>> +Func<HttpContent, Object> Deserializer
     <<rw>> +string AcceptHeader
     <<rw>> +string ContentType
+    <<rw>> +IDictionary<string, string> ExtraQueryParameters
+    <<rw>> +IDictionary<string, string> ExtraHeadersParameters
     }
     class DownstreamApiOptionsReadOnlyHttpMethod {
     +DownstreamApiOptionsReadOnlyHttpMethod Clone()

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

@@ -22,7 +22,13 @@ namespace Microsoft.Identity.Abstractions
     ///     "MyProfile": {
     ///        "BaseUrl": "https://graph.microsoft.com/v1.0",
     ///        "RelativePath": "/me/profile",
-    ///         "Scopes": [ "user.read"]
+    ///         "Scopes": [ "user.read"],
+    ///         "ExtraHeaderParameters": {
+    ///           "OData-Version": "4.0"
+    ///         },
+    ///         "ExtraQueryParameters": {
+    ///           "filter": "displayName eq 'John'"
+    ///         }
     ///     }
     ///   ]
     /// ```
@@ -36,7 +42,13 @@ namespace Microsoft.Identity.Abstractions
     ///        "RelativePath": "/books/all",
     ///        "RequestAppToken": true,
     ///        "ProtocolScheme": "Pop",
-    ///         "Scopes": ["https://mylibrary.com/.default"]
+    ///         "Scopes": ["https://mylibrary.com/.default"],
+    ///         "ExtraHeaderParameters": {
+    ///           "X-API-Version": "v2"
+    ///         },
+    ///         "ExtraQueryParameters": {
+    ///           "format": "json"
+    ///         }
     ///     }
     ///   ]
     /// ```
@@ -62,6 +74,8 @@ public DownstreamApiOptions(DownstreamApiOptions other) : base(other)
             Deserializer = other.Deserializer;
             AcceptHeader = other.AcceptHeader;
             ContentType = other.ContentType;
+            ExtraHeaderParameters = other.ExtraHeaderParameters;
+            ExtraQueryParameters = other.ExtraQueryParameters;
         }
 
         /// <summary>
@@ -125,5 +139,21 @@ protected override AuthorizationHeaderProviderOptions CloneInternal()
         /// </summary>
         /// <default>application/json</default>
         public string ContentType { get; set; } = "application/json";
+
+        /// <summary>
+        /// Sets extra headers in the HTTP request to the downstream web API. This should
+        /// not be confounded with another option to set the headers in the request to the 
+        /// Identity Provider. See <see cref="AcquireTokenOptions.ExtraHeadersParameters"/> for 
+        /// that scenario.
+        /// </summary>
+        public IDictionary<string, string>? ExtraHeaderParameters { get; set; }
+
+        /// <summary>
+        /// Sets query parameters for the query string in the HTTP request to the 
+        /// downstream web API. This should not be confounded with another option to set the 
+        /// query parameters in the request to the Identity Provider. See 
+        /// <see cref="AcquireTokenOptions.ExtraQueryParameters"/> for that scenario.
+        /// </summary>
+        public IDictionary<string, string>? ExtraQueryParameters { get; set; }
     }
 }

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

@@ -1,38 +1,42 @@
-#nullable enable
-Microsoft.Identity.Abstractions.CredentialDescription.Algorithm.get -> string?
-Microsoft.Identity.Abstractions.CredentialDescription.Algorithm.set -> void
-Microsoft.Identity.Abstractions.IAuthorizationHeaderProvider<TResult>
-Microsoft.Identity.Abstractions.IAuthorizationHeaderProvider<TResult>.CreateAuthorizationHeaderAsync(Microsoft.Identity.Abstractions.DownstreamApiOptions! downstreamApiOptions, System.Security.Claims.ClaimsPrincipal? claimsPrincipal = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task<TResult>!
-Microsoft.Identity.Abstractions.MicrosoftEntraApplicationOptions
-Microsoft.Identity.Abstractions.MicrosoftEntraApplicationOptions.AppHomeTenantId.get -> string?
-Microsoft.Identity.Abstractions.MicrosoftEntraApplicationOptions.AppHomeTenantId.set -> void
-Microsoft.Identity.Abstractions.MicrosoftEntraApplicationOptions.AzureRegion.get -> string?
-Microsoft.Identity.Abstractions.MicrosoftEntraApplicationOptions.AzureRegion.set -> void
-Microsoft.Identity.Abstractions.MicrosoftEntraApplicationOptions.ClientCapabilities.get -> System.Collections.Generic.IEnumerable<string!>?
-Microsoft.Identity.Abstractions.MicrosoftEntraApplicationOptions.ClientCapabilities.set -> void
-Microsoft.Identity.Abstractions.MicrosoftEntraApplicationOptions.Instance.get -> string?
-Microsoft.Identity.Abstractions.MicrosoftEntraApplicationOptions.Instance.set -> void
-Microsoft.Identity.Abstractions.MicrosoftEntraApplicationOptions.MicrosoftEntraApplicationOptions() -> void
-Microsoft.Identity.Abstractions.MicrosoftEntraApplicationOptions.Name.get -> string?
-Microsoft.Identity.Abstractions.MicrosoftEntraApplicationOptions.Name.set -> void
-Microsoft.Identity.Abstractions.MicrosoftEntraApplicationOptions.SendX5C.get -> bool
-Microsoft.Identity.Abstractions.MicrosoftEntraApplicationOptions.SendX5C.set -> void
-Microsoft.Identity.Abstractions.MicrosoftEntraApplicationOptions.TenantId.get -> string?
-Microsoft.Identity.Abstractions.MicrosoftEntraApplicationOptions.TenantId.set -> void
-override Microsoft.Identity.Abstractions.MicrosoftEntraApplicationOptions.Authority.get -> string?
-override Microsoft.Identity.Abstractions.MicrosoftEntraApplicationOptions.Authority.set -> void
-Microsoft.Identity.Abstractions.OperationResult<TResult, TError>
-~override Microsoft.Identity.Abstractions.OperationResult<TResult, TError>.ToString() -> string
-~static Microsoft.Identity.Abstractions.OperationResult<TResult, TError>.operator !=(Microsoft.Identity.Abstractions.OperationResult<TResult, TError> left, Microsoft.Identity.Abstractions.OperationResult<TResult, TError> right) -> bool
-~static Microsoft.Identity.Abstractions.OperationResult<TResult, TError>.operator ==(Microsoft.Identity.Abstractions.OperationResult<TResult, TError> left, Microsoft.Identity.Abstractions.OperationResult<TResult, TError> right) -> bool
-override Microsoft.Identity.Abstractions.OperationResult<TResult, TError>.GetHashCode() -> int
-~override Microsoft.Identity.Abstractions.OperationResult<TResult, TError>.Equals(object obj) -> bool
-~Microsoft.Identity.Abstractions.OperationResult<TResult, TError>.Equals(Microsoft.Identity.Abstractions.OperationResult<TResult, TError> other) -> bool
-Microsoft.Identity.Abstractions.OperationResult<TResult, TError>.OperationResult() -> void
-Microsoft.Identity.Abstractions.OperationResult<TResult, TError>.OperationResult(TResult! result) -> void
-Microsoft.Identity.Abstractions.OperationResult<TResult, TError>.OperationResult(TError! error) -> void
-Microsoft.Identity.Abstractions.OperationResult<TResult, TError>.Succeeded.get -> bool
-Microsoft.Identity.Abstractions.OperationResult<TResult, TError>.Error.get -> TError?
-Microsoft.Identity.Abstractions.OperationResult<TResult, TError>.Result.get -> TResult?
-Microsoft.Identity.Abstractions.OperationError
-Microsoft.Identity.Abstractions.OperationError.OperationError() -> void
+#nullable enable
+Microsoft.Identity.Abstractions.CredentialDescription.Algorithm.get -> string?
+Microsoft.Identity.Abstractions.CredentialDescription.Algorithm.set -> void
+Microsoft.Identity.Abstractions.DownstreamApiOptions.ExtraHeaderParameters.get -> System.Collections.Generic.IDictionary<string!, string!>?
+Microsoft.Identity.Abstractions.DownstreamApiOptions.ExtraHeaderParameters.set -> void
+Microsoft.Identity.Abstractions.DownstreamApiOptions.ExtraQueryParameters.get -> System.Collections.Generic.IDictionary<string!, string!>?
+Microsoft.Identity.Abstractions.DownstreamApiOptions.ExtraQueryParameters.set -> void
+Microsoft.Identity.Abstractions.IAuthorizationHeaderProvider<TResult>
+Microsoft.Identity.Abstractions.IAuthorizationHeaderProvider<TResult>.CreateAuthorizationHeaderAsync(Microsoft.Identity.Abstractions.DownstreamApiOptions! downstreamApiOptions, System.Security.Claims.ClaimsPrincipal? claimsPrincipal = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task<TResult>!
+Microsoft.Identity.Abstractions.MicrosoftEntraApplicationOptions
+Microsoft.Identity.Abstractions.MicrosoftEntraApplicationOptions.AppHomeTenantId.get -> string?
+Microsoft.Identity.Abstractions.MicrosoftEntraApplicationOptions.AppHomeTenantId.set -> void
+Microsoft.Identity.Abstractions.MicrosoftEntraApplicationOptions.AzureRegion.get -> string?
+Microsoft.Identity.Abstractions.MicrosoftEntraApplicationOptions.AzureRegion.set -> void
+Microsoft.Identity.Abstractions.MicrosoftEntraApplicationOptions.ClientCapabilities.get -> System.Collections.Generic.IEnumerable<string!>?
+Microsoft.Identity.Abstractions.MicrosoftEntraApplicationOptions.ClientCapabilities.set -> void
+Microsoft.Identity.Abstractions.MicrosoftEntraApplicationOptions.Instance.get -> string?
+Microsoft.Identity.Abstractions.MicrosoftEntraApplicationOptions.Instance.set -> void
+Microsoft.Identity.Abstractions.MicrosoftEntraApplicationOptions.MicrosoftEntraApplicationOptions() -> void
+Microsoft.Identity.Abstractions.MicrosoftEntraApplicationOptions.Name.get -> string?
+Microsoft.Identity.Abstractions.MicrosoftEntraApplicationOptions.Name.set -> void
+Microsoft.Identity.Abstractions.MicrosoftEntraApplicationOptions.SendX5C.get -> bool
+Microsoft.Identity.Abstractions.MicrosoftEntraApplicationOptions.SendX5C.set -> void
+Microsoft.Identity.Abstractions.MicrosoftEntraApplicationOptions.TenantId.get -> string?
+Microsoft.Identity.Abstractions.MicrosoftEntraApplicationOptions.TenantId.set -> void
+override Microsoft.Identity.Abstractions.MicrosoftEntraApplicationOptions.Authority.get -> string?
+override Microsoft.Identity.Abstractions.MicrosoftEntraApplicationOptions.Authority.set -> void
+Microsoft.Identity.Abstractions.OperationResult<TResult, TError>
+~override Microsoft.Identity.Abstractions.OperationResult<TResult, TError>.ToString() -> string
+~static Microsoft.Identity.Abstractions.OperationResult<TResult, TError>.operator !=(Microsoft.Identity.Abstractions.OperationResult<TResult, TError> left, Microsoft.Identity.Abstractions.OperationResult<TResult, TError> right) -> bool
+~static Microsoft.Identity.Abstractions.OperationResult<TResult, TError>.operator ==(Microsoft.Identity.Abstractions.OperationResult<TResult, TError> left, Microsoft.Identity.Abstractions.OperationResult<TResult, TError> right) -> bool
+override Microsoft.Identity.Abstractions.OperationResult<TResult, TError>.GetHashCode() -> int
+~override Microsoft.Identity.Abstractions.OperationResult<TResult, TError>.Equals(object obj) -> bool
+~Microsoft.Identity.Abstractions.OperationResult<TResult, TError>.Equals(Microsoft.Identity.Abstractions.OperationResult<TResult, TError> other) -> bool
+Microsoft.Identity.Abstractions.OperationResult<TResult, TError>.OperationResult() -> void
+Microsoft.Identity.Abstractions.OperationResult<TResult, TError>.OperationResult(TResult! result) -> void
+Microsoft.Identity.Abstractions.OperationResult<TResult, TError>.OperationResult(TError! error) -> void
+Microsoft.Identity.Abstractions.OperationResult<TResult, TError>.Succeeded.get -> bool
+Microsoft.Identity.Abstractions.OperationResult<TResult, TError>.Error.get -> TError?
+Microsoft.Identity.Abstractions.OperationResult<TResult, TError>.Result.get -> TResult?
+Microsoft.Identity.Abstractions.OperationError
+Microsoft.Identity.Abstractions.OperationError.OperationError() -> void

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

@@ -3,6 +3,10 @@ Microsoft.Identity.Abstractions.CredentialDescription.Algorithm.get -> string?
 Microsoft.Identity.Abstractions.CredentialDescription.Algorithm.set -> void
 Microsoft.Identity.Abstractions.CredentialDescriptionJsonConverter
 Microsoft.Identity.Abstractions.CredentialDescriptionJsonConverter.CredentialDescriptionJsonConverter() -> void
+Microsoft.Identity.Abstractions.DownstreamApiOptions.ExtraHeaderParameters.get -> System.Collections.Generic.IDictionary<string!, string!>?
+Microsoft.Identity.Abstractions.DownstreamApiOptions.ExtraHeaderParameters.set -> void
+Microsoft.Identity.Abstractions.DownstreamApiOptions.ExtraQueryParameters.get -> System.Collections.Generic.IDictionary<string!, string!>?
+Microsoft.Identity.Abstractions.DownstreamApiOptions.ExtraQueryParameters.set -> void
 Microsoft.Identity.Abstractions.IAuthorizationHeaderProvider<TResult>
 Microsoft.Identity.Abstractions.IAuthorizationHeaderProvider<TResult>.CreateAuthorizationHeaderAsync(Microsoft.Identity.Abstractions.DownstreamApiOptions! downstreamApiOptions, System.Security.Claims.ClaimsPrincipal? claimsPrincipal = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task<TResult>!
 Microsoft.Identity.Abstractions.MicrosoftEntraApplicationOptions

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

@@ -3,6 +3,10 @@ Microsoft.Identity.Abstractions.CredentialDescription.Algorithm.get -> string?
 Microsoft.Identity.Abstractions.CredentialDescription.Algorithm.set -> void
 Microsoft.Identity.Abstractions.CredentialDescriptionJsonConverter
 Microsoft.Identity.Abstractions.CredentialDescriptionJsonConverter.CredentialDescriptionJsonConverter() -> void
+Microsoft.Identity.Abstractions.DownstreamApiOptions.ExtraHeaderParameters.get -> System.Collections.Generic.IDictionary<string!, string!>?
+Microsoft.Identity.Abstractions.DownstreamApiOptions.ExtraHeaderParameters.set -> void
+Microsoft.Identity.Abstractions.DownstreamApiOptions.ExtraQueryParameters.get -> System.Collections.Generic.IDictionary<string!, string!>?
+Microsoft.Identity.Abstractions.DownstreamApiOptions.ExtraQueryParameters.set -> void
 Microsoft.Identity.Abstractions.IAuthorizationHeaderProvider<TResult>
 Microsoft.Identity.Abstractions.IAuthorizationHeaderProvider<TResult>.CreateAuthorizationHeaderAsync(Microsoft.Identity.Abstractions.DownstreamApiOptions! downstreamApiOptions, System.Security.Claims.ClaimsPrincipal? claimsPrincipal = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task<TResult>!
 Microsoft.Identity.Abstractions.MicrosoftEntraApplicationOptions