Client Assertion implementation now accepts an async callback as well as a string argument

change/@azure-msal-common-d9223c68-d959-4da8-8a74-caa4f751c48a.json

@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "Client Assertion Implementation now accepts a callback instead of a string argument",
+  "packageName": "@azure/msal-common",
+  "email": "[email protected]",
+  "dependentChangeType": "patch"
+}

change/@azure-msal-node-93a9e21c-c628-4ae1-ad55-2e1217792f32.json

@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "Client Assertion Implementation now accepts a callback instead of a string argument",
+  "packageName": "@azure/msal-node",
+  "email": "[email protected]",
+  "dependentChangeType": "patch"
+}

lib/msal-common/src/account/ClientCredentials.ts

@@ -3,11 +3,20 @@
  * Licensed under the MIT License.
  */
 
+export type ClientAssertionConfig = {
+    clientId: string;
+    tokenEndpoint?: string;
+};
+
+export type ClientAssertionCallback = (
+    config: ClientAssertionConfig
+) => Promise<string>;
+
 /**
  * Client Assertion credential for Confidential Clients
  */
 export type ClientAssertion = {
-    assertion: string;
+    assertion: string | ClientAssertionCallback;
     assertionType: string;
 };
 

lib/msal-common/src/client/AuthorizationCodeClient.ts

@@ -50,6 +50,8 @@ import { RequestValidator } from "../request/RequestValidator";
 import { IPerformanceClient } from "../telemetry/performance/IPerformanceClient";
 import { PerformanceEvents } from "../telemetry/performance/PerformanceEvent";
 import { invokeAsync } from "../utils/FunctionWrappers";
