[core-rest-pipeline] Challenge callbacks (Azure#13888)

This PR adds Continuous Assessment Evaluation (CAE) support to core-rest-pipeline.

CAE support at the core level is about the following:

- Some way to pre-process requests.
- Some way to identify challenges.
- Some way to process challenges.
- Some way to handle the challenges, for example, use "scope" and "claims" from the challenges in the subsequent calls to retrieve access tokens.

For more information about CAE, see https://docs.microsoft.com/azure/active-directory/conditional-access/concept-continuous-access-evaluation

The changes this PR introduces:

- Add a new `bearerTokenChallengeAuthenticationPolicy` that provides a skeleton of handling CAE flow. There are two extensible points: `authorizeRequest` and `authroizeRequestOnChallenge` callbacks.
  - `authorizeRequest` allows customizing the policy to alter how it authorizes a request before sending it. By default when no callbacks are specified, this policy has the same behavior as `bearerTokenAuthenticationPolicy`. It will retrieve the token from the underlying token credential, and if it gets one, it will cache the token and set it to the outgoing request..
  - `authorizeRequestOnChallenge`, which gets called only if we've found a challenge in the response. This callback has access to the original request and its response and is expected to handle the challenge. If this callback returns true, the request, usually updated after handling the challenge, will be sent again. If this call back returns false, no further actions will be taken.

Fixes Azure#13156

Author: sadasant

common/config/rush/pnpm-lock.yaml

@@ -1,8 +1,10 @@
 # Release History
 
-## 1.0.4 (Unreleased)
+## 1.1.0-beta.1 (Unreleased)
 
-- Rewrote `bearerTokenAuthenticationPolicy` to use a new backend that refreshes tokens only when they're about to expire and not multiple times before. This is based on a similar fix implemented on `@azure/core-http@1.2.4` ([PR with the changes](https://github.com/Azure/azure-sdk-for-js/pull/14223)). This fixes the issue: [13369](https://github.com/Azure/azure-sdk-for-js/issues/13369).
+- Add a new `bearerTokenChallengeAuthenticationPolicy` that provides a skeleton of handling challenge-based authorization. There are two extensible points: `authorizeRequest` and `authorizeRequestOnChallenge` callbacks.
+  - `authorizeRequest` allows customizing the policy to alter how it authorizes a request before sending it. By default when no callbacks are specified, this policy has the same behavior as `bearerTokenAuthenticationPolicy`. It will retrieve the token from the underlying token credential, and if it gets one, it will cache the token and set it to the outgoing request.
+  - `authorizeRequestOnChallenge`, which gets called only if we've found a challenge in the response. This callback has access to the original request and its response and is expected to handle the challenge. If this callback returns true, the request, usually updated after handling the challenge, will be sent again. If this call back returns false, no further actions will be taken.
 
 ## 1.0.3 (2021-03-30)
 

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

@@ -1,6 +1,6 @@
 {
   "name": "@azure/core-rest-pipeline",
-  "version": "1.0.4",
+  "version": "1.1.0-beta.1",
   "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/package.json

@@ -5,7 +5,9 @@
 ```ts
 
 import { AbortSignalLike } from '@azure/abort-controller';
+import { AccessToken } from '@azure/core-auth';
 import { Debugger } from '@azure/logger';
+import { GetTokenOptions } from '@azure/core-auth';
 import { OperationTracingOptions } from '@azure/core-tracing';
 import { TokenCredential } from '@azure/core-auth';
 
@@ -26,6 +28,21 @@ export interface Agent {
     sockets: unknown;
 }
 
+// @public
+export interface AuthorizeRequestOnChallengeOptions {
+    getAccessToken: (scopes: string[], options: GetTokenOptions) => Promise<AccessToken | null>;
+    request: PipelineRequest;
+    response: PipelineResponse;
+    scopes: string[];
+}
+
+// @public
+export interface AuthorizeRequestOptions {
+    getAccessToken: (scopes: string[], options: GetTokenOptions) => Promise<AccessToken | null>;
+    request: PipelineRequest;
+    scopes: string[];
+}
+
 // @public
 export function bearerTokenAuthenticationPolicy(options: BearerTokenAuthenticationPolicyOptions): PipelinePolicy;
 
@@ -38,6 +55,25 @@ export interface BearerTokenAuthenticationPolicyOptions {
     scopes: string | string[];
 }
 
+// @public
+export function bearerTokenChallengeAuthenticationPolicy(options: BearerTokenChallengeAuthenticationPolicyOptions): PipelinePolicy;
+
+// @public
+export const bearerTokenChallengeAuthenticationPolicyName = "bearerTokenChallengeAuthenticationPolicy";
+
+// @public
+export interface BearerTokenChallengeAuthenticationPolicyOptions {
+    challengeCallbacks?: ChallengeCallbacks;
+    credential: TokenCredential;
+    scopes: string[];
+}
+
+// @public
+export interface ChallengeCallbacks {
+    authorizeRequest?(options: AuthorizeRequestOptions): Promise<void>;
+    authorizeRequestOnChallenge?(options: AuthorizeRequestOnChallengeOptions): Promise<boolean>;
+}
+
 // @public
 export function createDefaultHttpClient(): HttpClient;
 

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

@@ -1,4 +1,4 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT license.
 
-export const SDK_VERSION: string = "1.0.4";
+export const SDK_VERSION: string = "1.1.0-beta.1";

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

@@ -68,4 +68,12 @@ export {
   BearerTokenAuthenticationPolicyOptions,
   bearerTokenAuthenticationPolicyName
 } from "./policies/bearerTokenAuthenticationPolicy";
+export {
+  bearerTokenChallengeAuthenticationPolicy,
+  BearerTokenChallengeAuthenticationPolicyOptions,
+  bearerTokenChallengeAuthenticationPolicyName,
+  ChallengeCallbacks,
+  AuthorizeRequestOptions,
+  AuthorizeRequestOnChallengeOptions
+} from "./policies/bearerTokenChallengeAuthenticationPolicy";
 export { ndJsonPolicy, ndJsonPolicyName } from "./policies/ndJsonPolicy";

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

@@ -38,12 +38,12 @@ export function bearerTokenAuthenticationPolicy(
   // 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 getToken = createTokenCycler(credential, scopes /* , options */);
+  const cycler = createTokenCycler(credential /* , options */);
 
   return {
     name: bearerTokenAuthenticationPolicyName,
     async sendRequest(request: PipelineRequest, next: SendRequest): Promise<PipelineResponse> {
-      const { token } = await getToken({
+      const { token } = await cycler.getToken(scopes, {
         abortSignal: request.abortSignal,
         tracingOptions: request.tracingOptions
       });