feat: Experimental support for Attestation-Based Client Authentication

Author: panva

README.md

@@ -52,6 +52,7 @@ The following draft specifications are implemented by oidc-provider:
 - [Financial-grade API: Client Initiated Backchannel Authentication Profile (`FAPI-CIBA`) - Implementers Draft 01][fapi-ciba]
 - [FAPI 2.0 Message Signing (`FAPI 2.0`) - Implementers Draft 01][fapi2ms-id1]
 - [OIDC Relying Party Metadata Choices 1.0 - Implementers Draft 01][rp-metadata-choices]
+- [OAuth 2.0 Attestation-Based Client Authentication][attestation-client-auth]
 
 Updates to draft specification versions are released as MINOR library versions,
 if you utilize these specification implementations consider using the tilde `~` operator in your
@@ -168,3 +169,4 @@ actions and i.e. emit metrics that react to specific triggers. See the list of a
 [Security Policy]: https://github.com/panva/node-oidc-provider/security/policy
 [rp-metadata-choices]: https://openid.net/specs/openid-connect-rp-metadata-choices-1_0-ID1.html
 [rfc8414]: https://www.rfc-editor.org/rfc/rfc8414.html
+[attestation-client-auth]: https://www.ietf.org/archive/id/draft-ietf-oauth-attestation-based-client-auth-06.html

docs/README.md