+import { ClientAssertion } from "../account/ClientCredentials";
+import { getClientAssertion } from "../utils/ClientAssertionUtils";
 
 /**
  * Oauth2.0 Authorization Code client
@@ -364,9 +366,16 @@ export class AuthorizationCodeClient extends BaseClient {
         }
 
         if (this.config.clientCredentials.clientAssertion) {
-            const clientAssertion =
+            const clientAssertion: ClientAssertion =
                 this.config.clientCredentials.clientAssertion;
-            parameterBuilder.addClientAssertion(clientAssertion.assertion);
+
+            parameterBuilder.addClientAssertion(
+                await getClientAssertion(
+                    clientAssertion.assertion,
+                    this.config.authOptions.clientId,
+                    request.resourceRequestUri
+                )
+            );
             parameterBuilder.addClientAssertionType(
                 clientAssertion.assertionType
             );

lib/msal-common/src/client/RefreshTokenClient.ts

@@ -48,6 +48,8 @@ import { PerformanceEvents } from "../telemetry/performance/PerformanceEvent";
 import { IPerformanceClient } from "../telemetry/performance/IPerformanceClient";
 import { invoke, invokeAsync } from "../utils/FunctionWrappers";
 import { generateCredentialKey } from "../cache/utils/CacheHelpers";
+import { ClientAssertion } from "../account/ClientCredentials";
+import { getClientAssertion } from "../utils/ClientAssertionUtils";
 
 const DEFAULT_REFRESH_TOKEN_EXPIRATION_OFFSET_SECONDS = 300; // 5 Minutes
 
@@ -385,9 +387,16 @@ export class RefreshTokenClient extends BaseClient {
         }
 
         if (this.config.clientCredentials.clientAssertion) {
-            const clientAssertion =
+            const clientAssertion: ClientAssertion =
                 this.config.clientCredentials.clientAssertion;
-            parameterBuilder.addClientAssertion(clientAssertion.assertion);
+
+            parameterBuilder.addClientAssertion(
+                await getClientAssertion(
+                    clientAssertion.assertion,
+                    this.config.authOptions.clientId,
+                    request.resourceRequestUri
+                )
+            );
             parameterBuilder.addClientAssertionType(
                 clientAssertion.assertionType
             );

lib/msal-common/src/index.ts

@@ -133,7 +133,11 @@ export { NativeRequest } from "./request/NativeRequest";
 export { NativeSignOutRequest } from "./request/NativeSignOutRequest";
 export { RequestParameterBuilder } from "./request/RequestParameterBuilder";
 export { StoreInCache } from "./request/StoreInCache";
-export { ClientAssertion } from "./account/ClientCredentials";
+export {
+    ClientAssertion,
+    ClientAssertionConfig,
+    ClientAssertionCallback,
+} from "./account/ClientCredentials";
 // Response
 export { AzureRegion } from "./authority/AzureRegion";
 export { AzureRegionConfiguration } from "./authority/AzureRegionConfiguration";
@@ -182,6 +186,7 @@ export {
     createClientConfigurationError,
 } from "./error/ClientConfigurationError";
 // Constants and Utils
+export { getClientAssertion } from "./utils/ClientAssertionUtils";
 export {
     Constants,
     OIDC_DEFAULT_SCOPES,
@@ -218,6 +223,7 @@ export {
 } from "./utils/ProtocolUtils";
 export * as TimeUtils from "./utils/TimeUtils";
 export * as UrlUtils from "./utils/UrlUtils";
+export * as ClientAssertionUtils from "./utils/ClientAssertionUtils";
 export * from "./utils/FunctionWrappers";
 // Server Telemetry
 export { ServerTelemetryManager } from "./telemetry/server/ServerTelemetryManager";

lib/msal-common/src/utils/ClientAssertionUtils.ts

@@ -0,0 +1,25 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import {
+    ClientAssertionCallback,
+    ClientAssertionConfig,
+} from "../account/ClientCredentials";
+
+export async function getClientAssertion(
+    clientAssertion: string | ClientAssertionCallback,
+    clientId: string,
+    tokenEndpoint?: string
+): Promise<string> {
+    if (typeof clientAssertion === "string") {
+        return clientAssertion;
+    } else {
+        const config: ClientAssertionConfig = {
+            clientId: clientId,
+            tokenEndpoint: tokenEndpoint,
+        };
+        return clientAssertion(config);
+    }
+}

lib/msal-common/test/request/RequestParameterBuilder.spec.ts

@@ -23,6 +23,9 @@ import {
     ClientConfigurationErrorMessage,
     createClientConfigurationError,
 } from "../../src/error/ClientConfigurationError";
+import { ClientAssertion, ClientAssertionCallback } from "../../src";
+import { getClientAssertion } from "../../src/utils/ClientAssertionUtils";
+import { ClientAssertionConfig } from "../../src/account/ClientCredentials";
 
 describe("RequestParameterBuilder unit tests", () => {
     it("constructor", () => {
@@ -379,14 +382,20 @@ describe("RequestParameterBuilder unit tests", () => {
         sinon.restore();
     });
 
-    it("adds clientAssertion and assertionType if they are passed in as strings", () => {
-        const clientAssertion = {
+    it("adds clientAssertion (string) and assertionType if they are provided by the developer", async () => {
+        const clientAssertion: ClientAssertion = {
             assertion: "testAssertion",
             assertionType: "jwt-bearer",
         };
 
         const requestParameterBuilder = new RequestParameterBuilder();
-        requestParameterBuilder.addClientAssertion(clientAssertion.assertion);
+        requestParameterBuilder.addClientAssertion(
+            await getClientAssertion(
+                clientAssertion.assertion,
+                "client_id",
+                "optional_token_endpoint"
+            )
+        );
         requestParameterBuilder.addClientAssertionType(
             clientAssertion.assertionType
         );
@@ -407,14 +416,94 @@ describe("RequestParameterBuilder unit tests", () => {
         ).toBe(true);
     });
 
-    it("doesn't add client assertion and client assertion type if they are empty strings", () => {
-        const clientAssertion = {
+    it("doesn't add client assertion (string) and client assertion type if they are empty strings", async () => {
+        const clientAssertion: ClientAssertion = {
             assertion: "",
             assertionType: "",
         };
 
         const requestParameterBuilder = new RequestParameterBuilder();
-        requestParameterBuilder.addClientAssertion(clientAssertion.assertion);
+        requestParameterBuilder.addClientAssertion(
+            await getClientAssertion(
+                clientAssertion.assertion,
+                "client_id",
+                "optional_token_endpoint"
+            )
+        );
+        requestParameterBuilder.addClientAssertionType(
+            clientAssertion.assertionType
+        );
+        const requestQueryString = requestParameterBuilder.createQueryString();
+        expect(
+            requestQueryString.includes(AADServerParamKeys.CLIENT_ASSERTION)
+        ).toBe(false);
+        expect(
+            requestQueryString.includes(
+                AADServerParamKeys.CLIENT_ASSERTION_TYPE
+            )
+        ).toBe(false);
+    });
+
+    it("adds clientAssertion (ClientAssertionCallback) and assertionType if they are provided by the developer", async () => {
+        const ClientAssertionCallback: ClientAssertionCallback = (
+            _config: ClientAssertionConfig
+        ) => {
+            return Promise.resolve("testAssertion");
+        };
+
+        const clientAssertion: ClientAssertion = {
+            assertion: ClientAssertionCallback,
+            assertionType: "jwt-bearer",
+        };
+
+        const requestParameterBuilder = new RequestParameterBuilder();
+        requestParameterBuilder.addClientAssertion(
+            await getClientAssertion(
+                clientAssertion.assertion,
+                "client_id",
+                "optional_token_endpoint"
+            )
+        );
+        requestParameterBuilder.addClientAssertionType(
+            clientAssertion.assertionType
+        );
+        const requestQueryString = requestParameterBuilder.createQueryString();
+        expect(
+            requestQueryString.includes(
+                `${AADServerParamKeys.CLIENT_ASSERTION}=${encodeURIComponent(
+                    "testAssertion"
+                )}`
+            )
+        ).toBe(true);
+        expect(
+            requestQueryString.includes(
+                `${
+                    AADServerParamKeys.CLIENT_ASSERTION_TYPE
+                }=${encodeURIComponent("jwt-bearer")}`
+            )
+        ).toBe(true);
+    });
+
+    it("doesn't add client assertion (ClientAssertionCallback) and client assertion type if they are empty strings", async () => {
+        const ClientAssertionCallback: ClientAssertionCallback = (
+            _config: ClientAssertionConfig
+        ) => {
+            return Promise.resolve("");
+        };
+
+        const clientAssertion: ClientAssertion = {
+            assertion: ClientAssertionCallback,
+            assertionType: "",
+        };
+
+        const requestParameterBuilder = new RequestParameterBuilder();
+        requestParameterBuilder.addClientAssertion(
+            await getClientAssertion(
+                clientAssertion.assertion,
+                "client_id",
+                "optional_token_endpoint"
+            )
+        );
         requestParameterBuilder.addClientAssertionType(
             clientAssertion.assertionType
         );

lib/msal-node/docs/initialize-confidential-client-application.md

@@ -29,6 +29,16 @@ See the MSAL sample: [auth-code-with-certs](../../../samples/msal-node-samples/a
 import * as msal from "@azure/msal-node";
 import "dotenv/config"; // process.env now has the values defined in a .env file
 
+const clientAssertionCallback: msal.ClientAssertionCallback = async (
+    config: msal.ClientAssertionConfig
+): Promise<string> => {
+    // network request that uses config.clientId and (optionally) config.tokenEndpoint
+    const result: Promise<string> = await Promise.resolve(
+        "network request which gets assertion"
+    );
+    return result;
+};
+
 const clientConfig = {
     auth: {
         clientId: "your_client_id",
@@ -38,7 +48,7 @@ const clientConfig = {
             thumbprint: process.env.thumbprint,
             privateKey: process.env.privateKey,
         }, // OR
-        clientAssertion: "assertion",
+        clientAssertion: clientAssertionCallback, // or a predetermined clientAssertion string
     },
 };
 const pca = new msal.ConfidentialClientApplication(clientConfig);
@@ -53,7 +63,7 @@ const pca = new msal.ConfidentialClientApplication(clientConfig);
 -   A Client credential is mandatory for confidential clients. Client credential can be a:
     -   `clientSecret` is secret string generated set on the app registration.
     -   `clientCertificate` is a certificate set on the app registration. The `thumbprint` is a X.509 SHA-1 thumbprint of the certificate, and the `privateKey` is the PEM encoded private key. `x5c` is the optional X.509 certificate chain used in [subject name/issuer auth scenarios](https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-node/docs/sni.md).
-    -   `clientAssertion` is string that the application uses when requesting a token. The certificate used to sign the assertion should be set on the app registration. Assertion should be of type urn:ietf:params:oauth:client-assertion-type:jwt-bearer.
+    -   `clientAssertion` is a ClientAssertion object containing an assertion string or a callback function that returns an assertion string that the application uses when requesting a token, as well as the assertion's type (urn:ietf:params:oauth:client-assertion-type:jwt-bearer). The callback is invoked every time MSAL needs to acquire a token from the token issuer. App developers should generally use the callback because assertions expire and new assertions need to be created. App developers are responsible for the assertion lifetime. Use [this mechanism](https://learn.microsoft.com/entra/workload-id/workload-identity-federation-create-trust) to get tokens for a downstream API using a Federated Identity Credential.
 
 ## Configure Authority
 

lib/msal-node/src/client/ClientApplication.ts

@@ -33,6 +33,9 @@ import {
     createClientAuthError,
     ClientAuthErrorCodes,
     buildStaticAuthorityOptions,
+    ClientAssertion as ClientAssertionType,
+    getClientAssertion,
+    ClientAssertionCallback,
 } from "@azure/msal-common";
 import {
     Configuration,
@@ -77,6 +80,9 @@ export abstract class ClientApplication {
      * Client assertion passed by the user for confidential client flows
      */
     protected clientAssertion: ClientAssertion;
