@azure/msal-common 16.12.0 → 16.14.0

package/src/crypto/DpopProofGenerator.ts

@@ -4,11 +4,14 @@
  */
 
 import { ICrypto, JsonWebTokenAlgorithms } from "./ICrypto.js";
+import { ITokenBindingKeyManager } from "./ITokenBindingKeyManager.js";
 import * as TimeUtils from "../utils/TimeUtils.js";
 import {
     createClientConfigurationError,
     ClientConfigurationErrorCodes,
 } from "../error/ClientConfigurationError.js";
+import { JoseHeader } from "./JoseHeader.js";
+import type { PublicJsonWebKey } from "./PublicJsonWebKey.js";
 
 /**
  * RFC 9449 DPoP proof JWT payload claims.
@@ -38,57 +41,34 @@ export type DpopTokenProofParams = {
  * @internal
  */
 export type DpopResourceProofParams = {
-    resourceUrl: string;
+    htu: string;
     htm: string;
     ath: string;
     nonce?: string;
 };
 
-/**
- * Public JWK embedded in the DPoP proof header.
- * @internal
- */
-export type DpopPublicJwk = Record<string, unknown>;
-
-/**
- * RFC 9449 DPoP proof JWT header.
- * @internal
- */
-export type DpopProofHeader = {
-    typ: typeof DPOP_JWT_HEADER_TYPE;
-    alg: string;
-    jwk: DpopPublicJwk;
-};
-
-/**
- * Signs the ASCII DPoP JWT signing input with the declared JOSE alg
- * and returns a base64url-encoded signature.
- * @internal
- */
-export type DpopProofSigner = {
-    alg: string;
-    sign: (signingInput: string, correlationId: string) => Promise<string>;
-};
-
-/**
- * Parameters shared by token and resource DPoP proof generation.
- * @internal
- */
-export type DpopProofGenerationParams = {
-    publicJwk: DpopPublicJwk;
-    signer: DpopProofSigner;
+export type GenerateDpopResourceProofParams = {
+    htu?: string;
+    htm?: string;
+    nonce?: string;
+    accessToken: string;
 };
 
 const DPOP_HTM_REGEX = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
-export const DPOP_JWT_HEADER_TYPE = "dpop+jwt";
-export const DPOP_JWT_HEADER_ALGORITHM = JsonWebTokenAlgorithms.ES256;
-
-function buildProofHeader(params: DpopProofGenerationParams): DpopProofHeader {
-    return {
-        typ: DPOP_JWT_HEADER_TYPE,
-        alg: params.signer.alg,
-        jwk: params.publicJwk,
-    };
+const DPOP_TOKEN_BINDING_KEY_TYPE = "dpop";
+const DPOP_JWT_HEADER_ALGORITHM = JsonWebTokenAlgorithms.ES256;
+
+function buildProofHeader(
+    publicJwk: PublicJsonWebKey,
+    correlationId: string
+): JoseHeader {
+    return JoseHeader.getDpopHeader(
+        {
+            alg: DPOP_JWT_HEADER_ALGORITHM,
+            jwk: publicJwk,
+        },
+        correlationId
+    );
 }
 
 function normalizeHtm(htm: string, correlationId: string): string {
@@ -136,6 +116,18 @@ function normalizeHtu(url: string, correlationId: string): string {
     return parsedUrl.href;
 }
 
+function validateDpopNonce(
+    nonce: string | undefined,
+    correlationId: string
+): void {
+    if (nonce !== undefined && nonce.trim().length === 0) {
+        throw createClientConfigurationError(
+            ClientConfigurationErrorCodes.invalidDpopNonce,
+            correlationId
+        );
+    }
+}
+
 /**
  * Builds RFC 9449 DPoP proof JWT payloads for token-endpoint and
  * resource-endpoint proof bindings.
@@ -149,9 +141,26 @@ function normalizeHtu(url: string, correlationId: string): string {
  */
 export class DpopProofGenerator {
     private cryptoUtils: ICrypto;
+    private tokenBindingKeyManager: ITokenBindingKeyManager;
 
-    constructor(cryptoUtils: ICrypto) {
+    constructor(
+        cryptoUtils: ICrypto,
+        tokenBindingKeyManager: ITokenBindingKeyManager
+    ) {
         this.cryptoUtils = cryptoUtils;
+        this.tokenBindingKeyManager = tokenBindingKeyManager;
+    }
+
+    /**
+     * Provisions a fresh DPoP key and returns the RFC 7638 JWK thumbprint used
+     * as `dpop_jkt`.
+     */
+    async generateJkt(correlationId: string = ""): Promise<string> {
+        return this.tokenBindingKeyManager.provisionTokenBindingKey({
+            tokenBindingKeyType: DPOP_TOKEN_BINDING_KEY_TYPE,
+            tokenBindingKeyAlgorithm: DPOP_JWT_HEADER_ALGORITHM,
+            correlationId,
+        });
     }
 
     /**
@@ -164,6 +173,7 @@ export class DpopProofGenerator {
         params: DpopTokenProofParams,
         correlationId: string = ""
     ): DpopProofClaims {
+        validateDpopNonce(params.nonce, correlationId);
         const claims: DpopProofClaims = {
             jti: this.cryptoUtils.createNewGuid(),
             htm: "POST",
@@ -180,12 +190,13 @@ export class DpopProofGenerator {
      * Builds and signs a compact DPoP proof JWT for a token-endpoint request.
      */
     async generateTokenProof(
-        params: DpopTokenProofParams & DpopProofGenerationParams,
+        params: DpopTokenProofParams,
+        keyId: string,
         correlationId: string = ""
     ): Promise<string> {
         return this.generateProof(
             this.buildTokenProofClaims(params, correlationId),
-            params,
+            keyId,
             correlationId
         );
     }
@@ -201,10 +212,11 @@ export class DpopProofGenerator {
         params: DpopResourceProofParams,
         correlationId: string = ""
     ): DpopProofClaims {
+        validateDpopNonce(params.nonce, correlationId);
         const claims: DpopProofClaims = {
             jti: this.cryptoUtils.createNewGuid(),
             htm: normalizeHtm(params.htm, correlationId),
-            htu: normalizeHtu(params.resourceUrl, correlationId),
+            htu: normalizeHtu(params.htu, correlationId),
             ath: params.ath,
             iat: TimeUtils.nowSeconds(),
         };
@@ -218,30 +230,50 @@ export class DpopProofGenerator {
      * Builds and signs a compact DPoP proof JWT for a resource request.
      */
     async generateResourceProof(
-        params: DpopResourceProofParams & DpopProofGenerationParams,
+        params: GenerateDpopResourceProofParams,
+        keyId: string,
         correlationId: string = ""
     ): Promise<string> {
+        const { htu, htm, nonce } = params;
+        if (!htu || !htm) {
+            throw createClientConfigurationError(
+                ClientConfigurationErrorCodes.dpopMissingResourceContext,
+                correlationId
+            );
+        }
+
+        const ath = await this.cryptoUtils.hashString(params.accessToken);
         return this.generateProof(
-            this.buildResourceProofClaims(params, correlationId),
-            params,
+            this.buildResourceProofClaims(
+                {
+                    htu,
+                    htm,
+                    ath,
+                    nonce,
+                },
+                correlationId
+            ),
+            keyId,
             correlationId
         );
     }
 
     private async generateProof(
         claims: DpopProofClaims,
-        params: DpopProofGenerationParams,
+        keyId: string,
         correlationId: string
     ): Promise<string> {
-        const encodedHeader = this.cryptoUtils.base64UrlEncode(
-            JSON.stringify(buildProofHeader(params))
-        );
-        const encodedClaims = this.cryptoUtils.base64UrlEncode(
-            JSON.stringify(claims)
-        );
-        const signingInput = `${encodedHeader}.${encodedClaims}`;
-        const signature = await params.signer.sign(signingInput, correlationId);
+        const publicJwk =
+            await this.tokenBindingKeyManager.getTokenBindingPublicKeyJwk(
+                keyId,
+                correlationId
+            );
 
-        return `${signingInput}.${signature}`;
+        return this.cryptoUtils.signTokenBindingJwt(
+            buildProofHeader(publicJwk, correlationId),
+            claims,
+            keyId,
+            correlationId
+        );
     }
 }

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,85 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import {
+    ClientAuthErrorCodes,
+    createClientAuthError,
+} from "../error/ClientAuthError.js";
+import type { PublicJsonWebKey } from "./PublicJsonWebKey.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<PublicJsonWebKey>;
+}
+
+/**
+ * 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<PublicJsonWebKey> {
+        throw createClientAuthError(
+            ClientAuthErrorCodes.methodNotImplemented,
+            correlationId
+        );
+    },
+};

package/src/crypto/JoseHeader.ts

@@ -7,40 +7,58 @@ import {
     JoseHeaderErrorCodes,
     createJoseHeaderError,
 } from "../error/JoseHeaderError.js";
+import { isPlainObject } from "../utils/ObjectUtils.js";
 import { JsonWebTokenTypes } from "../utils/Constants.js";
+import type { PublicJsonWebKey } from "./PublicJsonWebKey.js";
 
 export type JoseHeaderOptions = {
     typ?: JsonWebTokenTypes;
     alg?: string;
     kid?: string;
+    jwk?: PublicJsonWebKey;
 };
 
 /** @internal */
 export class JoseHeader {
     public typ?: JsonWebTokenTypes;
-    public alg?: string;
+    public alg: string;
     public kid?: string;
+    public jwk?: PublicJsonWebKey;
+
+    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 +66,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
         );
     }