Add auxiliary authentication header policy in core pipeline

sdk/core/core-rest-pipeline/CHANGELOG.md

@@ -1,9 +1,11 @@
 # Release History
 
-## 1.10.4 (Unreleased)
+## 1.11.0 (Unreleased)
 
 ### Features Added
 
+- Add a policy `auxiliaryAuthenticationHeaderPolicy` for external tokens to `x-ms-authorization-auxiliary` header. This header will be used when creating a cross-tenant application we may need to handle authentication requests for resources that are in different tenants. [PR #25270](https://github.com/Azure/azure-sdk-for-js/pull/25270)
+
 ### Breaking Changes
 
 ### Bugs Fixed

sdk/core/core-rest-pipeline/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@azure/core-rest-pipeline",
-  "version": "1.10.4",
+  "version": "1.11.0",
   "description": "Isomorphic client library for making HTTP requests in node.js and browser.",
   "sdk-type": "client",
   "main": "dist/index.js",

sdk/core/core-rest-pipeline/review/core-rest-pipeline.api.md

@@ -48,6 +48,19 @@ export interface AuthorizeRequestOptions {
     scopes: string[];
 }
 
+// @public
+export function auxiliaryAuthenticationHeaderPolicy(options: AuxiliaryAuthenticationHeaderPolicyOptions): PipelinePolicy;
+
+// @public
+export const auxiliaryAuthenticationHeaderPolicyName = "auxiliaryAuthenticationHeaderPolicy";
+
+// @public
+export interface AuxiliaryAuthenticationHeaderPolicyOptions {
+    credentials?: TokenCredential[];
+    logger?: AzureLogger;
+    scopes: string | string[];
+}
+
 // @public
 export function bearerTokenAuthenticationPolicy(options: BearerTokenAuthenticationPolicyOptions): PipelinePolicy;
 

sdk/core/core-rest-pipeline/src/index.ts

@@ -87,3 +87,8 @@ export {
   AuthorizeRequestOnChallengeOptions,
 } from "./policies/bearerTokenAuthenticationPolicy";
 export { ndJsonPolicy, ndJsonPolicyName } from "./policies/ndJsonPolicy";
+export {
+  auxiliaryAuthenticationHeaderPolicy,
+  AuxiliaryAuthenticationHeaderPolicyOptions,
+  auxiliaryAuthenticationHeaderPolicyName,
+} from "./policies/auxiliaryAuthenticationHeaderPolicy";

sdk/core/core-rest-pipeline/src/policies/auxiliaryAuthenticationHeaderPolicy.ts

@@ -0,0 +1,106 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+import { GetTokenOptions, TokenCredential } from "@azure/core-auth";
+import { AzureLogger } from "@azure/logger";
+import { PipelineRequest, PipelineResponse, SendRequest } from "../interfaces";
+import { PipelinePolicy } from "../pipeline";
+import { AccessTokenGetter, createTokenCycler } from "../util/tokenCycler";
+import { logger as coreLogger } from "../log";
+import { AuthorizeRequestOptions } from "./bearerTokenAuthenticationPolicy";
+
+/**
+ * The programmatic identifier of the auxiliaryAuthenticationHeaderPolicy.
+ */
+export const auxiliaryAuthenticationHeaderPolicyName = "auxiliaryAuthenticationHeaderPolicy";
+const AUTHORIZATION_AUXILIARY_HEADER = "x-ms-authorization-auxiliary";
+
+/**
+ * Options to configure the auxiliaryAuthenticationHeaderPolicy
+ */
+export interface AuxiliaryAuthenticationHeaderPolicyOptions {
+  /**
+   * TokenCredential list used to get token from auxiliary tenants and
+   * one credential for each tenant the client may need to access
+   */
+  credentials?: TokenCredential[];
+  /**
+   * Scopes depend on the cloud your application runs in
+   */
+  scopes: string | string[];
+  /**
+   * A logger can be sent for debugging purposes.
+   */
+  logger?: AzureLogger;
+}
+
+type NullableString = string | null | undefined;
+
+async function sendAuthorizeRequest(options: AuthorizeRequestOptions): Promise<NullableString> {
+  const { scopes, getAccessToken, request } = options;
+  const getTokenOptions: GetTokenOptions = {
+    abortSignal: request.abortSignal,
+    tracingOptions: request.tracingOptions,
+  };
+
+  return (await getAccessToken(scopes, getTokenOptions))?.token;
+}
+
+/**
+ * A policy for external tokens to `x-ms-authorization-auxiliary` header.
+ * This header will be used when creating a cross-tenant application we may need to handle authentication requests
+ * for resources that are in different tenants.
+ * You could see [ARM docs](https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/authenticate-multi-tenant) for a rundown of how this feature works
+ */
+export function auxiliaryAuthenticationHeaderPolicy(
+  options: AuxiliaryAuthenticationHeaderPolicyOptions
+): PipelinePolicy {
+  const { credentials, scopes } = options;
+  const logger = options.logger || coreLogger;
+  const tokenCyclerMap = new WeakMap<TokenCredential, AccessTokenGetter>();
+
+  return {
+    name: auxiliaryAuthenticationHeaderPolicyName,
+    async sendRequest(request: PipelineRequest, next: SendRequest): Promise<PipelineResponse> {
+      if (!request.url.toLowerCase().startsWith("https://")) {
+        throw new Error(
+          "Bearer token authentication for auxiliary header is not permitted for non-TLS protected (non-https) URLs."
+        );
+      }
+      if (!credentials || credentials.length === 0) {
+        logger.info(`Skip ${auxiliaryAuthenticationHeaderPolicyName} due to empty credentials`);
+        return next(request);
+      }
+
+      const tokenPromises: Promise<NullableString>[] = [];
+      for (const credential of credentials) {
+        if (!tokenCyclerMap.has(credential)) {
+          tokenCyclerMap.set(credential, createTokenCycler(credential));
+        }
+        tokenPromises.push(
+          sendAuthorizeRequest({
+            scopes: Array.isArray(scopes) ? scopes : [scopes],
+            request,
+            getAccessToken: tokenCyclerMap.get(credential)!,
+            logger,
+          })
+        );
+      }
+      const auxiliaryTokens: NullableString[] = (await Promise.all(tokenPromises)).filter((token) =>
+        Boolean(token)
+      );
+      if (auxiliaryTokens.length === 0) {
+        logger.warning(
+          `None of the auxiliary tokens are valid and skip to set ${AUTHORIZATION_AUXILIARY_HEADER} header`
+        );
+        return next(request);
+      }
+      request.headers.set(
+        AUTHORIZATION_AUXILIARY_HEADER,
+        auxiliaryTokens.map((token) => `Bearer ${token}`).join(", ")
+      );
+
+      return next(request);
+    },
+  };
+}