+    protected developerProvidedClientAssertion:
+        | string
+        | ClientAssertionCallback;
     /**
      * Client secret passed by the user for confidential client flows
      */
@@ -451,8 +457,8 @@ export abstract class ClientApplication {
             serverTelemetryManager: serverTelemetryManager,
             clientCredentials: {
                 clientSecret: this.clientSecret,
-                clientAssertion: this.clientAssertion
-                    ? this.getClientAssertion(discoveredAuthority)
+                clientAssertion: this.developerProvidedClientAssertion
+                    ? await this.getClientAssertion(discoveredAuthority)
                     : undefined,
             },
             libraryInfo: {
@@ -469,10 +475,17 @@ export abstract class ClientApplication {
         return clientConfiguration;
     }
 
-    private getClientAssertion(authority: Authority): {
-        assertion: string;
-        assertionType: string;
-    } {
+    private async getClientAssertion(
+        authority: Authority
+    ): Promise<ClientAssertionType> {
+        this.clientAssertion = ClientAssertion.fromAssertion(
+            await getClientAssertion(
+                this.developerProvidedClientAssertion,
+                this.config.auth.clientId,
+                authority.tokenEndpoint
+            )
+        );
+
         return {
             assertion: this.clientAssertion.getJwt(
                 this.cryptoProvider,