features.attestClientAuth

draft-ietf-oauth-attestation-based-client-auth-10 - OAuth 2.0 Attestation-Based Client Authentication

Specifies whether Attestation-Based Client Authentication capabilities shall be enabled. When enabled, the authorization server shall support the attest_jwt_client_auth authentication method within the server’s clientAuthMethods configuration. This mechanism enables Client Instances to authenticate using a Client Attestation JWT issued by a trusted Client Attester and a corresponding Client Attestation Proof-of-Possession JWT generated by the Client Instance. It can also enable Client Attestation as an additional security signal alongside existing Client Authentication methods using the attestation_pop_jwt Proof-of-Possession method.

default value:

{
  ack: undefined,
  additionalSecuritySignal: false,
  assertAttestationJwtAndPop: [AsyncFunction: assertAttestationJwtAndPop], // see expanded details below
  challengeSecret: undefined,
  enabled: false,
  getAttestationSignaturePublicKey: [AsyncFunction: getAttestationSignaturePublicKey] // see expanded details below
}

(Click to expand) features.attestClientAuth options details

additionalSecuritySignal

Specifies whether Client Attestation shall be accepted or required as an additional security signal alongside regular client authentication. Use optional to validate the signal when it is present, or required to require the OAuth-Client-Attestation and OAuth-Client-Attestation-PoP headers after the client is identified. This uses the attestation_pop_jwt method and does not enable DPoP combined mode.

default value:

false

assertAttestationJwtAndPop

Specifies a helper function that shall be invoked to perform additional validation of the Client Attestation JWT and Client Attestation Proof-of-Possession JWT beyond the specification requirements. This enables enforcement of extension profiles, deployment-specific policies, or additional security constraints.

At the point of invocation, both JWTs have undergone signature verification and standard validity claim validation. The function may throw errors to reject non-compliant attestations or return successfully to indicate acceptance of the client authentication attempt or additional security signal.

default value:

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
  //
  // When features.attestClientAuth.additionalSecuritySignal is enabled this function
  // is also invoked after regular client authentication succeeds. At that point the
  // attestation is available as an additional request security signal.
}

challengeSecret

Specifies the cryptographic secret value used for generating server-provided challenges. This value MUST be a 32-byte Buffer instance to ensure sufficient entropy for secure challenge generation. Challenges are derived from this secret rather than stored; the same value MUST be configured on all instances of a deployment and kept stable across restarts.

getAttestationSignaturePublicKey

Specifies a helper function that shall be invoked to retrieve the public key used for Client Attestation JWT signature verification. At the point of this function’s invocation, only the JWT format has been validated; no cryptographic or claims verification has occurred.

The function MUST return a public key in one of the supported formats: CryptoKey, KeyObject, or JSON Web Key (JWK) representation. The authorization server shall use this key to verify the Client Attestation JWT signature.

default value:

async function getAttestationSignaturePublicKey(ctx, header, payload, client) {
  // @param ctx - koa request context
  // @param header - Protected Header of the Client Attestation JWT
  // @param payload - decoded, untrusted payload of the Client Attestation JWT
  // @param client - client making the request
  throw new Error('features.attestClientAuth.getAttestationSignaturePublicKey not implemented');
}

Example: (Click to expand) Fetching attester public keys from the attester’s hosted JWKS

import * as jose from 'jose';
const attesters = new Map(Object.entries({
  'https://attester.example.com': jose.createRemoteJWKSet(new URL('https://attester.example.com/jwks')),
}));
function getAttestationSignaturePublicKey(ctx, header, payload, client) {
  if (typeof header.jku === 'string' && attesters.has(header.jku)) return attesters.get(header.jku)(header);
  throw new Error('unsupported oauth-client-attestation attester');
}