@azure/msal-common 16.11.3 → 16.13.0

package/src/crypto/ICrypto.ts

@@ -8,7 +8,7 @@ import {
     createClientAuthError,
 } from "../error/ClientAuthError.js";
 import type { BaseAuthRequest } from "../request/BaseAuthRequest.js";
-import type { ShrOptions, SignedHttpRequest } from "./SignedHttpRequest.js";
+import type { JoseHeader } from "./JoseHeader.js";
 
 /**
  * PKCE code verifier and challenge pair used by authorization code flows.
@@ -35,9 +35,11 @@ export type SignedHttpRequestParameters = Pick<
 
 /**
  * Shared JOSE algorithm literals used by MSAL package internals.
+ * @internal
  */
 export const JsonWebTokenAlgorithms = {
     ES256: "ES256",
+    RS256: "RS256",
 } as const;
 /**
  * Interface for crypto functions used by library
@@ -67,13 +69,6 @@ export interface ICrypto {
      * @returns Base64Url encoded public key
      */
     encodeKid(inputKid: string): string;
-    /**
-     * Generates an JWK RSA S256 Thumbprint
-     * @param request
-     */
-    getPublicKeyThumbprint(
-        request: SignedHttpRequestParameters
-    ): Promise<string>;
     /**
      * Removes cryptographic keypair from key store matching the keyId passed in
      * @param kid
@@ -86,14 +81,18 @@ export interface ICrypto {
      */
     clearKeystore(correlationId: string): Promise<boolean>;
     /**
-     * Returns a signed proof-of-possession token with a given acces token that contains a cnf claim with the required kid.
-     * @param accessToken
+     * Signs a compact JWT with the token-binding key identified by kid.
+     * @internal
+     * @param header
+     * @param payload
+     * @param kid
+     * @param correlationId
      */
