[Identity] Add token provider (#28645)

In our work to add support for AAD authentication in external clients,
we need a public API to get access tokens. This PR adds one similar to
Python's one added in
Azure/azure-sdk-for-python#32655.

~TODO: add tests and samples~.

Author: deyaaeldeen

sdk/identity/identity/CHANGELOG.md

@@ -4,6 +4,8 @@
 
 ### Features Added
 
+- Adds support for `getBearerTokenProvider` that returns a callback function to get a token for a given scope. This is useful for scenarios where an explicit Entra token is needed without having to worry about the token refreshing details.
+
 ### Breaking Changes
 
 ### Bugs Fixed

sdk/identity/identity/assets.json

@@ -2,5 +2,5 @@
   "AssetsRepo": "Azure/azure-sdk-assets",
   "AssetsRepoPrefixPath": "js",
   "TagPrefix": "js/identity/identity",
-  "Tag": "js/identity/identity_9b15d10264"
+  "Tag": "js/identity/identity_58e656fd32"
 }

sdk/identity/identity/review/identity.api.md

@@ -10,6 +10,7 @@ import { CommonClientOptions } from '@azure/core-client';
 import { GetTokenOptions } from '@azure/core-auth';
 import { LogPolicyOptions } from '@azure/core-rest-pipeline';
 import { TokenCredential } from '@azure/core-auth';
+import type { TracingContext } from '@azure/core-auth';
 
 export { AccessToken }
 
@@ -288,6 +289,17 @@ export interface ErrorResponse {
     traceId?: string;
 }
 
+// @public
+export function getBearerTokenProvider(credential: TokenCredential, scopes: string | string[], options?: GetBearerTokenProviderOptions): () => Promise<string>;
+
+// @public
+export interface GetBearerTokenProviderOptions {
+    abortSignal?: AbortSignal;
+    tracingOptions?: {
+        tracingContext?: TracingContext;
+    };
+}
+
 // @public
 export function getDefaultAzureCredential(): TokenCredential;
 

sdk/identity/identity/samples-dev/tokenProvider.ts

@@ -0,0 +1,32 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+/**
+ * @summary demonstrates how to get a bearer token.
+ */
+
+import { PipelineRequest, createPipelineRequest } from "@azure/core-rest-pipeline";
+import { getBearerTokenProvider, DefaultAzureCredential } from "@azure/identity";
+import { config } from "dotenv";
+
+// Load the .env file if it exists
+config();
+
+export async function main(): Promise<void> {
+  const credential = new DefaultAzureCredential();
+  const scope = "https://cognitiveservices.azure.com/.default";
+  const getAccessToken = getBearerTokenProvider(credential, scope);
+  const token = await getAccessToken();
+
+  // create a request
+  const request: PipelineRequest = createPipelineRequest({ url: "https://example.com" });
+  // add the access token to the request
+  request.headers.set("Authorization", `Bearer ${token}`);
+  console.log("Authorization header has been added to the request");
+}
+
+main().catch((err) => {
+  console.log("error code: ", err.code);
+  console.log("error message: ", err.message);
+  console.log("error stack: ", err.stack);
+});

sdk/identity/identity/src/index.ts

@@ -113,3 +113,5 @@ export { AzureAuthorityHosts } from "./constants";
 export function getDefaultAzureCredential(): TokenCredential {
   return new DefaultAzureCredential();
 }
+
+export { getBearerTokenProvider, GetBearerTokenProviderOptions } from "./tokenProvider";

sdk/identity/identity/src/tokenProvider.ts

@@ -0,0 +1,80 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+import type { TokenCredential, TracingContext } from "@azure/core-auth";
+import {
+  bearerTokenAuthenticationPolicy,
+  createEmptyPipeline,
+  createPipelineRequest,
+} from "@azure/core-rest-pipeline";
+
+/**
+ * The options to configure the token provider.
+ */
+export interface GetBearerTokenProviderOptions {
+  /** The abort signal to abort requests to get tokens */
+  abortSignal?: AbortSignal;
+  /** The tracing options for the requests to get tokens */
+  tracingOptions?: {
+    /**
+     * Tracing Context for the current request to get a token.
+     */
+    tracingContext?: TracingContext;
+  };
+}
+
+/**
+ * Returns a callback that provides a bearer token.
+ * For example, the bearer token can be used to authenticate a request as follows:
+ * ```js
+ * import { DefaultAzureCredential } from "@azure/identity";
+ *
+ * const credential = new DefaultAzureCredential();
+ * const scope = "https://cognitiveservices.azure.com/.default";
+ * const getAccessToken = getBearerTokenProvider(credential, scope);
+ * const token = await getAccessToken();
+ *
+ * // usage
+ * const request = createPipelineRequest({ url: "https://example.com" });
+ * request.headers.set("Authorization", `Bearer ${token}`);
+ * ```
+ *
+ * @param credential - The credential used to authenticate the request.
+ * @param scopes - The scopes required for the bearer token.
+ * @param options - Options to configure the token provider.
+ * @returns a callback that provides a bearer token.
+ */
+export function getBearerTokenProvider(
+  credential: TokenCredential,
+  scopes: string | string[],
+  options?: GetBearerTokenProviderOptions,
+): () => Promise<string> {
+  const { abortSignal, tracingOptions } = options || {};
+  const pipeline = createEmptyPipeline();
+  pipeline.addPolicy(bearerTokenAuthenticationPolicy({ credential, scopes }));
+  async function getRefreshedToken(): Promise<string> {
+    // Create a pipeline with just the bearer token policy
+    // and run a dummy request through it to get the token
+    const res = await pipeline.sendRequest(
+      {
+        sendRequest: (request) =>
+          Promise.resolve({
+            request,
+            status: 200,
+            headers: request.headers,
+          }),
+      },
+      createPipelineRequest({
+        url: "https://example.com",
+        abortSignal,
+        tracingOptions,
+      }),
+    );
+    const accessToken = res.headers.get("authorization")?.split(" ")[1];
+    if (!accessToken) {
+      throw new Error("Failed to get access token");
+    }
+    return accessToken;
+  }
+  return getRefreshedToken;
+}

sdk/identity/identity/test/public/node/tokenProvider.spec.ts

@@ -0,0 +1,38 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+import { EnvironmentCredential, getBearerTokenProvider } from "../../../src";
+import { MsalTestCleanup, msalNodeTestSetup } from "../../node/msalNodeTestSetup";
+import { Recorder, delay, isPlaybackMode } from "@azure-tools/test-recorder";
+import { Context } from "mocha";
+import { assert } from "@azure/test-utils";
+
+describe("getBearerTokenProvider", function () {
+  let cleanup: MsalTestCleanup;
+  let recorder: Recorder;
+
+  beforeEach(async function (this: Context) {
+    const setup = await msalNodeTestSetup(this.currentTest);
+    recorder = setup.recorder;
+    cleanup = setup.cleanup;
+  });
+  afterEach(async function () {
+    await cleanup();
+  });
+
+  const scope = "https://vault.azure.net/.default";
+
+  it("returns a callback that returns string tokens", async function () {
+    const credential = new EnvironmentCredential(recorder.configureClientOptions({}));
+
+    const getAccessToken = getBearerTokenProvider(credential, scope);
+
+    for (let i = 0; i < 5; i++) {
+      if (!isPlaybackMode()) {
+        await delay(500);
+      }
+      const token = await getAccessToken();
+      assert.isString(token);
+    }
+  });
+});