feat: add support for assertion framework

Author: dhensby

docs/api/handlers/token-handler.md

@@ -53,8 +53,14 @@ Get client credentials.
 The client credentials may be sent using the HTTP Basic authentication scheme or, alternatively,
 the `client_id` and `client_secret` can be embedded in the body.
 
+Also support the assertion framework for client authentication.
+
 **Kind**: instance method of [<code>TokenHandler</code>](#TokenHandler)  
-**See**: https://tools.ietf.org/html/rfc6749#section-2.3.1  
+**See**
+
+- https://datatracker.ietf.org/doc/html/rfc6749#section-2.3.1
+- https://datatracker.ietf.org/doc/html/rfc7521
+
 <a name="TokenHandler+handleGrantType"></a>
 
 ### tokenHandler.handleGrantType()

index.d.ts

@@ -242,6 +242,12 @@ declare namespace OAuth2Server {
         extendedGrantTypes?: Record<string, typeof AbstractGrantType>;
     }
 
+    interface AssertionCredential {
+        clientAssertion: string;
+        clientAssertionType: string;
+        clientId?: string;
+    }
+
     /**
      * For returning falsey parameters in cases of failure
      */
@@ -265,6 +271,16 @@ declare namespace OAuth2Server {
          *
          */
         saveToken(token: Omit<Token, 'client' | 'user'>, client: Client, user: User): Promise<Token | Falsey>;
+
+        /**
+         * Invoked to retrieve a client using a client assertion.
+         *
+         * It is for the model to decide if it supports the assertion framework and, if so, which
+         * assertion frameworks are supported. The function can return null if no model is found or
+         * throw an `InvalidClientError` if the assertion is invalid or not supported.
+         *
+         */
+        getClientFromAssertion?(assertion: AssertionCredential): Promise<Client | Falsey>;
     }
 
     interface RequestAuthenticationModel {

lib/handlers/token-handler.js

@@ -117,25 +117,36 @@ class TokenHandler {
     const grantType = request.body.grant_type;
     const codeVerifier = request.body.code_verifier;
     const isPkce = pkce.isPKCERequest({ grantType, codeVerifier });
+    const isAssertion = this.isClientAssertionRequest(request);
 
-    if (!credentials.clientId) {
-      throw new InvalidRequestError('Missing parameter: `client_id`');
-    }
+    // @todo - if multiple authentication schemes exist, throw an error
+    if (!isAssertion) {
+      if (!credentials.clientId) {
+        throw new InvalidRequestError('Missing parameter: `client_id`');
+      }
 
-    if (this.isClientAuthenticationRequired(grantType) && !credentials.clientSecret && !isPkce) {
-      throw new InvalidRequestError('Missing parameter: `client_secret`');
-    }
+      if (this.isClientAuthenticationRequired(grantType) && !credentials.clientSecret && !isPkce) {
+        throw new InvalidRequestError('Missing parameter: `client_secret`');
+      }
 
-    if (!isFormat.vschar(credentials.clientId)) {
-      throw new InvalidRequestError('Invalid parameter: `client_id`');
-    }
+      if (!isFormat.vschar(credentials.clientId)) {
+        throw new InvalidRequestError('Invalid parameter: `client_id`');
+      }
 
-    if (credentials.clientSecret && !isFormat.vschar(credentials.clientSecret)) {
-      throw new InvalidRequestError('Invalid parameter: `client_secret`');
+      if (credentials.clientSecret && !isFormat.vschar(credentials.clientSecret)) {
+        throw new InvalidRequestError('Invalid parameter: `client_secret`');
+      }
+    } else {
+      if (!credentials.clientAssertion) {
+        throw new InvalidClientError('Missing parameter: `client_assertion`');
+      }
+      if (!credentials.clientAssertionType) {
+        throw new InvalidClientError('Missing parameter: `client_assertion_type`');
+      }
     }
 
     try {
-      const client = await this.model.getClient(credentials.clientId, credentials.clientSecret);
+      const client = await (isAssertion ? this.model.getClientFromAssertion?.(credentials) : this.model.getClient(credentials.clientId, credentials.clientSecret));
 
       if (!client) {
         throw new InvalidClientError('Invalid client: client is invalid');
@@ -170,7 +181,10 @@ class TokenHandler {
    * The client credentials may be sent using the HTTP Basic authentication scheme or, alternatively,
    * the `client_id` and `client_secret` can be embedded in the body.
    *
-   * @see https://tools.ietf.org/html/rfc6749#section-2.3.1
+   * Also support the assertion framework for client authentication.
+   *
+   * @see https://datatracker.ietf.org/doc/html/rfc6749#section-2.3.1
+   * @see https://datatracker.ietf.org/doc/html/rfc7521
    */
 
   getClientCredentials(request) {
@@ -189,6 +203,10 @@ class TokenHandler {
       };
     }
 
+    if (this.isClientAssertionRequest(request)) {
+      return { clientId: request.body.client_id, clientAssertion: request.body.client_assertion, clientAssertionType: request.body.client_assertion_type };
+    }
+
     if (pkce.isPKCERequest({ grantType, codeVerifier })) {
       if (request.body.client_id) {
         return { clientId: request.body.client_id };
@@ -302,6 +320,10 @@ class TokenHandler {
     response.status = error.code;
   }
 
+  isClientAssertionRequest({ body }) {
+    return body.client_assertion && body.client_assertion_type;
+  }
+
   /**
    * Given a grant type, check if client authentication is required
    */