-    signJwt(
-        payload: SignedHttpRequest,
+    signTokenBindingJwt(
+        header: JoseHeader,
+        payload: object,
         kid: string,
-        shrOptions?: ShrOptions,
-        correlationId?: string
+        correlationId: string
     ): Promise<string>;
     /**
      * Returns the SHA-256 hash of an input string
@@ -137,28 +136,34 @@ export const DEFAULT_CRYPTO_IMPLEMENTATION: ICrypto = {
             ""
         );
     },
-    async getPublicKeyThumbprint(): Promise<string> {
-        throw createClientAuthError(
-            ClientAuthErrorCodes.methodNotImplemented,
-            ""
-        );
-    },
-    async removeTokenBindingKey(): Promise<void> {
+    async removeTokenBindingKey(
+        kid: string,
+        correlationId: string
+    ): Promise<void> {
+        void kid;
         throw createClientAuthError(
             ClientAuthErrorCodes.methodNotImplemented,
-            ""
+            correlationId
         );
     },
-    async clearKeystore(): Promise<boolean> {
+    async clearKeystore(correlationId: string): Promise<boolean> {
         throw createClientAuthError(
             ClientAuthErrorCodes.methodNotImplemented,
-            ""
+            correlationId
         );
     },
-    async signJwt(): Promise<string> {
+    async signTokenBindingJwt(
+        header: JoseHeader,
+        payload: object,
+        kid: string,
+        correlationId: string
+    ): Promise<string> {
+        void header;
+        void payload;
+        void kid;
         throw createClientAuthError(
             ClientAuthErrorCodes.methodNotImplemented,
-            ""
+            correlationId
         );
     },
     async hashString(): Promise<string> {

package/src/crypto/ITokenBindingKeyManager.ts

@@ -0,0 +1,84 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import {
+    ClientAuthErrorCodes,
+    createClientAuthError,
+} from "../error/ClientAuthError.js";
+
+/**
+ * Parameters used by token-binding key managers to provision browser-managed
+ * token-binding keys. Callers own the protocol policy (key type and JOSE
+ * algorithm); implementations generate, store, retrieve, and use the requested
+ * key material by key identifier.
+ */
+export type TokenBindingKeyProvisioningParameters = {
+    tokenBindingKeyType: string;
+    tokenBindingKeyAlgorithm: string;
+    correlationId: string;
+};
+
+/**
+ * Internal key lifecycle abstraction for browser token-binding keys.
+ * @internal
+ */
+export interface ITokenBindingKeyManager {
+    /**
+     * Provisions a token-binding key and returns the key identifier.
+     * @param request - Key provisioning policy.
+     */
+    provisionTokenBindingKey(
+        request: TokenBindingKeyProvisioningParameters
+    ): Promise<string>;
+    /**
+     * Removes a token-binding key by identifier.
+     * @param kid - Token-binding key identifier.
+     * @param correlationId - Request correlation identifier.
+     */
+    removeTokenBindingKey(kid: string, correlationId: string): Promise<void>;
+    /**
+     * Gets a token-binding public key as a JWK by identifier.
+     * @param kid - Token-binding key identifier.
+     * @param correlationId - Request correlation identifier.
+     */
+    getTokenBindingPublicKeyJwk(
+        kid: string,
+        correlationId: string
+    ): Promise<JsonWebKey>;
+}
+
+/**
+ * Default token-binding key manager used when a platform-specific implementation
+ * has not been provided.
+ * @internal
+ */
+export const DEFAULT_TOKEN_BINDING_KEY_MANAGER: ITokenBindingKeyManager = {
+    async provisionTokenBindingKey(
+        request: TokenBindingKeyProvisioningParameters
+    ): Promise<string> {
+        throw createClientAuthError(
+            ClientAuthErrorCodes.methodNotImplemented,
+            request.correlationId
+        );
+    },
+    async removeTokenBindingKey(
+        _kid: string,
+        correlationId: string
+    ): Promise<void> {
+        throw createClientAuthError(
+            ClientAuthErrorCodes.methodNotImplemented,
+            correlationId
+        );
+    },
+    async getTokenBindingPublicKeyJwk(
+        _kid: string,
+        correlationId: string
+    ): Promise<JsonWebKey> {
+        throw createClientAuthError(
+            ClientAuthErrorCodes.methodNotImplemented,
+            correlationId
+        );
+    },
+};

package/src/crypto/JoseHeader.ts

@@ -7,40 +7,57 @@ import {
     JoseHeaderErrorCodes,
     createJoseHeaderError,
 } from "../error/JoseHeaderError.js";
+import { isPlainObject } from "../utils/ObjectUtils.js";
 import { JsonWebTokenTypes } from "../utils/Constants.js";
 
 export type JoseHeaderOptions = {
     typ?: JsonWebTokenTypes;
     alg?: string;
     kid?: string;
+    jwk?: JsonWebKey;
 };
 
 /** @internal */
 export class JoseHeader {
     public typ?: JsonWebTokenTypes;
-    public alg?: string;
+    public alg: string;
     public kid?: string;
+    public jwk?: JsonWebKey;
+
+    constructor(
+        options: JoseHeaderOptions & { alg: string },
+        correlationId: string
+    ) {
+        if (typeof options.alg !== "string" || !options.alg) {
+            throw createJoseHeaderError(
+                JoseHeaderErrorCodes.missingAlgError,
+                correlationId
+            );
+        }
 
-    constructor(options: JoseHeaderOptions) {
         this.typ = options.typ;
         this.alg = options.alg;
         this.kid = options.kid;
+        this.jwk = options.jwk;
     }
 
     /**
      * Builds SignedHttpRequest formatted JOSE Header from the
-     * JOSE Header options provided or previously set on the object and returns
-     * the stringified header object.
+     * JOSE Header options provided or previously set on the object.
      * Throws if keyId or algorithm aren't provided since they are required for Access Token Binding.
      * @param shrHeaderOptions
+     * @param correlationId
      * @returns
      */
-    static getShrHeaderString(shrHeaderOptions: JoseHeaderOptions): string {
+    static getShrHeader(
+        shrHeaderOptions: JoseHeaderOptions,
+        correlationId: string
+    ): JoseHeader {
         // KeyID is required on the SHR header
         if (!shrHeaderOptions.kid) {
             throw createJoseHeaderError(
                 JoseHeaderErrorCodes.missingKidError,
-                ""
+                correlationId
             );
         }
 
@@ -48,17 +65,60 @@ export class JoseHeader {
         if (!shrHeaderOptions.alg) {
             throw createJoseHeaderError(
                 JoseHeaderErrorCodes.missingAlgError,
-                ""
+                correlationId
+            );
+        }
+
+        return new JoseHeader(
+            {
+                // Access Token PoP headers must have type pop, but the type header can be overriden for special cases
+                typ: shrHeaderOptions.typ || JsonWebTokenTypes.Pop,
+                kid: shrHeaderOptions.kid,
+                alg: shrHeaderOptions.alg,
+            },
+            correlationId
+        );
+    }
+
+    /**
+     * Builds a DPoP formatted JOSE Header from the JOSE Header options provided.
+     * Throws if public JWK or algorithm aren't provided since they are required for DPoP.
+     * @param dpopHeaderOptions
+     * @param correlationId
+     * @returns
+     */
+    static getDpopHeader(
+        dpopHeaderOptions: JoseHeaderOptions,
+        correlationId: string
+    ): JoseHeader {
+        if (!isPlainObject(dpopHeaderOptions.jwk)) {
+            throw createJoseHeaderError(
+                JoseHeaderErrorCodes.missingJwkError,
+                correlationId
+            );
+        }
+
+        if (!dpopHeaderOptions.alg) {
+            throw createJoseHeaderError(
+                JoseHeaderErrorCodes.missingAlgError,
+                correlationId
             );
         }
 
-        const shrHeader = new JoseHeader({
-            // Access Token PoP headers must have type pop, but the type header can be overriden for special cases
-            typ: shrHeaderOptions.typ || JsonWebTokenTypes.Pop,
-            kid: shrHeaderOptions.kid,
-            alg: shrHeaderOptions.alg,
-        });
+        if (Object.keys(dpopHeaderOptions.jwk).length === 0) {
+            throw createJoseHeaderError(
+                JoseHeaderErrorCodes.invalidJwkError,
+                correlationId
+            );
+        }
 
-        return JSON.stringify(shrHeader);
+        return new JoseHeader(
+            {
+                typ: JsonWebTokenTypes.Dpop,
+                alg: dpopHeaderOptions.alg,
+                jwk: dpopHeaderOptions.jwk,
+            },
+            correlationId
+        );
     }
 }

package/src/crypto/PopTokenGenerator.ts

@@ -3,13 +3,20 @@
  * Licensed under the MIT License.
  */
 
-import { ICrypto, SignedHttpRequestParameters } from "./ICrypto.js";
+import {
+    ICrypto,
+    JsonWebTokenAlgorithms,
+    SignedHttpRequestParameters,
+} from "./ICrypto.js";
 import * as TimeUtils from "../utils/TimeUtils.js";
 import { UrlString } from "../url/UrlString.js";
 import { IPerformanceClient } from "../telemetry/performance/IPerformanceClient.js";
 import * as PerformanceEvents from "../telemetry/performance/PerformanceEvents.js";
 import { invokeAsync } from "../utils/FunctionWrappers.js";
 import { Logger } from "../logger/Logger.js";
+import { JoseHeader } from "./JoseHeader.js";
+import { SignedHttpRequest } from "./SignedHttpRequest.js";
+import { ITokenBindingKeyManager } from "./ITokenBindingKeyManager.js";
 
 /**
  * See eSTS docs for more info.
@@ -34,13 +41,22 @@ const KeyLocation = {
 } as const;
 export type KeyLocation = (typeof KeyLocation)[keyof typeof KeyLocation];
 
+const SHR_TOKEN_BINDING_KEY_TYPE = "shr";
+const SHR_TOKEN_BINDING_KEY_ALGORITHM = JsonWebTokenAlgorithms.RS256;
+
 /** @internal */
 export class PopTokenGenerator {
     private cryptoUtils: ICrypto;
+    private tokenBindingKeyManager: ITokenBindingKeyManager;
     private performanceClient: IPerformanceClient;
 
-    constructor(cryptoUtils: ICrypto, performanceClient: IPerformanceClient) {
+    constructor(
+        cryptoUtils: ICrypto,
+        tokenBindingKeyManager: ITokenBindingKeyManager,
+        performanceClient: IPerformanceClient
+    ) {
         this.cryptoUtils = cryptoUtils;
+        this.tokenBindingKeyManager = tokenBindingKeyManager;
         this.performanceClient = performanceClient;
     }
 
@@ -77,9 +93,12 @@ export class PopTokenGenerator {
      * @returns
      */
     async generateKid(request: SignedHttpRequestParameters): Promise<ReqCnf> {
-        const kidThumbprint = await this.cryptoUtils.getPublicKeyThumbprint(
-            request
-        );
+        const kidThumbprint =
+            await this.tokenBindingKeyManager.provisionTokenBindingKey({
+                correlationId: request.correlationId,
+                tokenBindingKeyType: SHR_TOKEN_BINDING_KEY_TYPE,
+                tokenBindingKeyAlgorithm: SHR_TOKEN_BINDING_KEY_ALGORITHM,
+            });
 
         return {
             kid: kidThumbprint,
@@ -128,22 +147,47 @@ export class PopTokenGenerator {
             ? new UrlString(resourceRequestUri, request.correlationId)
             : undefined;
         const resourceUrlComponents = resourceUrlString?.getUrlComponents();
-        return this.cryptoUtils.signJwt(
+        const publicKeyJwk =
+            await this.tokenBindingKeyManager.getTokenBindingPublicKeyJwk(
+                keyId,
+                request.correlationId
+            );
+        const encodedKeyIdThumbprint = this.cryptoUtils.base64UrlEncode(
+            JSON.stringify({ kid: keyId })
+        );
+        const shrAlgorithm =
+            shrOptions?.header?.alg ||
+            publicKeyJwk.alg ||
+            SHR_TOKEN_BINDING_KEY_ALGORITHM;
+        const shrHeader = JoseHeader.getShrHeader(
             {
-                at: payload,
-                ts: TimeUtils.nowSeconds(),
-                m: resourceRequestMethod?.toUpperCase(),
-                u: resourceUrlComponents?.HostNameAndPort,
-                nonce: shrNonce || this.cryptoUtils.createNewGuid(),
-                p: resourceUrlComponents?.AbsolutePath,
-                q: resourceUrlComponents?.QueryString
-                    ? [[], resourceUrlComponents.QueryString]
-                    : undefined,
-                client_claims: shrClaims || undefined,
-                ...claims,
+                ...shrOptions?.header,
+                alg: shrAlgorithm,
+                kid: encodedKeyIdThumbprint,
             },
+            request.correlationId
+        );
+        const shrPayload: SignedHttpRequest = {
+            at: payload,
+            ts: TimeUtils.nowSeconds(),
+            m: resourceRequestMethod?.toUpperCase(),
+            u: resourceUrlComponents?.HostNameAndPort,
+            nonce: shrNonce || this.cryptoUtils.createNewGuid(),
+            p: resourceUrlComponents?.AbsolutePath,
+            q: resourceUrlComponents?.QueryString
+                ? [[], resourceUrlComponents.QueryString]
+                : undefined,
+            client_claims: shrClaims || undefined,
+            ...claims,
+            cnf: {
+                jwk: publicKeyJwk,
+            },
+        };
+
+        return this.cryptoUtils.signTokenBindingJwt(
+            shrHeader,
+            shrPayload,
             keyId,
-            shrOptions,
             request.correlationId
         );
     }

package/src/error/ClientConfigurationErrorCodes.ts

@@ -19,6 +19,8 @@ export const invalidAuthorityMetadata = "invalid_authority_metadata";
 export const untrustedAuthority = "untrusted_authority";
 export const missingSshJwk = "missing_ssh_jwk";
 export const missingSshKid = "missing_ssh_kid";
+export const unsupportedAuthenticationScheme =
+    "unsupported_authentication_scheme";
 export const missingNonceAuthenticationHeader =
     "missing_nonce_authentication_header";
 export const invalidAuthenticationHeader = "invalid_authentication_header";

package/src/error/JoseHeaderErrorCodes.ts

@@ -5,3 +5,5 @@
 
 export const missingKidError = "missing_kid_error";
 export const missingAlgError = "missing_alg_error";
+export const missingJwkError = "missing_jwk_error";
+export const invalidJwkError = "invalid_jwk_error";

package/src/exports-common.ts

@@ -104,7 +104,13 @@ export {
     PkceCodes,
     DEFAULT_CRYPTO_IMPLEMENTATION,
     SignedHttpRequestParameters,
+    JsonWebTokenAlgorithms,
 } from "./crypto/ICrypto.js";
+export {
+    ITokenBindingKeyManager,
+    DEFAULT_TOKEN_BINDING_KEY_MANAGER,
+    TokenBindingKeyProvisioningParameters,
+} from "./crypto/ITokenBindingKeyManager.js";
 
 export * as AuthorizeProtocol from "./protocol/Authorize.js";
 export * as TokenProtocol from "./protocol/Token.js";
@@ -127,6 +133,7 @@ export { AuthorizationCodePayload } from "./response/AuthorizationCodePayload.js
 export { AuthorizeResponse } from "./response/AuthorizeResponse.js";
 export { ServerAuthorizationTokenResponse } from "./response/ServerAuthorizationTokenResponse.js";
 export {
+    GenerateAuthenticationResultOptions,
     ResponseHandler,
     buildAccountToCache,
 } from "./response/ResponseHandler.js";

package/src/network/RequestThumbprint.ts

@@ -6,6 +6,7 @@
 import { ShrOptions } from "../crypto/SignedHttpRequest.js";
 import { BaseAuthRequest } from "../request/BaseAuthRequest.js";
 import { AuthenticationScheme } from "../utils/Constants.js";
+import * as CacheHelpers from "../cache/utils/CacheHelpers.js";
 
 /**
  * Type representing a unique request thumbprint.
@@ -24,6 +25,7 @@ export type RequestThumbprint = {
     shrOptions?: ShrOptions;
     embeddedClientId?: string;
     resource?: string;
+    attributeTokens?: string;
 };
 
 export function getRequestThumbprint(
@@ -45,5 +47,8 @@ export function getRequestThumbprint(
         embeddedClientId:
             request.embeddedClientId || request.extraParameters?.clientId,
         resource: request.resource,
+        attributeTokens: CacheHelpers.serializeAttributeTokens(
+            request.attributeTokens
+        ),
     };
 }

package/src/packageMetadata.ts

@@ -1,3 +1,3 @@
 /* eslint-disable header/header */
 export const name = "@azure/msal-common";
-export const version = "16.11.3";
+export const version = "16.13.0";

package/src/request/BaseAuthRequest.ts

@@ -111,6 +111,10 @@ export type BaseAuthRequest = {
      * String to string map of custom parameters added to outgoing token service requests.
      */
     extraParameters?: StringDict;
+    /**
+     * Optional caller-provided attribute tokens (opaque assertions from external Attribute Authorities).
+     */
+    attributeTokens?: Array<string>;
 };
 
 /**