@azure/msal-common 16.12.0 → 16.13.0

package/package.json

@@ -10,7 +10,7 @@
     "type": "git",
     "url": "https://github.com/AzureAD/microsoft-authentication-library-for-js.git"
   },
-  "version": "16.12.0",
+  "version": "16.13.0",
   "description": "Microsoft Authentication Library for js",
   "keywords": [
     "implicit",

package/src/authority/AuthorityMetadata.ts

@@ -19,10 +19,7 @@ type RawMetadata = {
 // Build endpoint metadata dynamically to avoid string duplication
 const endpointHosts: Array<{ host: string; issuerHost?: string }> = [
     { host: "login.microsoftonline.com" },
-    {
-        host: "login.chinacloudapi.cn",
-        issuerHost: "login.partner.microsoftonline.cn", // Issuer differs
-    },
+    { host: "login.partner.microsoftonline.cn" },
     { host: "login.microsoftonline.us" },
     { host: "login.sovcloud-identity.fr" },
     { host: "login.sovcloud-identity.de" },

package/src/cache/CacheManager.ts

@@ -909,19 +909,9 @@ export abstract class CacheManager implements ICacheManager {
             entity.credentialType ===
             Constants.CredentialType.ACCESS_TOKEN_WITH_AUTH_SCHEME
         ) {
-            if (
-                !!filter.tokenType &&
-                !this.matchTokenType(entity, filter.tokenType)
-            ) {
+            if (!this.matchAccessTokenWithAuthScheme(entity, filter)) {
                 return false;
             }
-
-            // KeyId (sshKid) in request must match cached SSH certificate keyId because SSH cert is bound to a specific key
-            if (filter.tokenType === Constants.AuthenticationScheme.SSH) {
-                if (filter.keyId && !this.matchKeyId(entity, filter.keyId)) {
-                    return false;
-                }
-            }
         }
 
         // Additional cache key components matching (bidirectional isolation)
@@ -1387,7 +1377,10 @@ export abstract class CacheManager implements ICacheManager {
             realm: targetRealm || account.tenantId,
             target: scopes,
             tokenType: authScheme,
-            keyId: request.sshKid,
+            keyId:
+                authScheme === Constants.AuthenticationScheme.SSH
+                    ? request.sshKid
+                    : undefined,
             additionalCacheKeyComponents: additionalCacheKeyComponents,
         };
 
@@ -1970,7 +1963,47 @@ export abstract class CacheManager implements ICacheManager {
         entity: CredentialEntity,
         tokenType: Constants.AuthenticationScheme
     ): boolean {
-        return !!(entity.tokenType && entity.tokenType === tokenType);
+        return !!(
+            entity.tokenType &&
+            entity.tokenType.toLowerCase() === tokenType.toLowerCase()
+        );
+    }
+
+    private matchAccessTokenWithAuthScheme(
+        entity: CredentialEntity,
+        filter: CredentialFilter
+    ): boolean {
+        const normalizedFilterTokenType = (
+            filter.tokenType as string | undefined
+        )?.toLowerCase();
+
+        if (
+            !!filter.tokenType &&
+            !this.matchTokenType(entity, filter.tokenType)
+        ) {
+            return false;
+        }
+
+        switch (normalizedFilterTokenType) {
+            case "dpop":
+                return this.matchKeyBoundAccessToken(entity, filter, true);
+            case Constants.AuthenticationScheme.SSH:
+                return this.matchKeyBoundAccessToken(entity, filter, false);
+            default:
+                return true;
+        }
+    }
+
+    private matchKeyBoundAccessToken(
+        entity: CredentialEntity,
+        filter: CredentialFilter,
+        requireKeyId: boolean
+    ): boolean {
+        if (!filter.keyId) {
+            return !requireKeyId;
+        }
+
+        return this.matchKeyId(entity, filter.keyId);
     }
 
     /**

package/src/cache/utils/CacheHelpers.ts

@@ -98,6 +98,7 @@ export function createAccessTokenEntity(
         atEntity.refreshOn = refreshOn.toString();
     }
 
+    const normalizedTokenType = atEntity.tokenType?.toLowerCase();
     /*
      * Create Access Token With Auth Scheme instead of regular access token
      * Cast to lower to handle "bearer" from ADFS
@@ -108,7 +109,7 @@ export function createAccessTokenEntity(
     ) {
         atEntity.credentialType =
             Constants.CredentialType.ACCESS_TOKEN_WITH_AUTH_SCHEME;
-        switch (atEntity.tokenType) {
+        switch (normalizedTokenType) {
             case Constants.AuthenticationScheme.POP:
                 // Make sure keyId is present and add it to credential
                 const tokenClaims: TokenClaims | null = extractTokenClaims(
@@ -124,6 +125,15 @@ export function createAccessTokenEntity(
                 }
                 atEntity.keyId = tokenClaims.cnf.kid;
                 break;
+            case "dpop":
+                if (!keyId) {
+                    throw createClientAuthError(
+                        ClientAuthErrorCodes.keyIdMissing,
+                        correlationId
+                    );
+                }
+                atEntity.keyId = keyId;
+                break;
             case Constants.AuthenticationScheme.SSH:
                 atEntity.keyId = keyId;
         }

package/src/client/AuthorizationCodeClient.ts

@@ -168,7 +168,8 @@ export class AuthorizationCodeClient {
             this.logger,
             this.performanceClient,
             this.config.serializableCache,
-            this.config.persistencePlugin
+            this.config.persistencePlugin,
+            this.config.tokenBindingKeyManager
         );
 
         // Validate response. This function throws a server error if an error is returned by the server.
@@ -422,6 +423,7 @@ export class AuthorizationCodeClient {
         ) {
             const popTokenGenerator = new PopTokenGenerator(
                 this.cryptoUtils,
+                this.config.tokenBindingKeyManager,
                 this.performanceClient
             );
 

package/src/client/RefreshTokenClient.ts

@@ -139,7 +139,8 @@ export class RefreshTokenClient {
             this.logger,
             this.performanceClient,
             this.config.serializableCache,
-            this.config.persistencePlugin
+            this.config.persistencePlugin,
+            this.config.tokenBindingKeyManager
         );
         responseHandler.validateTokenResponse(
             response.body,
@@ -488,6 +489,7 @@ export class RefreshTokenClient {
         ) {
             const popTokenGenerator = new PopTokenGenerator(
                 this.cryptoUtils,
+                this.config.tokenBindingKeyManager,
                 this.performanceClient
             );
 

package/src/client/SilentFlowClient.ts

@@ -263,7 +263,10 @@ export class SilentFlowClient {
             true,
             request,
             this.performanceClient,
-            idTokenClaims
+            {
+                idTokenClaims,
+                tokenBindingKeyManager: this.config.tokenBindingKeyManager,
+            }
         );
     }
 }

package/src/config/ClientConfiguration.ts

@@ -5,6 +5,10 @@
 
 import { INetworkModule } from "../network/INetworkModule.js";
 import { DEFAULT_CRYPTO_IMPLEMENTATION, ICrypto } from "../crypto/ICrypto.js";
+import {
+    DEFAULT_TOKEN_BINDING_KEY_MANAGER,
+    ITokenBindingKeyManager,
+} from "../crypto/ITokenBindingKeyManager.js";
 import { ILoggerCallback, Logger, LogLevel } from "../logger/Logger.js";
 import {
     DEFAULT_COMMON_TENANT,
@@ -32,6 +36,7 @@ import { StubPerformanceClient } from "../telemetry/performance/StubPerformanceC
  * This object allows you to configure important elements of MSAL functionality:
  * - authOptions                - Authentication for application
  * - cryptoInterface            - Implementation of crypto functions
+ * - tokenBindingKeyManager     - Implementation of token-binding key lifecycle functions
  * - libraryInfo                - Library metadata
  * - telemetry                  - Telemetry options and data
  * - loggerOptions              - Logging for application
@@ -48,6 +53,7 @@ export type ClientConfiguration = {
     storageInterface?: CacheManager;
     networkInterface?: INetworkModule;
     cryptoInterface?: ICrypto;
+    tokenBindingKeyManager?: ITokenBindingKeyManager;
     clientCredentials?: ClientCredentials;
     libraryInfo?: LibraryInfo;
     telemetry?: TelemetryOptions;
@@ -66,6 +72,7 @@ export type CommonClientConfiguration = {
     storageInterface: CacheManager;
     networkInterface: INetworkModule;
     cryptoInterface: Required<ICrypto>;
+    tokenBindingKeyManager: ITokenBindingKeyManager;
     libraryInfo: LibraryInfo;
     telemetry: Required<TelemetryOptions>;
     serverTelemetryManager: ServerTelemetryManager | null;
@@ -226,6 +233,7 @@ export function buildClientConfiguration({
     storageInterface: storageImplementation,
     networkInterface: networkImplementation,
     cryptoInterface: cryptoImplementation,
+    tokenBindingKeyManager: tokenBindingKeyManager,
     clientCredentials: clientCredentials,
     libraryInfo: libraryInfo,
     telemetry: telemetry,
@@ -253,6 +261,8 @@ export function buildClientConfiguration({
         networkInterface:
             networkImplementation || DEFAULT_NETWORK_IMPLEMENTATION,
         cryptoInterface: cryptoImplementation || DEFAULT_CRYPTO_IMPLEMENTATION,
+        tokenBindingKeyManager:
+            tokenBindingKeyManager || DEFAULT_TOKEN_BINDING_KEY_MANAGER,
         clientCredentials: clientCredentials || DEFAULT_CLIENT_CREDENTIALS,
         libraryInfo: { ...DEFAULT_LIBRARY_INFO, ...libraryInfo },
         telemetry: { ...DEFAULT_TELEMETRY_OPTIONS, ...telemetry },

package/src/crypto/DpopProofGenerator.ts

@@ -4,11 +4,13 @@
  */
 
 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";
 
 /**
  * RFC 9449 DPoP proof JWT payload claims.
@@ -44,51 +46,21 @@ export type DpopResourceProofParams = {
     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;
-};
-
 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: JsonWebKey,
+    correlationId: string
+): JoseHeader {
+    return JoseHeader.getDpopHeader(
+        {
+            alg: DPOP_JWT_HEADER_ALGORITHM,
+            jwk: publicJwk,
+        },
+        correlationId
+    );
 }
 
 function normalizeHtm(htm: string, correlationId: string): string {
@@ -149,9 +121,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,
+        });
     }
 
     /**
@@ -180,12 +169,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
         );
     }
@@ -218,30 +208,33 @@ export class DpopProofGenerator {
      * Builds and signs a compact DPoP proof JWT for a resource request.
      */
     async generateResourceProof(
-        params: DpopResourceProofParams & DpopProofGenerationParams,
+        params: DpopResourceProofParams,
+        keyId: string,
         correlationId: string = ""
     ): Promise<string> {
         return this.generateProof(
             this.buildResourceProofClaims(params, correlationId),
-            params,
+            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 publicJwk =
+            await this.tokenBindingKeyManager.getTokenBindingPublicKeyJwk(
+                keyId,
+                correlationId
+            );
+
+        return this.cryptoUtils.signTokenBindingJwt(
+            buildProofHeader(publicJwk, correlationId),
+            claims,
+            keyId,
+            correlationId
         );
-        const signingInput = `${encodedHeader}.${encodedClaims}`;
-        const signature = await params.signer.sign(signingInput, correlationId);
-
-        return `${signingInput}.${signature}`;
     }
 }

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
+        );
+    },
+};