[core-rest-pipeline] Challenge callbacks

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

@@ -29,6 +29,7 @@ export class AzureSASCredential implements SASCredential {
 // @public
 export interface GetTokenOptions {
     abortSignal?: AbortSignalLike;
+    claims?: string;
     requestOptions?: {
         timeout?: number;
     };

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

@@ -25,6 +25,10 @@ export interface TokenCredential {
  * Defines options for TokenCredential.getToken.
  */
 export interface GetTokenOptions {
+  /**
+   * Challenge claims
+   */
+  claims?: string;
   /**
    * The signal which can be used to abort requests.
    */

sdk/core/core-https/CHANGELOG.md

@@ -4,6 +4,7 @@
 
 - Changed from exposing `DefaultHttpsClient` as a class directly, to providing `createDefaultHttpsClient()` to instantiate the appropriate runtime class.
 - Fix an issue when passing in proxy hosts. [PR 13911](https://github.com/Azure/azure-sdk-for-js/pull/13911)
+- Added a `challengeAuthenticationPolicy` with features to support [CAE](https://docs.microsoft.com/azure/active-directory/conditional-access/concept-continuous-access-evaluation).
 
 ## 1.0.0-beta.1 (2021-02-04)
 

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

@@ -17,6 +17,12 @@ export interface AddPipelineOptions {
     phase?: PipelinePhase;
 }
 
+// @public
+export interface AuthenticationContext {
+    claims?: string;
+    scopes?: string | string[];
+}
+
 // @public
 export function bearerTokenAuthenticationPolicy(options: BearerTokenAuthenticationPolicyOptions): PipelinePolicy;
 
@@ -25,10 +31,25 @@ export const bearerTokenAuthenticationPolicyName = "bearerTokenAuthenticationPol
 
 // @public
 export interface BearerTokenAuthenticationPolicyOptions {
+    authenticationContext?: AuthenticationContext;
     credential: TokenCredential;
     scopes: string | string[];
 }
 
+// @public
+export function challengeAuthenticationPolicy(options: ChallengeAuthenticationPolicyOptions): PipelinePolicy;
+
+// @public
+export const challengeAuthenticationPolicyName = "challengeAuthenticationPolicy";
+
+// @public
+export interface ChallengeAuthenticationPolicyOptions {
+    authenticationContext: AuthenticationContext;
+    getChallenge?(response: PipelineResponse): string | undefined;
+    prepareRequest?(request: PipelineRequest): Promise<void>;
+    processChallenge(challenge: string, context: AuthenticationContext): Promise<boolean>;
+}
+
 // @public
 export function createDefaultHttpsClient(): HttpsClient;
 

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

@@ -13,7 +13,8 @@ export {
   ProxySettings,
   RawHttpHeaders,
   TransferProgressEvent,
-  RequestBodyType
+  RequestBodyType,
+  AuthenticationContext
 } from "./interfaces";
 export {
   AddPolicyOptions as AddPipelineOptions,
@@ -67,4 +68,9 @@ export {
   BearerTokenAuthenticationPolicyOptions,
   bearerTokenAuthenticationPolicyName
 } from "./policies/bearerTokenAuthenticationPolicy";
+export {
+  challengeAuthenticationPolicy,
+  ChallengeAuthenticationPolicyOptions,
+  challengeAuthenticationPolicyName
+} from "./policies/challengeAuthenticationPolicy";
 export { ndJsonPolicy, ndJsonPolicyName } from "./policies/ndJsonPolicy";

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

@@ -274,3 +274,17 @@ export type FormDataValue = string | Blob;
  * A simple object that provides form data, as if from a browser form.
  */
 export type FormDataMap = { [key: string]: FormDataValue | FormDataValue[] };
+
+/**
+ * Allows the discovery of authentication properties.
+ */
+export interface AuthenticationContext {
+  /**
+   * Scopes to overwrite during the get token request.
+   */
+  scopes?: string | string[];
+  /**
+   * Claims that can be used by the credential's getToken request.
+   */
+  claims?: string;
+}

sdk/core/core-https/src/policies/bearerTokenAuthenticationPolicy.ts

@@ -1,7 +1,12 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT license.
 
-import { PipelineResponse, PipelineRequest, SendRequest } from "../interfaces";
+import {
+  PipelineResponse,
+  PipelineRequest,
+  SendRequest,
+  AuthenticationContext
+} from "../interfaces";
 import { PipelinePolicy } from "../pipeline";
 import { TokenCredential, GetTokenOptions } from "@azure/core-auth";
 import { AccessTokenCache, ExpiringAccessTokenCache } from "../accessTokenCache";
@@ -23,6 +28,10 @@ export interface BearerTokenAuthenticationPolicyOptions {
    * The scopes for which the bearer token applies.
    */
   scopes: string | string[];
+  /**
+   * Allows the dynamic discovery of authentication properties.
+   */
+  authenticationContext?: AuthenticationContext;
 }
 
 /**
@@ -34,10 +43,14 @@ export function bearerTokenAuthenticationPolicy(
 ): PipelinePolicy {
   const { credential, scopes } = options;
   const tokenCache: AccessTokenCache = new ExpiringAccessTokenCache();
+  const authenticationContext: AuthenticationContext = options.authenticationContext || {};
+
   async function getToken(tokenOptions: GetTokenOptions): Promise<string | undefined> {
     let accessToken = tokenCache.getCachedToken();
     if (accessToken === undefined) {
-      accessToken = (await credential.getToken(scopes, tokenOptions)) || undefined;
+      accessToken =
+        (await credential.getToken(authenticationContext.scopes || scopes, tokenOptions)) ||
+        undefined;
       tokenCache.setCachedToken(accessToken);
     }
 
@@ -50,8 +63,10 @@ export function bearerTokenAuthenticationPolicy(
         abortSignal: request.abortSignal,
         tracingOptions: {
           spanOptions: request.spanOptions
-        }
+        },
+        claims: authenticationContext.claims
       });
+
       request.headers.set("Authorization", `Bearer ${token}`);
       return next(request);
     }

sdk/core/core-https/src/policies/challengeAuthenticationPolicy.ts

@@ -0,0 +1,86 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+import {
+  PipelineResponse,
+  PipelineRequest,
+  SendRequest,
+  AuthenticationContext
+} from "../interfaces";
+import { PipelinePolicy } from "../pipeline";
+
+/**
+ * The programmatic identifier of the challengeAuthenticationPolicy.
+ */
+export const challengeAuthenticationPolicyName = "challengeAuthenticationPolicy";
+
+/**
+ * Options to configure the challengeAuthenticationPolicy
+ */
+export interface ChallengeAuthenticationPolicyOptions {
+  /**
+   * Authentication context that can bind together the challengeAuthenticationPolicy with other policies.
+   * The second policy should also receive an authenticationContext in their options.
+   * By default, the only other policy that supports this is the bearerTokenAuthenticationPolicy.
+   */
+  authenticationContext: AuthenticationContext;
+  /**
+   * Allows for the customization of the next request before its sent.
+   */
+  prepareRequest?(request: PipelineRequest): Promise<void>;
+  /**
+   * Defines how to get the challenge from the PipelineResponse.
+   * By default we will retrieve the challenge only if the response status code was 401,
+   * and if the response contained the header "WWW-Authenticate" with a non-empty value.
+   */
+  getChallenge?(response: PipelineResponse): string | undefined;
+  /**
+   * Updates  the authentication context based on the challenge.
+   */
+  processChallenge(challenge: string, context: AuthenticationContext): Promise<boolean>;
+}
+
+/**
+ * By default we will retrieve the challenge only if the response status code was 401,
+ * and if the response contained the header "WWW-Authenticate" with a non-empty value.
+ */
+function defaultGetChallenge(response: PipelineResponse): string | undefined {
+  const challenges = response.headers.get("WWW-Authenticate");
+  if (response.status === 401 && challenges) {
+    return challenges;
+  }
+  return;
+}
+
+/**
+ * Allows processing authentication challenges.
+ */
+export function challengeAuthenticationPolicy(
+  options: ChallengeAuthenticationPolicyOptions
+): PipelinePolicy {
+  const {
+    prepareRequest,
+    getChallenge = defaultGetChallenge,
+    processChallenge,
+    authenticationContext
+  } = options;
+
+  return {
+    name: challengeAuthenticationPolicyName,
+    async sendRequest(request: PipelineRequest, next: SendRequest): Promise<PipelineResponse> {
+      if (prepareRequest) {
+        await prepareRequest(request);
+      }
+      const response = await next(request);
+      const challenge = getChallenge(response);
+      if (
+        challenge &&
+        processChallenge &&
+        (await processChallenge(challenge, authenticationContext))
+      ) {
+        return next(request);
+      }
+      return response;
+    }
+  };
+}

sdk/core/core-https/src/util/parseCAEChallenges.ts

@@ -0,0 +1,38 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+/**
+ * parseCAEChallenges Parses multiple challenges into an array of objects.
+ * Allows users to specify the challenge type through the TChallenge type parameter.
+ */
+export function parseCAEChallenges<TChallenge>(challenges: string): TChallenge[] {
+  if (!challenges) return [{} as TChallenge];
+
+  // Parses a `key="value"` string into an object with { key: "key", value: "value" }
+  const parseKeyValue = (keyValue: string): { key: string; value: string } =>
+    (keyValue.match(/(?<key>\w+(?==))="(?<value>[^"]*)"/) as any)?.groups || {};
+
+  // Receives an array of `key="value"` strings
+  // And produces an object with properties based on those keys and values.
+  const groupKeyValues = (keyValues: string[]): TChallenge =>
+    keyValues.reduce((parsedChallenge, keyValue) => {
+      const { key, value } = parseKeyValue(keyValue);
+      if (!key) {
+        return parsedChallenge;
+      }
+      return {
+        ...parsedChallenge,
+        [key]: value || ""
+      };
+    }, {}) as TChallenge;
+
+  // Splits a string challenge composed of key="value" elements separated by comma
+  // into an array of `key="value"` strings.
+  const separateKeyValues = (challenge: string): string[] =>
+    `${challenge}, `.match(/(\w+="[^"]*"(?=, ))/g) || [];
+
+  // Each set of challenges will be separated by "Bearer ".
+  const bearerSeparated = challenges.split("Bearer").filter((x) => x);
+
+  return bearerSeparated.map((challenge) => groupKeyValues(separateKeyValues(challenge)));
+}

sdk/core/core-https/test/bearerTokenAuthenticationPolicy.spec.ts

@@ -41,7 +41,8 @@ describe("BearerTokenAuthenticationPolicy", function() {
     assert(
       fakeGetToken.calledWith(tokenScopes, {
         abortSignal: undefined,
-        tracingOptions: { spanOptions: undefined }
+        tracingOptions: { spanOptions: undefined },
+        claims: undefined
       }),
       "fakeGetToken called incorrectly."
     );