feat: support client assertion for client credentials authentication (#228)

* feat(credentials): support using client assertion in client credentials auth

* refactor: rename type to privatekeyjwt instead of clientassertion

Author: ewanharris

configuration.ts

@@ -152,13 +152,7 @@ export class Configuration {
       case CredentialsMethod.ClientCredentials:
         this.credentials = {
           method: CredentialsMethod.ClientCredentials,
-          config: {
-            // We are only copying them from the passed in params here. We will be validating that they are valid in the Credentials constructor
-            clientId: credentialParams.config.clientId,
-            clientSecret: credentialParams.config.clientSecret,
-            apiAudience: credentialParams.config.apiAudience,
-            apiTokenIssuer: credentialParams.config.apiTokenIssuer,
-          }
+          config: credentialParams.config
         };
         break;
       case CredentialsMethod.None:

credentials/credentials.ts

@@ -12,14 +12,30 @@
 
 
 import globalAxios, { AxiosInstance } from "axios";
+import * as jose from "jose";
 
 import { assertParamExists, isWellFormedUriString } from "../validation";
 import { FgaApiAuthenticationError, FgaApiError, FgaValidationError } from "../errors";
 import { attemptHttpRequest } from "../common";
-import { AuthCredentialsConfig, ClientCredentialsConfig, CredentialsMethod } from "./types";
+import { AuthCredentialsConfig, PrivateKeyJWTConfig, ClientCredentialsConfig, ClientSecretConfig, CredentialsMethod } from "./types";
 import { TelemetryAttributes } from "../telemetry/attributes";
 import { TelemetryCounters } from "../telemetry/counters";
 import { TelemetryConfiguration } from "../telemetry/configuration";
+import { randomUUID } from "crypto";
+
+interface ClientSecretRequest {
+  client_id: string;
+  client_secret: string;
+  audience: string;
+  grant_type: "client_credentials";
+}
+
+interface ClientAssertionRequest {
+  client_id: string;
+  client_assertion: string;
+  client_assertion_type: "urn:ietf:params:oauth:client-assertion-type:jwt-bearer";
+  audience: string;
+}
 
 export class Credentials {
   private accessToken?: string;
@@ -73,10 +89,11 @@ export class Credentials {
       break;
     case CredentialsMethod.ClientCredentials:
       assertParamExists("Credentials", "config.clientId", authConfig.config?.clientId);
-      assertParamExists("Credentials", "config.clientSecret", authConfig.config?.clientSecret);
       assertParamExists("Credentials", "config.apiTokenIssuer", authConfig.config?.apiTokenIssuer);
       assertParamExists("Credentials", "config.apiAudience", authConfig.config?.apiAudience);
 
+      assertParamExists("Credentials", "config.clientSecret or config.clientAssertionSigningKey", (authConfig.config as ClientSecretConfig).clientSecret || (authConfig.config as PrivateKeyJWTConfig).clientAssertionSigningKey);
+
       if (!isWellFormedUriString(`https://${authConfig.config?.apiTokenIssuer}`)) {
         throw new FgaValidationError(
           `Configuration.apiTokenIssuer does not form a valid URI (https://${authConfig.config?.apiTokenIssuer})`);
@@ -129,25 +146,16 @@ export class Credentials {
   private async refreshAccessToken() {
     const clientCredentials = (this.authConfig as { method: CredentialsMethod.ClientCredentials; config: ClientCredentialsConfig })?.config;
     const url = `https://${clientCredentials.apiTokenIssuer}/oauth/token`;
+    const credentialsPayload = await this.buildClientAuthenticationPayload();
 
     try {
-      const wrappedResponse = await attemptHttpRequest<{
-          client_id: string,
-          client_secret: string,
-          audience: string,
-          grant_type: "client_credentials",
-        }, {
+      const wrappedResponse = await attemptHttpRequest<ClientSecretRequest|ClientAssertionRequest, {
         access_token: string,
         expires_in: number,
       }>({
         url,
         method: "POST",
-        data: {
-          client_id: clientCredentials.clientId,
-          client_secret: clientCredentials.clientSecret,
-          audience: clientCredentials.apiAudience,
-          grant_type: "client_credentials",
-        },
+        data: credentialsPayload,
         headers: {
           "Content-Type": "application/x-www-form-urlencoded"
         }
@@ -199,4 +207,43 @@ export class Credentials {
       throw err;
     }
   }
+
+  private async buildClientAuthenticationPayload(): Promise<ClientSecretRequest|ClientAssertionRequest> {
+    if (this.authConfig?.method !== CredentialsMethod.ClientCredentials) {
+      throw new FgaValidationError("Credentials method is not set to ClientCredentials");
+    }
+
+    const config = this.authConfig.config;
+    if ((config as PrivateKeyJWTConfig).clientAssertionSigningKey) {
+      const alg = (config as PrivateKeyJWTConfig).clientAssertionSigningAlgorithm || "RS256";
+      const privateKey = await jose.importPKCS8((config as PrivateKeyJWTConfig).clientAssertionSigningKey, alg);
+      const assertion = await new jose.SignJWT({})
+        .setProtectedHeader({ alg })
+        .setIssuedAt()
+        .setSubject(config.clientId)
+        .setJti(randomUUID())
+        .setIssuer(config.clientId)
+        .setAudience(`https://${config.apiTokenIssuer}/`)
+        .setExpirationTime("2m")
+        .sign(privateKey);
+      return {
+        ...config.customClaims,
+        client_id: (config as PrivateKeyJWTConfig).clientId,
+        client_assertion: assertion,
+        audience: config.apiAudience,
+        client_assertion_type: "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
+        grant_type: "client_credentials",
+      } as ClientAssertionRequest;
+    } else if ((config as ClientSecretConfig).clientSecret) {
+      return {
+        ...config.customClaims,
+        client_id: (config as ClientSecretConfig).clientId,
+        client_secret: (config as ClientSecretConfig).clientSecret,
+        audience: (config as ClientSecretConfig).apiAudience,
+        grant_type: "client_credentials",
+      };
+    }
+
+    throw new FgaValidationError("Credentials method is set to ClientCredentials, but no clientSecret or clientAssertionSigningKey is provided");
+  }
 }

credentials/types.ts

@@ -17,35 +17,63 @@ export enum CredentialsMethod {
   ClientCredentials = "client_credentials",
 }
 
-export interface ClientCredentialsConfig {
+type BaseClientCredentialsConfig = {
   /**
    * Client ID
    *
    * @type {string}
    * @memberof Configuration
    */
   clientId: string;
+   /**
+   * API Token Issuer
+   *
+   * @type {string}
+   */
+   apiTokenIssuer: string;
+   /**
+    * API Audience
+    *
+    * @type {string}
+    */
+   apiAudience: string;
+   /**
+    * Claims to be included in the token exchange request.
+    * 
+    * @type {Record<string, string>}
+    */
+   customClaims?: Record<string, string>
+}
+
+export type ClientSecretConfig = BaseClientCredentialsConfig & {
   /**
    * Client Secret
    *
    * @type {string}
    * @memberof Configuration
    */
   clientSecret: string;
+ 
+}
+export type PrivateKeyJWTConfig = BaseClientCredentialsConfig & {
   /**
-   * API Token Issuer
+   * Client assertion signing key
    *
    * @type {string}
+   * @memberof Configuration
    */
-  apiTokenIssuer: string;
+  clientAssertionSigningKey: string;
   /**
-   * API Audience
-   *
+   * Client assertion signing algorithm,
+   * defaults to `RS256` if not specified.
    * @type {string}
+   * @memberof Configuration
    */
-  apiAudience: string;
+  clientAssertionSigningAlgorithm?: string;
 }
 
+export type ClientCredentialsConfig = ClientSecretConfig | PrivateKeyJWTConfig;
+
 export interface ApiTokenConfig {
   /**
    * API Token Value

package-lock.json

@@ -24,6 +24,7 @@
   "dependencies": {
     "@opentelemetry/api": "^1.9.0",
     "axios": "^1.8.3",
+    "jose": "^5.10.0",
     "tiny-async-pool": "^2.1.0"
   },
   "devDependencies": {

package.json

@@ -22,6 +22,34 @@ export const OPENFGA_API_AUDIENCE = "https://api.fga.example/";
 export const OPENFGA_CLIENT_ID = "01H0H3D8TD07EWAQHXY9BWJG3V";
 export const OPENFGA_CLIENT_SECRET = "this-is-very-secret";
 export const OPENFGA_API_TOKEN = "fga_abcdef";
+export const OPENFGA_CLIENT_ASSERTION_SIGNING_KEY = `-----BEGIN PRIVATE KEY-----
+MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQDmJ37Zi9/LS5/I
+E5pl7XobscHSFNrTfZC9Jx15KF5iJLFb9s8twQdo/hWPC4adidu7gVCIGNGYBGH2
+Q2z9nMrVA5TUQrrTsvJw0ldSWn2MeadZcMGI0AcaomOu8P7lxyaf/sgWAOgW1P+Y
+SAEPHHvKuA0orQVVWYwt7jaaQ0GBwEh3XiwqiwUKCJQ06eeQVxXxGr9DBYtZJOzn
+gLRj0wNF3WWU5JddV2o+CHRvpN1zLBHam3RXJQMdObs2waeR85AbfO6rNQr/Zscd
+Y6XDsHjeAHOykfoMBBexK0Rdu3Vqk2DSaXG3HUC54sbCLZSDmo4S0Dsax1IEWnWs
+rA8nD5O7AgMBAAECggEAWZzoNbFSJnhgEsmbNPO1t0HLq05Gc9FwwU2RGsMemM0b
+p6ieO3zsszM3VraQqBds0IHFxvAO78dJE1dmgQsDKNSXptwCnXoQDuC/ckfcmY0m
+nVsbZ/dDxNmUwaGBRht4TRSpeHPK6lTt3i+vBeC7zI9ERGG18WkH/TxC02a7g1aL
+emz/SNgOdFkHPoKcgYyUp2Svh0aly9g2NbyIusNO4C9M/tCYRobcrZBRIognNZKY
+bZVQrnilOClVcbND1oOPs0O6sxTMGd3eR7bS6w7i59vUCPwQSTo1L/FA23ZPY5kQ
+AgeGZnp4Nve1Ecsvp48MJHb4cwJeysxH6hhyl3zMHQKBgQDzKmo1Sa5wAqTD4HAP
+/aboYfSxhIE9c3qhj5HDP76PBZa8N5fyNyTJCsauk2a2/ZFOwCz142yF1JEbxHgb
+j6XYYazVFfk2DFWb9Ul/zQMmCVcETlRhxIQPc76f9QjvAc20B6xeR3M14RwfK/u+
+FaN7PsMAItH0xJRpGIWpwN/3PQKBgQDyTUY2WsGNUzMKarLyKX5KSDELfgmJtcAv
+LunqhYnhks4i6PVknXIY4GuGhIhAanDFlFZIhTa5a2e2bNZvgRz+VxNNRsQQZPgt
+M9Gg1fLSqQOL7OZn+cjkkYfxNE1FLMoStaANl6JkCjN4Ted2pLbswCBXwa4qsxRZ
+bsA3BTWmVwKBgQCgqYSVAsLLZSPB+7dvCVPPNHF9HKRbmsIKnxZa3/IjAzlN0JmH
+QuH+Jy2QyPlTrIPmeVj7ebEJV6Isq4oEA8w7BIYyIBuRl2K08cMHOsh6yC8DPFHK
+axIqN3paq4akjBeCfJNpk2HO1pZDDkd9l0R1uMkUfO0mAQBh0/70YuhXrQKBgEbn
+igZZ5I3grOz9cEQhFE3UdlWwmkXsI8Mq7VStoz2ZYi0hEr5QvJS/B3gjzGNdQobu
+85jhMrRr07u0ecPDeqKLBKD2dmV9xoojwdJZCWfQAbOurXX7yGfqlmdlML9vbeqv
+r5iKqQCxY4Ju+a7kYItDZbOIf9kK8oeBO0pegeadAoGAfYi3Sl3wYzaP44TKmjNq
+3Z0NQChIcSzRDfEo25bioBzdlwf3tRBHTdPwdXhLJVTI/I90WMAcAgKaXlotrnMT
+HultzBviGb7LdUt1cNnjS9C+Cl8tCYePUx+Wg+pQruYX3fAo27G0GlIC8CIQz79M
+ElVV8gBIxYwuivacl3w9B6E=
+-----END PRIVATE KEY-----`;
 
 export const baseConfig: UserClientConfigurationParams = {
   storeId: OPENFGA_STORE_ID,

tests/helpers/default-config.ts

@@ -33,6 +33,7 @@ import {
   baseConfig,
   defaultConfiguration,
   OPENFGA_API_TOKEN_ISSUER,
+  OPENFGA_CLIENT_ASSERTION_SIGNING_KEY,
 } from "./helpers/default-config";
 import { getNocks } from "./helpers/nocks";
 
@@ -116,7 +117,7 @@ describe("OpenFGA SDK", function () {
               method: CredentialsMethod.ClientCredentials,
             } as AuthCredentialsConfig,
           })
-      ).toThrowError();
+      ).toThrow("config.clientId");
 
       expect(
         () =>
@@ -130,7 +131,7 @@ describe("OpenFGA SDK", function () {
               }
             } as Configuration["credentials"]
           })
-      ).toThrowError();
+      ).toThrow("config.clientId");
 
       expect(
         () =>
@@ -139,12 +140,28 @@ describe("OpenFGA SDK", function () {
             credentials: {
               method: CredentialsMethod.ClientCredentials,
               config: {
-                ...(baseConfig.credentials as any)!.clientCredentials,
+                ...(baseConfig.credentials as any)!.config,
                 clientSecret: undefined!
               }
             } as Configuration["credentials"]
           })
-      ).toThrowError();
+      ).toThrow("config.clientSecret or config.clientAssertionSigningKey");
+
+      expect(
+        () =>
+          new OpenFgaApi({
+            ...baseConfig,
+            credentials: {
+              method: CredentialsMethod.ClientCredentials,
+              config: {
+                ...(baseConfig.credentials as any)!.config,
+                clientSecret: undefined!,
+                clientAssertionSigningKey: undefined!
+              }
+            } as Configuration["credentials"]
+          })
+      ).toThrow("config.clientSecret or config.clientAssertionSigningKey");
+
 
       expect(
         () =>
@@ -158,7 +175,7 @@ describe("OpenFGA SDK", function () {
               }
             } as Configuration["credentials"]
           })
-      ).toThrowError();
+      ).toThrow("config.apiAudience");
 
       expect(
         () =>
@@ -172,7 +189,7 @@ describe("OpenFGA SDK", function () {
               }
             } as Configuration["credentials"]
           })
-      ).toThrowError();
+      ).toThrow("config.apiTokenIssuer");
     });
 
     it("should issue a network call to get the token at the first request if client id is provided", async () => {
@@ -245,13 +262,39 @@ describe("OpenFGA SDK", function () {
       nock.cleanAll();
     });
 
+
+    it("should issue a network call to get the token at the first request if client assertion is provided", async () => {
+      const scope = nocks.tokenExchange(OPENFGA_API_TOKEN_ISSUER);
+      nocks.readAuthorizationModels(baseConfig.storeId!);
+
+      const fgaApi = new OpenFgaApi({
+        ...baseConfig,
+        credentials: {
+          method: CredentialsMethod.ClientCredentials,
+          config: {
+            ...(baseConfig.credentials as any).config,
+            clientAssertionSigningKey: OPENFGA_CLIENT_ASSERTION_SIGNING_KEY
+          }
+        }
+      });
+      expect(scope.isDone()).toBe(false);
+
+      await fgaApi.readAuthorizationModels(baseConfig.storeId!);
+
+      expect(scope.isDone()).toBe(true);
+
+      nock.cleanAll();
+    });
+
+
+
     it("should allow passing in a configuration instance", async () => {
       const configuration = new Configuration(baseConfig);
       expect(() => new OpenFgaApi(configuration)).not.toThrowError();
     });
 
+
     it("should only accept valid telemetry attributes", async () => {
-    
       expect(
         () =>
           new OpenFgaApi({