[Proposal] TokenCredentialRefresher and authenticationOptions

sdk/core/core-auth/CHANGELOG.md

@@ -4,6 +4,8 @@
 
 ### Features Added
 
+- New interface added: `TokenCredentialRefresher`. Represents a credential that can refresh a token over time.
+
 ### Breaking Changes
 
 ### Key Bugs Fixed

sdk/core/core-auth/review/core-auth.api.md

@@ -104,6 +104,11 @@ export interface TokenCredential {
     getToken(scopes: string | string[], options?: GetTokenOptions): Promise<AccessToken | null>;
 }
 
+// @public
+export interface TokenCredentialRefresher extends TokenCredential {
+    refreshToken(scopes: string | string[], options?: GetTokenOptions): Promise<AccessToken | null>;
+}
+
 
 // (No @packageDocumentation comment for this package)
 

sdk/core/core-auth/src/index.ts

@@ -11,6 +11,7 @@ export { AzureSASCredential, SASCredential, isSASCredential } from "./azureSASCr
 
 export {
   TokenCredential,
+  TokenCredentialRefresher,
   GetTokenOptions,
   AccessToken,
   isTokenCredential

sdk/core/core-auth/src/tokenCredential.ts

@@ -21,6 +21,22 @@ export interface TokenCredential {
   getToken(scopes: string | string[], options?: GetTokenOptions): Promise<AccessToken | null>;
 }
 
+/**
+ * Represents a credential capable of refreshing an authentication token over time.
+ */
+export interface TokenCredentialRefresher extends TokenCredential {
+  /**
+   * Retrieves previously stored token, or retrieves a new token.
+   *
+   * This method is called automatically by Azure SDK client libraries.
+   *
+   * @param scopes - The list of scopes for which the token will have access.
+   * @param options - The options used to configure any requests this
+   *                TokenCredential implementation might make.
+   */
+  refreshToken(scopes: string | string[], options?: GetTokenOptions): Promise<AccessToken | null>;
+}
+
 /**
  * Defines options for TokenCredential.getToken.
  */

sdk/core/core-client/CHANGELOG.md

@@ -4,6 +4,8 @@
 
 ### Features Added
 
+- Added a new optional property `authenticationOptions` to the `OperationOptions` interface. Through this property, users will be able to specify values that will modify the client authentication through the request pipelines.
+
 ### Breaking Changes
 
 ### Bugs Fixed

sdk/core/core-client/review/core-client.api.md

@@ -15,8 +15,14 @@ import { PipelinePolicy } from '@azure/core-rest-pipeline';
 import { PipelineRequest } from '@azure/core-rest-pipeline';
 import { PipelineResponse } from '@azure/core-rest-pipeline';
 import { TokenCredential } from '@azure/core-auth';
+import { TokenCredentialRefresher } from '@azure/core-auth';
 import { TransferProgressEvent } from '@azure/core-rest-pipeline';
 
+// @public
+export interface AuthenticationOptions {
+    credential?: TokenCredential | TokenCredentialRefresher;
+}
+
 // @public (undocumented)
 export interface BaseMapper {
     constraints?: MapperConstraints;
@@ -202,6 +208,7 @@ export interface OperationArguments {
 // @public
 export interface OperationOptions {
     abortSignal?: AbortSignalLike;
+    authenticationOptions?: AuthenticationOptions;
     onResponse?: RawResponseCallback;
     requestOptions?: OperationRequestOptions;
     serializerOptions?: SerializerOptions;

sdk/core/core-client/src/index.ts

@@ -8,6 +8,7 @@ export {
   OperationSpec,
   OperationArguments,
   OperationOptions,
+  AuthenticationOptions,
   OperationResponseMap,
   OperationParameter,
   OperationQueryParameter,

sdk/core/core-client/src/interfaces.ts

@@ -1,6 +1,7 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT license.
 
+import { TokenCredential, TokenCredentialRefresher } from "@azure/core-auth";
 import { AbortSignalLike } from "@azure/abort-controller";
 import { OperationTracingOptions } from "@azure/core-tracing";
 import {
@@ -37,6 +38,7 @@ export interface XmlOptions {
    */
   xmlCharKey?: string;
 }
+
 /**
  * Options to configure serialization/de-serialization behavior.
  */
@@ -47,6 +49,16 @@ export interface SerializerOptions {
   xml: XmlOptions;
 }
 
+/**
+ * Options to configure authentication.
+ */
+export interface AuthenticationOptions {
+  /**
+   * Optionally swap the operation credential.
+   */
+  credential?: TokenCredential | TokenCredentialRefresher;
+}
+
 export type RequiredSerializerOptions = {
   [K in keyof SerializerOptions]: Required<SerializerOptions[K]>;
 };
@@ -106,6 +118,10 @@ export interface OperationOptions {
    * Options to override serialization/de-serialization behavior.
    */
   serializerOptions?: SerializerOptions;
+  /**
+   * Options to configure authentication.
+   */
+  authenticationOptions?: AuthenticationOptions;
 
   /**
    * A function to be called each time a response is received from the server

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

@@ -10,6 +10,7 @@ import { Debugger } from '@azure/logger';
 import { GetTokenOptions } from '@azure/core-auth';
 import { OperationTracingOptions } from '@azure/core-tracing';
 import { TokenCredential } from '@azure/core-auth';
+import { TokenCredentialRefresher } from '@azure/core-auth';
 
 // @public
 export interface AddPipelineOptions {
@@ -52,7 +53,7 @@ export const bearerTokenAuthenticationPolicyName = "bearerTokenAuthenticationPol
 // @public
 export interface BearerTokenAuthenticationPolicyOptions {
     challengeCallbacks?: ChallengeCallbacks;
-    credential?: TokenCredential;
+    credential?: TokenCredential | TokenCredentialRefresher;
     scopes: string | string[];
 }
 
@@ -188,6 +189,9 @@ export interface PipelineRequest {
     abortSignal?: AbortSignalLike;
     agent?: Agent;
     allowInsecureConnection?: boolean;
+    authenticationOptions?: {
+        credential?: TokenCredential | TokenCredentialRefresher;
+    };
     body?: RequestBodyType;
     disableKeepAlive?: boolean;
     formData?: FormDataMap;

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

@@ -1,6 +1,7 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT license.
 
+import { TokenCredential, TokenCredentialRefresher } from "@azure/core-auth";
 import { AbortSignalLike } from "@azure/abort-controller";
 import { OperationTracingOptions } from "@azure/core-tracing";
 
@@ -156,6 +157,16 @@ export interface PipelineRequest {
    */
   tracingOptions?: OperationTracingOptions;
 
+  /**
+   * Options to configure authentication.
+   */
+  authenticationOptions?: {
+    /**
+     * Optionally swap the operation credential.
+     */
+    credential?: TokenCredential | TokenCredentialRefresher;
+  };
+
   /**
    * Callback which fires upon upload progress.
    */

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

@@ -1,10 +1,14 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT license.
 
-import { TokenCredential, GetTokenOptions, AccessToken } from "@azure/core-auth";
+import {
+  TokenCredential,
+  GetTokenOptions,
+  AccessToken,
+  TokenCredentialRefresher
+} from "@azure/core-auth";
 import { PipelineResponse, PipelineRequest, SendRequest } from "../interfaces";
 import { PipelinePolicy } from "../pipeline";
-import { createTokenCycler } from "../util/tokenCycler";
 
 /**
  * The programmatic identifier of the bearerTokenAuthenticationPolicy.
@@ -75,7 +79,7 @@ export interface BearerTokenAuthenticationPolicyOptions {
   /**
    * The TokenCredential implementation that can supply the bearer token.
    */
-  credential?: TokenCredential;
+  credential?: TokenCredential | TokenCredentialRefresher;
   /**
    * The scopes for which the bearer token applies.
    */
@@ -131,14 +135,6 @@ export function bearerTokenAuthenticationPolicy(
     ...challengeCallbacks
   };
 
-  // This function encapsulates the entire process of reliably retrieving the token
-  // The options are left out of the public API until there's demand to configure this.
-  // Remember to extend `BearerTokenAuthenticationPolicyOptions` with `TokenCyclerOptions`
-  // in order to pass through the `options` object.
-  const getAccessToken = credential
-    ? createTokenCycler(credential /* , options */)
-    : () => Promise.resolve(null);
-
   return {
     name: bearerTokenAuthenticationPolicyName,
     /**
@@ -161,6 +157,15 @@ export function bearerTokenAuthenticationPolicy(
         );
       }
 
+      // TODO:
+      // If we changed the AuthorizeRequestOptions to incldue the credential instead of the getAccessToken method,
+      // then we could skip this part and just pass any of these credentials directly.
+      const refreshCredential = request.authenticationOptions?.credential ?? credential;
+      const getAccessToken =
+        (refreshCredential as TokenCredentialRefresher)?.refreshToken?.bind(refreshCredential) ??
+        refreshCredential?.getToken.bind(refreshCredential) ??
+        (() => Promise.resolve(null));
+
       await callbacks.authorizeRequest({
         scopes: Array.isArray(scopes) ? scopes : [scopes],
         request,