@@ -470,6 +470,7 @@ location / {
   - [rpInitiatedLogout](#featuresrpinitiatedlogout)
   - [userinfo](#featuresuserinfo)
   - Experimental features:
+    - [attestClientAuth](#featuresattestclientauth)
     - [externalSigningSupport (e.g. KMS)](#featuresexternalsigningsupport)
     - [richAuthorizationRequests](#featuresrichauthorizationrequests)
     - [rpMetadataChoices](#featuresrpmetadatachoices)
@@ -638,6 +639,83 @@ new oidc.Provider('http://localhost:3000', {
 ```
 </details>
 
+### features.attestClientAuth
+
+[`draft-ietf-oauth-attestation-based-client-auth-06`](https://www.ietf.org/archive/id/draft-ietf-oauth-attestation-based-client-auth-06.html) - OAuth 2.0 Attestation-Based Client Authentication  
+
+> [!NOTE]
+> This is an experimental feature.
+
+Enables the method `attest_jwt_client_auth` for use in the server's `clientAuthMethods` configuration.   
+  
+
+
+_**default value**_:
+```js
+{
+  ack: undefined,
+  assertAttestationJwtAndPop: [AsyncFunction: assertAttestationJwtAndPop], // see expanded details below
+  challengeSecret: undefined,
+  enabled: false,
+  getAttestationSignaturePublicKey: [AsyncFunction: getAttestationSignaturePublicKey] // see expanded details below
+}
+```
+
+<details><summary>(Click to expand) features.attestClientAuth options details</summary><br>
+
+
+#### assertAttestationJwtAndPop
+
+Helper function used to assert the Attestation JWT and Attestation JWT PoP beyond its specification definition, e.g. According to used extension profiles.   
+ At the point of this helper's invocation the Attestation JWT and Attestation JWT PoP have had their signatures and validity claims verified.  
+
+
+_**default value**_:
+```js
+async function assertAttestationJwtAndPop(ctx, attestation, pop, client) {
+  // @param ctx - koa request context
+  // @param attestation - verified and parsed Attestation JWT
+  //        attestation.protectedHeader - parsed protected header object
+  //        attestation.payload - parsed protected header object
+  //        attestation.key - CryptoKey that verified the Attestation JWT signature
+  // @param pop - verified and parsed Attestation JWT PoP
+  //        pop.protectedHeader - parsed protected header object
+  //        pop.payload - parsed protected header object
+  //        pop.key - CryptoKey that verified the Attestation JWT PoP signature
+  // @param client - client making the request
+}
+```
+
+#### challengeSecret
+
+A secret value used for generating server-provided Client Attestation PoP JWT challenges. Must be a 32-byte length Buffer instance.  
+
+
+_**default value**_:
+```js
+undefined
+```
+
+#### getAttestationSignaturePublicKey
+
+Helper function used to verify the issuer identifier of a Client Attestation JWT and to retrieve a public key with which the Client Attestation JWT signature will be verified.   
+ At the point of this helper's invocation nothing about the Attestation JWT has been verified, only that its format is a JWT.   
+ The key may be returned as CryptoKey, KeyObject, or a JWK.  
+
+
+_**default value**_:
+```js
+async function getAttestationSignaturePublicKey(ctx, iss, header, client) {
+  // @param ctx - koa request context
+  // @param iss - Issuer Identifier from the Client Attestation JWT
+  // @param header - Protected Header of the Client Attestation JWT
+  // @param client - client making the request
+  throw new Error('features.attestClientAuth.getAttestationSignaturePublicKey not implemented');
+}
+```
+
+</details>
+
 ### features.backchannelLogout
 
 [`OIDC Back-Channel Logout 1.0`](https://openid.net/specs/openid-connect-backchannel-1_0-final.html)  
@@ -2233,7 +2311,7 @@ true
 
 ### assertJwtClientAuthClaimsAndHeader
 
-Helper function used to validate the JWT Client Authentication Assertion Claims Set and Header beyond what its specification mandates.  
+Helper function used to validate the JWT Client Authentication (`private_key_jwt` and `client_secret_jwt`) Assertion Claims Set and Header beyond what its specification mandates.  
 
 
 _**default value**_:
@@ -3212,6 +3290,7 @@ _**default value**_:
 {
   authorization: '/auth',
   backchannel_authentication: '/backchannel',
+  challenge: '/challenge',
   code_verification: '/device',
   device_authorization: '/device/auth',
   end_session: '/session/end',
@@ -3337,6 +3416,33 @@ Configure `ttl` for a given token type with a function like so, this must return
 Fine-tune the algorithms the authorization server supports by declaring algorithm values for each respective JWA use  
 
 
+### enabledJWA.attestSigningAlgValues
+
+JWS "alg" Algorithm values the authorization server supports to verify signed Client Attestation and Client Attestation PoP JWTs with   
+  
+
+
+_**default value**_:
+```js
+[
+  'ES256',
+  'Ed25519',
+  'EdDSA'
+]
+```
+<a id="enabled-jwa-attest-signing-alg-values-supported-values-list"></a><details><summary>(Click to expand) Supported values list
+</summary><br>
+
+```js
+[
+  'RS256', 'RS384', 'RS512',
+  'PS256', 'PS384', 'PS512',
+  'ES256', 'ES384', 'ES512',
+  'Ed25519', 'EdDSA',
+]
+```
+</details>
+
 ### enabledJWA.authorizationEncryptionAlgValues
 
 JWE "alg" Algorithm values the authorization server supports for JWT Authorization response (`JARM`) encryption   
@@ -3428,7 +3534,7 @@ _**default value**_:
 
 ### enabledJWA.clientAuthSigningAlgValues
 
-JWS "alg" Algorithm values the authorization server supports for signed JWT Client Authentication   
+JWS "alg" Algorithm values the authorization server supports for signed JWT Client Authentication (`private_key_jwt` and `client_secret_jwt`)   
   
 
 

example/my_adapter.js

@@ -69,6 +69,8 @@ class MyAdapter {
      *     refresh token
      * - 'jkt' {string} - JWK SHA-256 Thumbprint (according to [RFC7638]) of a DPoP bound
      *     access or refresh token
+     * - 'attestationJkt' {string} - [BackchannelAuthenticationRequest, DeviceCode, RefreshToken, PushedAuthorizationRequest only]
+     *     JWK SHA-256 Thumbprint (according to [RFC7638]) of an attest_jwt_client_auth client instance
      * - gty {string} - [AccessToken, RefreshToken only] space delimited grant values, indicating
      *     the grant type(s) they originate from (implicit, authorization_code, refresh_token or
      *     device_code) the original one is always first, second is refresh_token if refreshed

lib/actions/authorization/backchannel_request_response.js

@@ -14,6 +14,10 @@ export default async function backchannelRequestResponse(ctx) {
     scope: [...ctx.oidc.requestParamScopes].join(' '),
   });
 
+  if (ctx.oidc.client.clientAuthMethod === 'attest_jwt_client_auth') {
+    await request.setAttestBinding(ctx);
+  }
+
   // eslint-disable-next-line default-case
   switch (request.resource.length) {
     case 0:

lib/actions/authorization/device_authorization_response.js

@@ -12,6 +12,10 @@ export default async function deviceAuthorizationResponse(ctx) {
     userCode: normalize(userCode),
   });
 
+  if (ctx.oidc.client.clientAuthMethod === 'attest_jwt_client_auth') {
+    await dc.setAttestBinding(ctx);
+  }
+
   ctx.oidc.entity('DeviceCode', dc);
   ctx.body = {
     device_code: await dc.save(),

lib/actions/authorization/pushed_authorization_request_response.js

@@ -48,6 +48,10 @@ export default async function pushedAuthorizationRequestResponse(ctx) {
     trusted: ctx.oidc.client.clientAuthMethod !== 'none' || !!ctx.oidc.trusted?.length,
   });
 
+  if (ctx.oidc.client.clientAuthMethod === 'attest_jwt_client_auth') {
+    await requestObject.setAttestBinding(ctx);
+  }
+
   const id = await requestObject.save(ttl);
 
   ctx.oidc.entity('PushedAuthorizationRequest', requestObject);

lib/actions/challenge.js

@@ -0,0 +1,22 @@
+import instance from '../helpers/weak_cache.js';
+import noCache from '../shared/no_cache.js';
+
+export default [
+  noCache,
+  function challenge(ctx) {
+    const { DPoPNonces, AttestChallenges } = instance(ctx.oidc.provider);
+
+    ctx.body = {};
+
+    const nextNonce = DPoPNonces?.nextNonce();
+    if (nextNonce) {
+      ctx.set('dpop-nonce', nextNonce);
+    }
+
+    const nextChallenge = AttestChallenges?.nextChallenge();
+    if (nextChallenge) {
+      ctx.set('oauth-client-attestation-challenge', nextChallenge);
+      ctx.body.attestation_challenge = nextChallenge;
+    }
+  },
+];

lib/actions/discovery.js

@@ -139,5 +139,9 @@ export default function discovery(ctx) {
     ctx.body.authorization_details_types_supported = Object.keys(richAuthorizationRequests.types);
   }
 
+  if (features.attestClientAuth.enabled) {
+    ctx.body.challenge_endpoint = ctx.oidc.urlFor('challenge');
+  }
+
   defaults(ctx.body, configuration.discovery);
 }

lib/actions/grants/authorization_code.js

@@ -9,6 +9,8 @@ import resolveResource from '../../helpers/resolve_resource.js';
 import epochTime from '../../helpers/epoch_time.js';
 import checkRar from '../../shared/check_rar.js';
 import getCtxAccountClaims from '../../helpers/account_claims.js';
+import { setRefreshTokenBindings } from '../../helpers/set_rt_bindings.js';
+import { checkAttestBinding } from '../../helpers/check_attest_binding.js';
 
 const gty = 'authorization_code';
 
@@ -89,6 +91,10 @@ export const handler = async function authorizationCodeHandler(ctx) {
     throw new InvalidGrant('authorization code redirect_uri mismatch');
   }
 
+  if (ctx.oidc.client.clientAuthMethod === 'attest_jwt_client_auth' && code.attestationJkt) {
+    await checkAttestBinding(ctx, code);
+  }
+
   if (code.consumed) {
     await revoke(ctx, code.grantId);
     throw new InvalidGrant('authorization code already consumed');
@@ -192,15 +198,7 @@ export const handler = async function authorizationCodeHandler(ctx) {
       rar: code.rar,
     });
 
-    if (ctx.oidc.client.clientAuthMethod === 'none') {
-      if (at.jkt) {
-        rt.jkt = at.jkt;
-      }
-
-      if (at['x5t#S256']) {
-        rt['x5t#S256'] = at['x5t#S256'];
-      }
-    }
+    await setRefreshTokenBindings(ctx, at, rt);
 
     ctx.oidc.entity('RefreshToken', rt);
     refreshToken = await rt.save();

lib/actions/grants/ciba.js

@@ -9,6 +9,8 @@ import dpopValidate, { DPOP_OK_WINDOW } from '../../helpers/validate_dpop.js';
 import resolveResource from '../../helpers/resolve_resource.js';
 import epochTime from '../../helpers/epoch_time.js';
 import getCtxAccountClaims from '../../helpers/account_claims.js';
+import { setRefreshTokenBindings } from '../../helpers/set_rt_bindings.js';
+import { checkAttestBinding } from '../../helpers/check_attest_binding.js';
 
 const {
   AuthorizationPending,
@@ -72,6 +74,10 @@ export const handler = async function cibaHandler(ctx) {
     throw new AuthorizationPending();
   }
 
+  if (ctx.oidc.client.clientAuthMethod === 'attest_jwt_client_auth') {
+    await checkAttestBinding(ctx, request);
+  }
+
   if (request.consumed) {
     await revoke(ctx, request.grantId);
     throw new InvalidGrant('backchannel authentication request already consumed');
@@ -185,15 +191,7 @@ export const handler = async function cibaHandler(ctx) {
       sid: request.sid,
     });
 
-    if (ctx.oidc.client.clientAuthMethod === 'none') {
-      if (at.jkt) {
-        rt.jkt = at.jkt;
-      }
-
-      if (at['x5t#S256']) {
-        rt['x5t#S256'] = at['x5t#S256'];
-      }
-    }
+    await setRefreshTokenBindings(ctx, at, rt);
 
     ctx.oidc.entity('RefreshToken', rt);
     refreshToken = await rt.save();