]> MATTR

tobias.looker@mattr.global

Bundesdruckerei

paul.bastian@posteo.de

SPRIND

chris.bormann@gmx.de

Security Web Authorization Protocol This specification defines an extension to the OAuth 2.0 protocol (RFC 6749) that enables a client instance to include a key-bound attestation when interacting with an Authorization Server or Resource Server. This mechanism allows a client instance to prove its authenticity verified by a client attester without revealing its target audience to that attester. It may also serve as a mechanism for client authentication as per OAuth 2.0. About This Document The latest revision of this draft can be found at . Status information for this document may be found at . Discussion of this document takes place on the Web Authorization Protocol Working Group mailing list (), which is archived at . Subscribe at . Source for this draft and an issue tracker can be found at .

Introduction Traditional OAuth client authentication methods, such as private_key_jwt defined in , typically rely on a direct connection between the client's backend and the Authorization Server. In ecosystems such as the Issuer-Holder-Verifier model used in , this direct communication raises privacy concerns, as it would enable the client's backend (i.e. client attester) to correlate which Holder (i.e. client) interacts with which Issuer (i.e. Authorization Server) and potentially observe the credentials or metadata being issued. This specification establishes a mechanism for a backend-attested client authentication through a front-channel to address these issues. Additionally, this approach acknowledges the evolving landscape of OAuth 2 deployments, where the ability for mobile native apps to authenticate securely and reliably has become increasingly important. Leveraging platform mechanisms to validate a client instance, such as mobile native apps, enables secure authentication that would otherwise be difficult with traditional OAuth client authentication methods. Transforming these platform-specific mechanisms into a common format as described in this specification abstracts this complexity to minimize the efforts for the Authorization Server. The primary purpose of this specification is the authentication of a client instance enabled through the client backend attesting to it. The client backend may also attest further technical properties about the hardware and software of the client instance. The client is considered a confidential OAuth 2 client type according to . The mechanism described in this document may either serve as a standalone OAuth 2 client authentication mechanism or as an additional, supportive security mechanism beside an existing OAuth 2 client authentication mechanism. This specification introduces the concept of client attestations to the OAuth 2 protocol, using two artifacts:

• a Client Attestation, a signed statement by the Client Attester that authenticates the Client Instance
• a Proof of Possession (PoP), a signed statement by the Client Instance that authenticates the Client Attestation

This specification does not use the Assertion Framework for OAuth 2.0 Client Authentication, as the client attestation is transferred by HTTP headers, which is incompatible with the mechanisms defined by .

Data Flow The following diagram depicts the overall architecture and protocol flow towards an Authorization Server. | | (5) | | (1) | | Client |<--------->| Authorization | | | Instance | (7) | Server | +------| |<--------->| | +---------------+ +---------------+ ^ | | | +-------+ (6) ]]> The following steps describe this OAuth flow: (1) The Client Instance generates a key (Client Instance Key) and gathers optional evidence to prove its authenticity to the Client Attester. This could be evidence about the software running on the client, statements about the integrity of the operating system, or hardware the Client Instance is running on. A Client Instance can provide several such statements or attestations to the Client Attester within a single request, but their content, how they are collected, and how they are transmitted are out of scope of this specification. (2) The Client Instance sends this data to the Client Attester in request for a Client Attestation JWT. Transmission of the evidence may result in one or multiple requests. (3) The Client Attester authenticates the Client Instance, validates that the Client Instance is in control of the private key of the Client Instance Key, and evaluates any further provided evidence according to its policy. It then generates a signed Client Attestation JWT that is cryptographically bound to the Client Instance Key generated by the Client. Therefore, the attestation is bound to this particular Client Instance. (4) The Client Attester responds to the Client Instance by sending the Client Attestation JWT. (5) The Client Instance optionally requests a Challenge from the Authorization Server's Challenge endpoint or receives a challenge from a previous message. (6) The Client Instance generates a Proof of Possession (PoP) with the Client Instance Key. (7) The Client Instance sends the Client Attestation JWT along with its Proof of Possession to the Authorization Server, e.g. within a token request. The Proof of Possession is typically a Client Attestation PoP JWT or a DPoP proof (see ). The Authorization Server validates the Client Attestation and thus authenticates the Client Instance. The same flow applies when authenticating to a Resource Server, where step (7) typically occurs when accessing a protected resource. Please note that the protocol details for steps (2) and (4), particularly how the Client Instance authenticates to the Client Attester, are beyond the scope of this specification. Furthermore, this specification is designed to be flexible and can be implemented even in scenarios where the client does not have a backend serving as a Client Attester. In such cases, each Client Instance is responsible for performing the functions typically handled by the Client Attester on its own. While the concrete evidence about the Client Instance collected and transmitted in (1) and (2) is out of scope, a Client Attestation JWT is generally understood to convey that the Client Attester has verified

• the authenticity and integrity of the Client Instance (this might encompass statements about its software and hardware environment)
• that the Client Instance controls the private key of the Client Instance Key
• optionally, properties of that key (e.g., that it was securely generated or resides in hardware-backed storage)

Conventions and Definitions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here.

Terminology

Client Attestation JWT:

A JSON Web Token (JWT) generated by the Client Attester that attests to the authenticity of a Client Instance and is cryptographically bound to a key managed by that Client Instance. A Client Attestation JWT may additionally convey information about the integrity or state of the Client Instance.

Client Attestation Proof of Possession (PoP) JWT:

A Proof of Possession generated by the Client Instance using the key that the Client Attestation JWT is bound to.

Client Instance:

A deployed instance of a piece of client software.

Client Instance Key:

A cryptographic asymmetric key pair that is generated by the Client Instance where the public key of the key pair is provided to the Client Attester. This public key is then encapsulated within the Client Attestation JWT and is utilized to sign a proof of possession.

Client Attester:

An entity that authenticates a Client Instance and attests it by issuing a Client Attestation JWT.

Challenge:

A String that is the input to a cryptographic challenge-response pattern, used to detect replay attacks. Within OAuth, this is traditionally called a nonce.

Client Attestation JWT The Client Attestation MUST be encoded as a "JSON Web Token (JWT)" according to . The following content applies to the JWT Header:

• typ: REQUIRED. The typ (JWT type) header MUST be oauth-client-attestation+jwt unless specified otherwise by a profile as described in .
• alg: REQUIRED. The alg (algorithm) header MUST specify the cryptographic algorithm used to sign the Client Attestation.

The following content applies to the JWT Claims Set:

• sub: REQUIRED. The sub (subject) claim MUST specify the client_id value of the OAuth Client, unless specified otherwise by a profile as described in .
• exp: REQUIRED. The exp (expiration time) claim MUST specify the time at which the Client Attestation is considered expired by its issuer. The Authorization Server or Resource Server MUST reject any JWT with an expiration time that has passed, subject to allowable clock skew between systems.
• cnf: REQUIRED. The cnf (confirmation) claim MUST specify a key conforming to that is used by the Client Instance to generate the Client Attestation PoP JWT for client authentication with an Authorization Server or Resource Server. The key MUST be expressed using the "jwk" representation.
• iat: OPTIONAL. The iat (issued at) claim MUST specify the time at which the Client Attestation was issued.

The following additional rules apply:

1. The JWT MAY contain other claims. All claims that are not understood by implementations MUST be ignored.
2. The JWT MUST be digitally signed or integrity protected with a Message Authentication Code (MAC). The Authorization Server or Resource Server MUST reject JWTs if signature or integrity protection validation fails.
3. The Authorization Server or Resource Server MUST reject a JWT that is not valid in all other respects per "JSON Web Token (JWT)" .

The following example is the decoded header and payload of a JWT meeting the processing rules as defined above. When using headers to transfer the Client Attestation JWT to an Authorization Server or Resource Server, it MUST be provided in an HTTP request using the HTTP header field OAuth-Client-Attestation. The following is an example of the OAuth-Client-Attestation header. Note that per header field names are case-insensitive; so OAUTH-CLIENT-ATTESTATION, oauth-client-attestation, etc., are all valid and equivalent header field names. Case is significant in the header field value, however. The OAuth-Client-Attestation HTTP header field value uses the token68 syntax defined in (repeated below for ease of reference).

Proof of Possession This specification defines two options for the proof of possession:

• A Client Attestation PoP JWT, introduced by this specification
• Utilizing DPoP as defined in

Other specifications or profiles may define additional proof of possession mechanisms for use with the Client Attestation. Any such mechanism MUST demonstrate possession of the private key corresponding to the key in the cnf claim of the Client Attestation JWT and MUST define how server-provided freshness is achieved, either by incorporating a Challenge (see ) into the proof of possession or by an equivalent mechanism native to that proof of possession mechanism. Such specifications are also expected to register their own token endpoint authentication method value, analogous to attest_jwt_client_auth and attest_jwt_client_auth_dpop (see ).

Client Attestation PoP JWT The Client Attestation PoP MUST be encoded as a "JSON Web Token (JWT)" according to . The following content applies to the JWT Header:

• typ: REQUIRED. The typ (JWT type) header MUST be oauth-client-attestation-pop+jwt.
• alg: REQUIRED. The alg (algorithm) header MUST specify the cryptographic algorithm used to sign the Client Attestation PoP

The following content applies to the JWT Claims Set:

• aud: REQUIRED. The aud (audience) claim MUST specify a value that identifies the intended audience of the JWT. When the JWT is presented to an Authorization Server, the issuer identifier URL of the Authorization Server MUST be used. When the JWT is presented to a Resource Server, the resource identifier URL of the Resource Server MUST be used. A Client Attestation PoP JWT is intended for a single audience, Clients MUST generate JWTs for each target.
• jti: REQUIRED. The jti (JWT identifier) claim MUST specify a unique identifier for the Client Attestation PoP. The Authorization Server or Resource Server can utilize the jti value for replay attack detection, see .
• iat: REQUIRED. The iat (issued at) claim MUST specify the time at which the Client Attestation PoP was issued. Note that the Authorization Server or Resource Server may reject JWTs with an "iat" claim value that is unreasonably far in the past.
• challenge: OPTIONAL. The challenge (challenge) claim MUST specify a String value that is provided by the Authorization Server or Resource Server for the client to include in the Client Attestation PoP JWT.

The following additional rules apply:

1. The JWT MAY contain other claims. All claims that are not understood by implementations MUST be ignored.
2. The JWT MUST be digitally signed using an asymmetric cryptographic algorithm. The Authorization Server or Resource Server MUST reject JWTs with an invalid signature.
3. The public key used to verify the JWT MUST be the key located in the "cnf" claim of the corresponding Client Attestation JWT.
4. The Authorization Server or Resource Server MUST reject a JWT that is not valid in all other respects per "JSON Web Token (JWT)" .

The following example is the decoded header and payload of a JWT meeting the processing rules as defined above. When using headers to transfer the Client Attestation PoP JWT to an Authorization Server or Resource Server, it MUST be provided in an HTTP request using the HTTP header field OAuth-Client-Attestation-PoP. The following is an example of the OAuth-Client-Attestation-PoP header. Note that per header field names are case-insensitive; so OAUTH-CLIENT-ATTESTATION-POP, oauth-client-attestation-pop, etc., are all valid and equivalent header field names. Case is significant in the header field value, however. The OAuth-Client-Attestation-PoP HTTP header field value uses the token68 syntax defined in (repeated below for ease of reference).

Using DPoP as the Proof of Possession This section defines an optimization that allows a single Proof of Possession (PoP) JWT to satisfy the role of both (a) the Client Attestation PoP defined in this specification and (b) the DPoP proof defined in for sender-constrained access tokens. In this "combined mode" the Client Instance Key and the DPoP Key are the same asymmetric key pair, and a request using the mechanism carries only one PoP, the DPoP proof, instead of two separate PoP JWTs (the DPoP proof and Client Attestation PoP JWT). Note that combined mode requires an actual DPoP proof to be presented, since the DPoP proof also serves as the Client Attestation PoP; the dpop_jkt authorization request parameter defined in cannot substitute for it. A Client that binds the authorization code using dpop_jkt without presenting a DPoP proof therefore uses the normal mode. Note that DPoP can also be used alongside the Client Attestation PoP JWT without this combined mode. In this case, the DPoP proof is validated according to independently of this specification and its public key is not required to match the key in the cnf claim of the Client Attestation JWT (see ). The following rules apply to the DPoP proof as defined in :

1. The DPoP proof MUST adhere to
2. The public key located in the DPoP proof MUST match the public key located in the cnf claim of the Client Attestation JWT.

In combined mode, the Challenge mechanisms defined by this specification (the challenge claim and the OAuth-Client-Attestation-Challenge HTTP header field, see ) are not used for the DPoP proof. Instead, server-provided freshness and replay protection rely solely on the DPoP nonce mechanism defined in and : the server provides a nonce that the Client includes in the nonce claim of the DPoP proof. In addition to the means defined by , a server that supports DPoP with server-provided nonces provides a fresh DPoP nonce in the response of the challenge endpoint as described in , allowing the Client to obtain a nonce proactively. The following non-normative example shows a token request using combined mode (line breaks for display only): DPoP: grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA ]]> Decoded (non-normative) DPoP (combined) proof - Header: Payload: Note that additional claims may be present in the DPoP proof depending on the context, as required by . The nonce claim is present when the server provides DPoP nonces, either through the means defined in or through the challenge endpoint (see ).

Challenges Challenges may be used by the Authorization Server or Resource Server to guarantee freshness and can be used to detect replay attacks. Support for Challenges is OPTIONAL for the Authorization Server or Resource Server. The lifetime of a Challenge, and whether a Challenge may be used in more than one Client Attestation PoP JWT, are determined solely by the local policy of the Authorization Server or Resource Server. If they are provided, the Client MUST include the Challenge in the proof of possession. The value of the challenge is opaque to the Client. A server that uses Challenges:

• MUST provide a Challenge when returning an use_attestation_challenge error defined in
• MAY provide a Challenge in any HTTP response as described in
• MAY provide a Challenge at the challenge endpoint as described in

A Client MUST include the most recently received Challenge provided by the Authorization Server or Resource Server in the Client Attestation PoP JWT as defined in , irrespective of whether that Challenge was obtained from the challenge endpoint or from a previous response as described in . If the Authorization Server or Resource Server provides a challenge endpoint as defined in , a Client that does not hold a Challenge SHOULD obtain a Challenge from that endpoint rather than sending a request without a Challenge and relying on the resulting error response. A Client MAY use the same Challenge in more than one Client Attestation PoP JWT. If the Authorization Server or Resource Server accepts a Challenge only once, it rejects the second use with the use_attestation_challenge error as defined in and provides a fresh Challenge in that response. Upon receiving a use_attestation_challenge error, a Client SHOULD retry the request once, using a newly created Client Attestation PoP JWT containing the Challenge provided with that error response. A Client MUST NOT retry indefinitely. This mechanism applies only to the Client Attestation PoP JWT. In the DPoP combined mode (see ), the use_dpop_nonce error and the DPoP-Nonce HTTP header field defined in are used instead, see . The challenge endpoint MAY be utilized to provide DPoP-Nonce HTTP header field.

Providing Challenges in Errors An Authorization Server that requires a Challenge that the Client did not provide, or that rejects the Challenge contained in the Client Attestation PoP JWT, MUST respond with an HTTP 400 (Bad Request) status code and the error code use_attestation_challenge (see ). The response MUST include a fresh Challenge in the OAuth-Client-Attestation-Challenge HTTP header field. A Resource Server that requires a Challenge that the Client did not provide, or that rejects the Challenge contained in the Client Attestation PoP JWT, MUST respond with an HTTP 401 (Unauthorized) status code with the error code use_attestation_challenge in the WWW-Authenticate HTTP header field and a fresh Challenge in the OAuth-Client-Attestation-Challenge HTTP header field. The Client uses the Challenge provided with the error response to retry the request. The following is a non-normative example of such an error response of an Authorization Server:

Providing Challenges in Previous Responses The Authorization Server or Resource Server MAY provide a fresh Challenge with any HTTP response using a HTTP header-based syntax. The HTTP header field MUST be named "OAuth-Client-Attestation-Challenge" and contain the value of the Challenge. The following is a non-normative example of an Authorization Response containing a fresh Challenge:

Providing Challenges through the Challenge Endpoint The Authorization Server or Resource Server MAY provide a challenge endpoint for Clients to fetch Challenges in the context of this specification. If the Authorization Server supports metadata as defined in or the Resource Server supports metadata as defined in , it MUST signal support for the challenge endpoint by including the metadata entry challenge_endpoint containing the URL of the endpoint as its value. If the challenge endpoint response contains a DPoP-Nonce HTTP header field, a Client using DPoP MUST use its value as the nonce in subsequent DPoP proofs as defined in . A request for a Challenge is made by sending an HTTP POST request to the URL provided in the challenge_endpoint parameter of the Authorization Server metadata. The following is a non-normative example of a request: The Authorization Server or Resource Server provides a Challenge in the HTTP response with a 200 status code and the following parameters included in the message body of the HTTP response using the application/json media type:

• attestation_challenge: REQUIRED if the Authorization Server or Resource Server supports Client Attestations and server-provided challenges as described in this document. String containing a Challenge to be used in the Client Attestation PoP JWT as defined in . The intention of this element not being required in other circumstances is to preserve the ability for the challenge endpoint to be used in other applications unrelated to client attestations.

If the server supports DPoP with server-provided nonces, the response MUST additionally include a fresh DPoP nonce in the DPoP-Nonce HTTP header field as defined in . This allows a Client to obtain a DPoP nonce proactively, without the additional round trip caused by a use_dpop_nonce error, both when using the DPoP combined mode (see ) and when using DPoP independently of this specification. The Authorization Server or Resource Server MUST make the response uncacheable by adding a Cache-Control header field including the value no-store. The Authorization Server or Resource Server MAY add additional challenges or data. The following is a non-normative example of a response: The DPoP-Nonce HTTP header field in this example is only present if the server supports DPoP with server-provided nonces. The attestation_challenge parameter is only present if the server supports Client Attestations and server-provided challenges (i.e., this endpoint can also be used to provide only DPoP nonces).

Verification and Processing This section defines the verification and processing rules for the proof of possession mechanisms defined by this specification. Proof of possession mechanisms defined by other specifications define their own verification and processing rules. An Authorization Server MAY support both attest_jwt_client_auth and attest_jwt_client_auth_dpop and distinguish them by the following rules:

• If the request contains an OAuth-Client-Attestation-PoP HTTP request header field, the receiving server MUST apply the validation rules of and if present, a DPoP proof present in the request is validated according to independently of this specification.
• If an OAuth-Client-Attestation HTTP request header field and a DPoP proof are present, but no OAuth-Client-Attestation-PoP HTTP request header field, the receiving server MUST apply the validation rules of .
• If the request contains an OAuth-Client-Attestation header field and a DPoP proof, but no OAuth-Client-Attestation-PoP header field, and the Authorization Server does not support attest_jwt_client_auth_dpop, it MUST reject the request (see ).

Client Attestation JWT To validate a Client Attestation, the receiving server MUST ensure the following conditions and rules are met:

1. There is precisely one OAuth-Client-Attestation HTTP request header field containing a Client Attestation JWT.
2. The Client Attestation JWT contains all required claims and header parameters as per .
3. The alg JOSE Header Parameter contains a registered algorithm , is not none, is supported by the application, and is acceptable per local policy.
4. The signature of the Client Attestation JWT verifies with the public key of a known and trusted Client Attester.
5. The key contained in the cnf claim of the Client Attestation JWT is not a private key.
6. The Client Attestation JWT is fresh enough per local policy of the Authorization Server or Resource Server by checking the iat or exp claims.
7. If a client_id is provided in the request containing the Client Attestation, then this client_id matches the sub claim of the Client Attestation JWT, unless specified otherwise by a profile as described in .

Client Attestation PoP JWT This section applies when the Client Attestation PoP JWT is used as the Proof of Possession. When operating in DPoP combined mode as defined in , this section does not apply; instead, see . To validate a Client Attestation PoP, the receiving server MUST ensure the following conditions and rules are met:

1. There is precisely one OAuth-Client-Attestation-PoP HTTP request header field containing a Client Attestation PoP JWT.
2. The Client Attestation PoP JWT contains all required claims and header parameters as per .
3. The alg JOSE Header Parameter contains a registered algorithm , is not none, is supported by the application, and is acceptable per local policy.
4. The signature of the Client Attestation PoP JWT verifies with the public key contained in the cnf claim of the Client Attestation JWT.
5. If the server provides challenges through the challenge endpoint or within previous responses as described in , the challenge claim of the Client Attestation PoP JWT MUST match a provided challenge.
6. The creation time of the Client Attestation PoP JWT as determined by either the iat claim or a server managed timestamp via the challenge claim, is within an acceptable window per local policy of the Authorization Server or Resource Server.
7. The audience claim in the Client Attestation PoP JWT identifies the receiving server: when validated by an Authorization Server, it MUST be the issuer identifier URL of the Authorization Server as described in ; when validated by a Resource Server, it MUST be the resource identifier URL of the Resource Server as described in .
8. Depending on the security requirements of the deployment, additional checks to guarantee replay protection for the Client Attestation PoP JWT might need to be applied (see for more details).

DPoP Combined Mode This section applies when the DPoP combined mode is used as defined in . When the Client Attestation PoP JWT is used as the Proof of Possession instead, this section does not apply; see . To validate a request using DPoP combined mode, the receiving server MUST perform the following steps:

1. There is no OAuth-Client-Attestation-PoP HTTP request header field present in the request.
2. There is precisely one DPoP HTTP request header field present in the request.
3. Validate the DPoP proof in accordance with . If the server provides DPoP nonces, this includes validating that the nonce claim of the DPoP proof contains a valid nonce provided by the server, whether it was provided via the DPoP-Nonce HTTP header field as defined in or via the challenge endpoint as described in .
4. The public key in the jwk header parameter of the DPoP proof MUST be identical to the public key in the cnf claim of the Client Attestation JWT. Note that this doesn't mean the comparison of a canonical representation of the JWK, but a check via JWK thumbprint or by comparing the required members per key type (e.g., kty, curve, x, y).

Errors When validation errors specifically related to the use of client attestations are encountered the following additional error codes are defined for use in either Authorization Server authenticated endpoint error responses (as defined in ) or Resource Server error responses (as defined in ).

• use_attestation_challenge MUST be used when the Client Attestation PoP JWT is not using an expected server-provided challenge. When used, this error code MUST be accompanied by a fresh Challenge in the OAuth-Client-Attestation-Challenge HTTP header field (as described in ). If the combined mode as defined in is used and the DPoP proof does not contain an expected server-provided nonce, the DPoP error use_dpop_nonce MUST be used instead and a fresh nonce provided in the DPoP-Nonce HTTP header field of the response, as defined in .
• use_fresh_attestation MUST be used when the Client Attestation JWT is deemed to be not fresh enough to be acceptable by the server.
• invalid_client_attestation MAY be used in addition to the more general invalid_client error code as defined in if the attestation or its proof of possession could not be successfully verified, the public keys of the Client Attestation JWT and the proof of possession don't match, or the proof of possession is not supported.

In the event of errors due to situations not described above, Authorization and Resource Servers MUST follow the guidance of and or their respective extensions of when to return suitable Error Responses.

Client Attestation as an OAuth Client Authentication A Client Attestation may be used as an OAuth 2 Client Authentication mechanism as described in towards an Authorization Server. If the token request contains a client_id parameter as per the Authorization Server MUST verify that the value of this parameter is the same as the client_id value in the sub claim of the Client Attestation, unless specified otherwise by a profile as described in . The following example demonstrates usage of the client attestation mechanism in an access token request (with extra line breaks for display purposes only):

Client Attestation as an additional security signal A Client Attestation may be used as a (additional) security signal towards an Authorization Server or Resource Server. This may provide additional assurance about the client's authenticity, integrity, state or other information contained in the Client Attestation. When used at the Authorization Server, the Client Attestation may appear alongside existing OAuth 2 Client Authentication mechanisms. An Authorization Server or Resource Server MAY signal a requirement to Clients for presenting a Client Attestation and its Proof of Possession as an additional security signal alongside the regular request. A server signals this demand by including the client_attestation_pop_methods_supported metadata parameter in its published metadata, as defined in for the Authorization Server and in for the Resource Server. The value of client_attestation_pop_methods_supported is a JSON array of case-sensitive strings, each identifying a Proof of Possession method that the server accepts, as registered in the "OAuth Client Attestation Proof-of-Possession Methods" registry established by this specification (see ). A server MUST NOT include a method it does not accept, and the array MUST NOT be empty when the parameter is present. When the parameter is omitted, presenting a Client Attestation as an additional security signal is OPTIONAL. When the parameter includes none, the Client MAY omit the Client Attestation. If the Client sends a Client Attestation, it MUST use one of the supported Proof of Possession methods. For example, for "client_attestation_pop_methods_supported": ["dpop_combined", "none"], the server accepts requests without a Client Attestation as well as requests carrying a Client Attestation with a DPoP proof as the Proof of Possession. When the parameter is present and does not include none, a Client SHOULD include the Client Attestation and its Proof of Possession in its requests to that server, and the Client MUST use one of the listed Proof of Possession methods. This specification registers the following Proof of Possession methods:

• attestation_pop_jwt: The Proof of Possession is a dedicated Client Attestation PoP JWT as defined in ("normal mode").
• dpop_combined: The Proof of Possession is a DPoP proof serving as the combined Proof of Possession as defined in ("DPoP combined mode").
• none: No Client Attestation is required. A server includes this value to signal that the Client MAY omit the Client Attestation.

The following example demonstrates usage of the client attestation mechanism in a PAR request as defined in alongside client_secret (with extra line breaks for display purposes only): The following example demonstrates usage of the client attestation mechanism at the Resource Server (with extra line breaks for display purposes only):

Authorization Server and Resource Server Metadata The Authorization Server SHOULD communicate support for authentication with Attestation-Based Client Authentication using a Client Attestation PoP JWT as the PoP by using the value attest_jwt_client_auth in the token_endpoint_auth_methods_supported within its published metadata. The Authorization Server SHOULD communicate support for authentication with Attestation-Based Client Authentication using a DPoP proof as the PoP by using the value attest_jwt_client_auth_dpop in the token_endpoint_auth_methods_supported within its published metadata. The client SHOULD fetch and parse the Authorization Server metadata and recognize Attestation-Based Client Authentication as a client authentication mechanism if either of the given token_endpoint_auth_methods_supported values are present. The Authorization Server or Resource Server SHOULD communicate supported algorithms for client attestations by using client_attestation_signing_alg_values_supported and client_attestation_pop_signing_alg_values_supported within its published metadata. This enables the client to validate that its client attestation is understood by the Authorization Server prior to authentication. The client MAY try to get a new client attestation with different algorithms. The Authorization Server or Resource Server MUST include client_attestation_signing_alg_values_supported and client_attestation_pop_signing_alg_values_supported in its published metadata if the Client Attestation PoP JWT mechanism is used. The Authorization Server or Resource Server MUST include dpop_signing_alg_values_supported as defined in , if DPoP is used as the Proof of Possession in combined mode. The Authorization Server or Resource Server MAY signal that it requires a Client Attestation as an additional security signal as described in . The Authorization Server includes the client_attestation_pop_methods_supported metadata parameter, containing a JSON array of the Proof of Possession methods it accepts, in its metadata as defined in . The Resource Server uses the same client_attestation_pop_methods_supported parameter in its metadata as defined in . The Proof of Possession method values are registered in the "OAuth Client Attestation Proof-of-Possession Methods" registry established by this specification (see ).

Client Metadata This section defines client metadata parameters for use with attestation-based client authentication. As described in , client metadata defines a general data model for Clients that is useful even when the Dynamic Client Registration Protocol is not being used. A Client MAY use these values to compare its own capabilities against the Authorization Server or Resource Server metadata defined in to determine whether it can interoperate with a given server prior to attempting authentication. A Client that supports attestation-based client authentication as defined in this specification indicates this by using the value attest_jwt_client_auth or attest_jwt_client_auth_dpop in the token_endpoint_auth_method client metadata parameter defined in . In addition, the following client metadata parameters are defined:

• client_attestation_signing_alg_values_supported: OPTIONAL. JSON array containing a list of the JWS alg values (as defined in ) supported by the Client for signing the Client Attestation JWT. The value none MUST NOT be present.
• client_attestation_pop_signing_alg_values_supported: OPTIONAL. JSON array containing a list of the JWS alg values (as defined in ) supported by the Client for signing the Client Attestation PoP JWT. The values none and any symmetric algorithms MUST NOT be present.
• client_attestation_pop_methods_supported: OPTIONAL. JSON array of case-sensitive strings, each identifying a Proof of Possession method supported by the Client, as registered in the "OAuth Client Attestation Proof-of-Possession Methods" registry established by this specification (see ).

These client metadata values are advertisements of Client capability. The Authorization Server or Resource Server enforces its own accepted algorithm and Proof of Possession method policies independently, and is not required to consult these values when validating an incoming request.

Implementation Considerations

DPoP Combined Mode Considerations When using DPoP combined mode, the key used for client authentication and token binding is shared. This may be undesirable depending on the deployment considerations of the Client. Conversely, the benefits of this approach are as follows:

• It authenticates (attests) the DPoP key used for sender-constraining tokens against the Client deployment.
• It reduces implementation complexity for the Client by minimizing the number of JWTs that need to be constructed or validated in a request.
• It reduces run-time costs for the Client by minimizing the number of cryptographic operations that need to be constructed in a request, especially if the keys are in a remote and/or hardware-backed key storage.

Reuse of a Client Attestation JWT Implementers should be aware that the design of this authentication mechanism deliberately allows for a Client Instance to re-use a single Client Attestation JWT in multiple interactions/requests with an Authorization Server or Resource Server, whilst producing a fresh Client Attestation PoP JWT. Client deployments should consider this when determining the validity period for issued Client Attestation JWTs as this ultimately controls how long a Client Instance can re-use a single Client Attestation JWT.

Refresh token binding Authorization servers issuing a refresh token in response to a token request using the client attestation mechanism as defined by this specification MUST bind the refresh token to the Client Instance, and NOT just the client as specified in . To prove this binding, the Client Instance MUST use the client attestation mechanism when refreshing an access token. Unless a profile specifies otherwise as described in , the refresh token MUST be bound to the Client Instance Key, and the Client Instance MUST use the same key that was present in the cnf claim of the Client Attestation that was used when the refresh token was issued.

Binding of OAuth protocol artifacts Authorization servers using Attestation-Based Client Authentication are RECOMMENDED to bind relevant protocol artifacts to the Client Instance and its associated public key where possible, and NOT just the client as specified in . Note that this only applies if Attestation-Based Client Authentication is used as Client Authentication. Examples of these artifacts include but are not limited to:

• The authorization_code as specified in .
• The auth_req_id as specified in section 7.3 .

How this binding is established and then proven is specific to the protocol artifact. For example establishing binding to an authorization_code involves the client instance using client attestation before the user is redirected to the Authorization Endpoint (for example by using PAR, ), and proving binding of the authorization_code to the Client Instance involves using the client attestation mechanism to authenticate at the token endpoint when performing the authorization code grant.

Web Server Default Maximum HTTP Header Sizes Because the Client Attestation and Client Attestation PoP are communicated using HTTP headers, implementers should consider that web servers may have a default maximum HTTP header size configured which could be too low to allow conveying a Client Attestation and or Client Attestation PoP in an HTTP request. It should be noted, that this limit is not given by the HTTP , but instead web server implementations commonly set a default maximum size for HTTP headers. As of 2024, typical limits for modern web servers configure maximum HTTP headers as 8 kB or more as a default.

Rotation of Client Instance Key This specification does not provide a mechanism to rotate the Client Instance Key in the Client Attestation JWT's "cnf" claim. If the Client Instance needs to use a new Client Instance Key for any reason, then it MUST request a new Client Attestation JWT from its Client Attester.

Replay Attack Detection Authorization Server or Resource Servers implementing measures to detect replay attacks as described in require efficient data structures to manage large amounts of challenge or jti values for use cases with high volumes of transactions. To limit the size of the data structure, the Authorization Server or Resource Server should use a sliding window, allowing Client Attestation PoPs within a certain time window, in which the seen challenge or jti values are stored, but discarded afterwards. The allowed window is determined by the iat of the Client Attestation PoP and the sliding window time duration chosen by the Authorization Server or Resource Server. To ensure security, the Authorization Server or Resource Server MUST first evaluate the iat of the Client Attestation PoP and reject any Client Attestation PoP whose iat falls outside this time window. Using such a data structure, the Authorization Server or Resource Server performs the following operations:

• search for the challenge or jti value of the Client Attestation PoP to validate whether it has been previously seen, and reject the Client Attestation PoP if it has
• insert the challenge or jti value of the Client Attestation PoP once it has passed all other checks
• delete challenge or jti values after they have passed the sliding time window

A trie (also called prefix tree), or a patricia trie (also called radix tree) are RECOMMENDED data structures to implement such a mechanism. Note that this seen-values mechanism is only needed when replay detection relies on a jti value or on a challenge obtained from the challenge endpoint. When the Authorization Server or Resource Server issues a challenge bound to a specific Client Instance session (see ), it can instead validate the Client Attestation PoP against the single challenge value expected for that session, without maintaining a seen-values data structure. Note that for the combined mode, the nonce and jti claims of the DPoP proof are used instead of the challenge and jti claims of the Client Attestation PoP.

Trust Management and Key Resolution The mechanisms by which the Authorization Server establishes trust in the Client Attester, and by which it obtains the public keys used to verify Client Attestation JWTs, are out of scope of this specification. Attestation-Based Client Authentication protects the integrity of Client Attestations using either Message Authentication Codes (MACs) or digital signatures. When digital signatures are used, the Authorization Server needs to be able to obtain the corresponding public key, either through pre-configuration or through dynamic discovery. Examples of trust management approaches include:

• Public Key Infrastructure (PKI) and trust lists.
• Pre-shared or out-of-band negotiated configuration (e.g., keys, URLs).

Specifications, profiles, and ecosystems built on top of Attestation-Based Client Authentication SHOULD adopt one of the following mechanisms to resolve the public key used to verify a Client Attestation JWT:

• The x5c header parameter, as defined in , conveys an X.509 certificate chain in the JOSE header of each Client Attestation. Trust is established by validating the chain against a configured trust anchor.
• The kid header parameter combined with the jku header parameter, as defined in and . The Authorization Server retrieves a JWK Set from the URL indicated by jku and selects the key identified by kid. This approach is self-contained but requires an additional HTTP request, and trust must be established in the jku URL.
• The kid header parameter combined with Client Metadata or other pre-shared information. Client Metadata, as defined in , includes a jwks_uri parameter which, together with kid, enables resolution of the verification key.

Privacy Considerations

Client Instance Tracking Across Authorization Servers or Resource Servers Implementers should be aware that using the same client attestation across multiple Authorization Servers or Resource Servers could result in correlation of the end user using the Client Instance through claim values (including the Client Instance Key in the cnf claim). Client deployments are therefore RECOMMENDED to use different Client Attestation JWTs with different Client Instance Keys across different Authorization Servers or Resource Servers.

Security Considerations The guidance provided by and applies.

Replay Attacks An Authorization/Resource Server SHOULD implement measures to detect replay attacks by the Client Instance. In the context of this specification, this means to detect that an attacker is resending the same Client Attestation PoP JWT in multiple requests. The following options are RECOMMENDED for this client authentication method:

• The Authorization/Resource Server manages a list of witnessed jti values of the Client Attestation PoP JWT for the time window of which the JWT would be considered valid. This sliding time window is based on the iat of the Client Attestation PoP and the duration chosen by the Authorization/Resource Server. If any Client Attestation PoP JWT would be replayed, the Authorization/Resource Server would recognize the jti value in the list and respond with an authentication error. Details how to implement such a data structure to maintain jti values is given in .
• The Authorization/Resource Server provides a challenge as an OAuth-Client-Attestation-Challenge in the challenge endpoint to the Client Instance and the Client uses it as a challenge value in the Client Attestation PoP JWT. The Authorization/Resource Server may choose to:
  • manage a list of witnessed challenge values, similar to the previously described jti approach. Details how to implement such a data structure to maintain challenge values is given in . This guarantees stronger replay protection with a challenge chosen by the Authorization/Resource Server itself, at the potential cost of an additional round-trip.
  • use self-contained challenges while not storing the seen challenges. This approach scales well, while only guaranteeing freshness, but no replay protection within the limited time-window chosen by the Authorization/Resource Server.
• The Authorization/Resource Server generates a challenge that is bound to the Client Instance's session, such that a specific challenge in the Client Attestation PoP JWT is expected and validated. The Authorization/Resource Server sends the challenge as part of another previous response to the Client Instance.

Note that protocols that provide a challenge as part of a previous response should provide a clear indicator for clients when this feature is used. This makes it easier for client implementations to deal with proper state handling. This can be implicit by always mandating support for this feature or via some metadata that allows the client to detect support for this feature for a specific server. Because clock skews between servers and clients may be large, Authorization/Resource Servers MAY limit Client Attestation PoP lifetimes by using server-provided challenge values containing the time at the server rather than comparing the client-supplied iat time to the time at the server. Challenges created in this way yield the same result even in the face of arbitrarily large clock skews. In any case the Authorization/Resource Server SHOULD ensure the freshness of the Client Attestation PoP by checking either the iat claim or if present the server provided challenge, is within an acceptable time window. The approach using a challenge explicitly provided by the Authorization/Resource Server gives stronger replay attack detection guarantees, however support by the Authorization/Resource Server is OPTIONAL to simplify mandatory implementation requirements. The jti value is mandatory and hence acts as a default fallback.

Client Attestation Protection This specification allows both, digital signatures using asymmetric cryptography, and Message Authentication Codes (MAC) to be used to protect Client Attestation JWTs. Implementers should only use MACs to secure the integrity of Client Attestation JWTs if they fully understand the risks of MACs when compared to digital signatures and especially the requirements of their use-case scenarios. These use-cases typically represent deployments where the Client Attester and Authorization Server have a trust relationship and the possibility to securely exchange keys out of band or are the same entity and no other entity needs to verify the Client Attestations. We expect most deployments to use digital signatures for the protection of Client Attestations, and implementers SHOULD default to digital signatures if they are unsure.

Considerations for Profiling this specification Use cases, ecosystems or other specifications that utilize Attestation-Based Client Authentication may profile this specification. A profile MUST define how an Authorization Server or Resource Server determines that the profile applies to a given request (which could also be an out-of-band mechanism). A profile MAY deviate on the following points:

• The type of the Client Attestation JWT: a profile MAY redefine a typ header parameter value other than oauth-client-attestation+jwt (see ) in order to distinguish profile-specific Client Attestations. Client Attestations are still unambiguously transferred by the OAuth-Client-Attestation HTTP header.
• The subject of the Client Attestation JWT: a profile MAY redefine the meaning of the sub claim (see ) and how a client_id maps to Client Instances. Such a profile MUST define how the checks that rely on sub matching the client_id are replaced, in particular those in and .
• The binding of refresh tokens: a profile MAY redefine the refresh token binding described in if its use case does not allow binding refresh tokens to the Client Instance Key. Such a profile MUST define what the refresh token is bound to instead and how that binding is proven when the refresh token is used.

All other requirements of this specification continue to apply unchanged.

Relation to RATS The Remote Attestation Procedures (RATS) architecture defined by has some commonalities to this document. The flow specified in this specification relates to the "Passport Model" in RATS. However, while the RATS ecosystem gives explicit methods and values how the RATS Attester proves itself to the Verifier, this is deliberately out of scope for Attestation-Based Client Authentication. Additionally, the terminology between RATS and OAuth is different:

• a RATS "Attester" relates to an OAuth "Client"
• a RATS "Relying Party" relates to an OAuth "Authorization Server or Resource Server"
• a RATS "Verifier" relates to the "Client Attester" defined in this specification
• a RATS "Attestation Result" relates to the "Client Attestation JWT" defined by this specification
• a RATS "Endorser", "Reference Value Provider", "Endorsement", "Evidence" and "Policies and Reference Values" are out of scope for this specification

IANA Considerations

OAuth Extensions Error Registration This specification requests registration of the following values in the IANA "OAuth Extensions Error Registry" registry of established by .

• Error Name: use_attestation_challenge
• Error Usage Location: token error response, resource access error response
• Related Protocol Extension: OAuth 2.0 Attestation-Based Client Authentication
• Change Controller: IETF
• Specification Document(s): of this specification

• Error Name: use_fresh_attestation
• Error Usage Location: token error response, resource access error response
• Related Protocol Extension: OAuth 2.0 Attestation-Based Client Authentication
• Change Controller: IETF
• Specification Document(s): of this specification

• Error Name: invalid_client_attestation
• Error Usage Location: token error response, resource access error response
• Related Protocol Extension: OAuth 2.0 Attestation-Based Client Authentication
• Change Controller: IETF
• Specification Document(s): of this specification

OAuth Authorization Server Metadata Registration This specification requests registration of the following values in the IANA "OAuth Authorization Server Metadata" registry of established by .

• Metadata Name: challenge_endpoint
• Metadata Description: URL of the authorization server's challenge endpoint which is used to obtain a fresh challenge for usage in client authentication methods such as client attestation.
• Change Controller: IETF
• Specification Document(s): of this specification

• Metadata Name: client_attestation_signing_alg_values_supported
• Metadata Description: JSON array containing a list of the JWS signing algorithms supported by the authorization server for the signature on the Client Attestation JWT.
• Change Controller: IETF
• Specification Document(s): of this specification

• Metadata Name: client_attestation_pop_signing_alg_values_supported
• Metadata Description: JSON array containing a list of the JWS signing algorithms supported by the authorization server for the signature on the Client Attestation PoP JWT.
• Change Controller: IETF
• Specification Document(s): of this specification

• Metadata Name: client_attestation_pop_methods_supported
• Metadata Description: JSON array of strings, each identifying a Proof of Possession method the authorization server accepts when requiring Clients to present a Client Attestation as an additional security signal. If omitted, presenting a Client Attestation is not required.
• Change Controller: IETF
• Specification Document(s): of this specification

OAuth Protected Resource Metadata Registration This specification requests registration of the following values in the IANA "OAuth Protected Resource Metadata" registry of established by .

• Metadata Name: challenge_endpoint
• Metadata Description: URL of the protected resource's challenge endpoint which is used to obtain a fresh challenge for usage in client authentication methods such as client attestation.
• Change Controller: IETF
• Specification Document(s): of this specification

• Metadata Name: client_attestation_signing_alg_values_supported
• Metadata Description: JSON array containing a list of the JWS signing algorithms supported by the protected resource for the signature on the Client Attestation JWT.
• Change Controller: IETF
• Specification Document(s): of this specification

• Metadata Name: client_attestation_pop_signing_alg_values_supported
• Metadata Description: JSON array containing a list of the JWS signing algorithms supported by the protected resource for the signature on the Client Attestation PoP JWT.
• Change Controller: IETF
• Specification Document(s): of this specification

• Metadata Name: client_attestation_pop_methods_supported
• Metadata Description: JSON array of strings, each identifying a Proof of Possession method the protected resource accepts when requiring Clients to present a Client Attestation as an additional security signal. If omitted, presenting a Client Attestation is not required.
• Change Controller: IETF
• Specification Document(s): of this specification

OAuth Dynamic Client Registration Metadata Registration This specification requests registration of the following values in the IANA "OAuth Dynamic Client Registration Metadata" registry of established by .

• Client Metadata Name: client_attestation_signing_alg_values_supported
• Client Metadata Description: JSON array containing a list of the JWS signing algorithms supported by the Client for signing the Client Attestation JWT.
• Change Controller: IETF
• Specification Document(s): of this specification

• Client Metadata Name: client_attestation_pop_signing_alg_values_supported
• Client Metadata Description: JSON array containing a list of the JWS signing algorithms supported by the Client for signing the Client Attestation PoP JWT.
• Change Controller: IETF
• Specification Document(s): of this specification

• Client Metadata Name: client_attestation_pop_methods_supported
• Client Metadata Description: JSON array of strings, each identifying a Proof of Possession method supported by the Client.
• Change Controller: IETF
• Specification Document(s): of this specification

OAuth Client Attestation Proof-of-Possession Methods Registry This specification establishes the IANA "OAuth Client Attestation Proof-of-Possession Methods" registry. This registry lists the Proof of Possession methods that a Client may use to demonstrate possession of the Client Instance Key, referenced by the client_attestation_pop_methods_supported metadata parameter defined in and . Client Attestation Proof-of-Possession Methods are registered by Specification Required after a two-week review period on the oauth-ext-review@ietf.org mailing list, on the advice of one or more Designated Experts. To allow for the allocation of values prior to publication of the final version of a specification, the designated experts may approve registration once they are satisfied that the specification will be completed and published. However, if the specification is not completed and published in a timely manner, as determined by the designated experts, the designated experts may request that IANA withdraw the registration. Registration requests sent to the mailing list for review should use an appropriate subject (e.g., "Request to register Client Attestation PoP: example"). Within the review period, the designated experts will either approve or deny the registration request, communicating this decision to the review list and IANA. Denials should include an explanation and, if applicable, suggestions as to how to make the request successful. If the designated experts are not responsive, the registration requesters should contact IANA to escalate the process. Designated experts should apply at least the following criteria when reviewing proposed registrations:

• the mechanism should not duplicate existing functionality
• the mechanism is likely generally applicable, as opposed to being used for a single application
• the specification sufficiently describes how the Proof of Possession method works in combination with a Client Attestation

IANA must only accept registry updates from the designated experts and should direct all requests for registration to the review mailing list. In order to enable broadly informed review of registration decisions, there should be multiple designated experts to represent the perspectives of different applications using this specification. In cases where registration may be perceived as a conflict of interest for a particular expert, that expert should defer to the judgment of the other experts. The mailing list is used to enable public review of registration requests, which enables both designated experts and other interested parties to provide feedback on proposed registrations. Designated experts may allocate values prior to publication of the final specification. This allows authors to receive guidance from the designated experts early, so any identified issues can be fixed before the final specification is published.

Registration Template

• Method Name: The name of the Proof of Possession method, a case-sensitive ASCII string.
• Method Description: A brief description of the mechanism.
• Change Controller: For values registered by this specification, IETF.
• Specification document(s): A reference to the specification that defines the mechanism.

Initial Registry Content

• Method Name: attestation_pop_jwt
• Method Description: The Proof of Possession is a dedicated Client Attestation PoP JWT ("normal mode").
• Change Controller: IETF
• Specification document(s): of this specification

• Method Name: dpop_combined
• Method Description: The Proof of Possession is a DPoP proof serving as the combined Proof of Possession ("DPoP combined mode").
• Change Controller: IETF
• Specification document(s): of this specification

• Method Name: none
• Method Description: No Client Attestation is required. When a server includes this value, the Client MAY omit the Client Attestation.
• Change Controller: IETF
• Specification document(s): of this specification

Registration of attest_jwt_client_auth Token Endpoint Authentication Method This section registers the value "attest_jwt_client_auth" in the IANA "OAuth Token Endpoint Authentication Methods" registry established by OAuth 2.0 Dynamic Client Registration Protocol .

• Token Endpoint Authentication Method Name: "attest_jwt_client_auth"
• Change Controller: IESG
• Specification Document(s): of this specification

Registration of attest_jwt_client_auth_dpop Token Endpoint Authentication Method This section registers the value "attest_jwt_client_auth_dpop" in the IANA "OAuth Token Endpoint Authentication Methods" registry established by OAuth 2.0 Dynamic Client Registration Protocol .

• Token Endpoint Authentication Method Name: "attest_jwt_client_auth_dpop"
• Change Controller: IESG
• Specification Document(s): of this specification

HTTP Field Name Registration This section requests registration of the following scheme in the "Hypertext Transfer Protocol (HTTP) Field Name Registry" described in :

• Field Name: OAuth-Client-Attestation
• Status: permanent
• Structured Type: Item
• Specification document(s): of this specification

• Field Name: OAuth-Client-Attestation-PoP
• Status: permanent
• Structured Type: Item
• Specification document(s): of this specification

• Field Name: OAuth-Client-Attestation-Challenge
• Status: permanent
• Structured Type: Item
• Specification document(s): of this specification

Media Type Registration This section requests registration of the following media types in the "Media Types" registry in the manner described in . To indicate that the content is a Client Attestation JWT as defined by this specification:

• Type name: application
• Subtype name: oauth-client-attestation+jwt
• Required parameters: n/a
• Optional parameters: n/a
• Encoding considerations: 8bit; JWT values are encoded as a series of base64url encoded values (some of which may be the empty string) separated by period ('.') characters.
• Security considerations: See of this specification
• Interoperability considerations: n/a
• Published specification: this specification
• Applications that use this media type: Applications using this specification to convey a Client Attestation
• Fragment identifier considerations: n/a
• Additional information: n/a
• Person & email address to contact for further information: OAuth WG mailing list, oauth@ietf.org
• Intended usage: COMMON
• Restrictions on usage: none
• Author: OAuth WG mailing list, oauth@ietf.org
• Change controller: IETF
• Provisional registration? No

To indicate that the content is a Client Attestation PoP JWT as defined by this specification:

• Type name: application
• Subtype name: oauth-client-attestation-pop+jwt
• Required parameters: n/a
• Optional parameters: n/a
• Encoding considerations: 8bit; JWT values are encoded as a series of base64url encoded values (some of which may be the empty string) separated by period ('.') characters.
• Security considerations: See of this specification
• Interoperability considerations: n/a
• Published specification: this specification
• Applications that use this media type: Applications using this specification for updated status information of tokens
• Fragment identifier considerations: n/a
• Additional information: n/a
• Person & email address to contact for further information: OAuth WG mailing list, oauth@ietf.org
• Intended usage: COMMON
• Restrictions on usage: none
• Author: OAuth WG mailing list, oauth@ietf.org
• Change controller: IETF
• Provisional registration? No

JSON Web Token Claims Registration This specification requests registration of the following value in the IANA "JSON Web Token (JWT) Claims" registry established by .

• Claim Name: challenge
• Claim Description: Server-provided challenge for use in a proof of possession
• Change Controller: IETF
• Specification Document(s): of this specification

References Normative References This second document defines the general structure of the MIME media typing system and defines an initial set of media types. [STANDARDS-TRACK] The OAuth 2.0 authorization framework enables a third-party application to obtain limited access to an HTTP service, either on behalf of a resource owner by orchestrating an approval interaction between the resource owner and the HTTP service, or by allowing the third-party application to obtain access on its own behalf. This specification replaces and obsoletes the OAuth 1.0 protocol described in RFC 5849. [STANDARDS-TRACK] This specification describes how to use bearer tokens in HTTP requests to access OAuth 2.0 protected resources. Any party in possession of a bearer token (a "bearer") can use it to get access to the associated resources (without demonstrating possession of a cryptographic key). To prevent misuse, bearer tokens need to be protected from disclosure in storage and in transport. [STANDARDS-TRACK] JSON Web Signature (JWS) represents content secured with digital signatures or Message Authentication Codes (MACs) using JSON-based data structures. Cryptographic algorithms and identifiers for use with this specification are described in the separate JSON Web Algorithms (JWA) specification and an IANA registry defined by that specification. Related encryption capabilities are described in the separate JSON Web Encryption (JWE) specification. This specification defines mechanisms for dynamically registering OAuth 2.0 clients with authorization servers. Registration requests send a set of desired client metadata values to the authorization server. The resulting registration responses return a client identifier to use at the authorization server and the client metadata values registered for the client. The client can then use this registration information to communicate with the authorization server using the OAuth 2.0 protocol. This specification also defines a set of common client metadata fields and values for clients to use during registration. JSON Web Token (JWT) is a compact, URL-safe means of representing claims to be transferred between two parties. The claims in a JWT are encoded as a JSON object that is used as the payload of a JSON Web Signature (JWS) structure or as the plaintext of a JSON Web Encryption (JWE) structure, enabling the claims to be digitally signed or integrity protected with a Message Authentication Code (MAC) and/or encrypted. This specification describes how to declare in a JSON Web Token (JWT) that the presenter of the JWT possesses a particular proof-of- possession key and how the recipient can cryptographically confirm proof of possession of the key by the presenter. Being able to prove possession of a key is also sometimes described as the presenter being a holder-of-key. Many protocols make use of points of extensibility that use constants to identify various protocol parameters. To ensure that the values in these fields do not have conflicting uses and to promote interoperability, their allocations are often coordinated by a central record keeper. For IETF protocols, that role is filled by the Internet Assigned Numbers Authority (IANA). To make assignments in a given registry prudently, guidance describing the conditions under which new values should be assigned, as well as when and how modifications to existing values can be made, is needed. This document defines a framework for the documentation of these guidelines by specification authors, in order to assure that the provided guidance for the IANA Considerations is clear and addresses the various issues that are likely in the operation of a registry. This is the third edition of this document; it obsoletes RFC 5226. This specification defines a metadata format that an OAuth 2.0 client can use to obtain the information needed to interact with an OAuth 2.0 authorization server, including its endpoint locations and authorization server capabilities. JSON Web Tokens, also known as JWTs, are URL-safe JSON-based security tokens that contain a set of claims that can be signed and/or encrypted. JWTs are being widely used and deployed as a simple security token format in numerous protocols and applications, both in the area of digital identity and in other application areas. This Best Current Practices document updates RFC 7519 to provide actionable guidance leading to secure implementation and deployment of JWTs. This document defines procedures for the specification and registration of media types for use in HTTP, MIME, and other Internet protocols. This memo documents an Internet Best Current Practice. The Hypertext Transfer Protocol (HTTP) is a stateless application-level protocol for distributed, collaborative, hypertext information systems. This document describes the overall architecture of HTTP, establishes common terminology, and defines aspects of the protocol that are shared by all versions. In this definition are core protocol elements, extensibility mechanisms, and the "http" and "https" Uniform Resource Identifier (URI) schemes. This document updates RFC 3864 and obsoletes RFCs 2818, 7231, 7232, 7233, 7235, 7538, 7615, 7694, and portions of 7230. The Hypertext Transfer Protocol (HTTP) is a stateless application-level protocol for distributed, collaborative, hypertext information systems. This document specifies the HTTP/1.1 message syntax, message parsing, connection management, and related security concerns. This document obsoletes portions of RFC 7230. This document defines the pushed authorization request (PAR) endpoint, which allows clients to push the payload of an OAuth 2.0 authorization request to the authorization server via a direct request and provides them with a request URI that is used as reference to the data in a subsequent call to the authorization endpoint. This document describes a mechanism for sender-constraining OAuth 2.0 tokens via a proof-of-possession mechanism on the application level. This mechanism allows for the detection of replay attacks with access and refresh tokens. This specification defines a metadata format that an OAuth 2.0 client or authorization server can use to obtain the information needed to interact with an OAuth 2.0 protected resource. IANA n.d. IANA n.d. IANA n.d. IANA n.d. IANA n.d. In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. Informative References In network protocol exchanges, it is often useful for one end of a communication to know whether the other end is in an intended operating state. This document provides an architectural overview of the entities involved that make such tests possible through the process of generating, conveying, and evaluating evidentiary Claims. It provides a model that is neutral toward processor architectures, the content of Claims, and protocols. This specification defines the use of a JSON Web Token (JWT) Bearer Token as a means for requesting an OAuth 2.0 access token as well as for client authentication. This specification provides a framework for the use of assertions with OAuth 2.0 in the form of a new client authentication mechanism and a new authorization grant type. Mechanisms are specified for transporting assertions during interactions with a token endpoint; general processing rules are also specified. The intent of this specification is to provide a common framework for OAuth 2.0 to interwork with other identity systems using assertions and to provide alternative client authentication mechanisms. Note that this specification only defines abstract message flows and processing rules. In order to be implementable, companion specifications are necessary to provide the corresponding concrete instantiations. This specification defines a mechanism for the selective disclosure of individual elements of a JSON data structure used as the payload of a JSON Web Signature (JWS). The primary use case is the selective disclosure of JSON Web Token (JWT) claims. n.d.

Document History -11

• clarify that challenge support is optional, but that a server using challenges always provides a fresh challenge in the use_attestation_challenge error
• combined mode now exclusively uses the DPoP nonce mechanism
• allow the challenge endpoint response to convey a DPoP nonce
• add clarifications on AS combined mode handling & errors
• remove duplication challenge verification in Verifivation of Client Attestation PoP JWT
• fix IANA registry entries
• remove duplication challenge verification in Verification of Client Attestation PoP JWT
• add Client Metadata section defining for use by Clients
• register the new client metadata parameters in the IANA registry
• add considerations for profiling this draft
• mention that RFC7521 is not used

-10

• add client_attestation_pop_methods_supported Authorization Server and Resource Server metadata
• establish the "OAuth Client Attestation Proof-of-Possession Methods" registry
• allow proof of possession mechanisms defined by other/future specifications
• clarify that DPoP can be used alongside attest_jwt_client_auth and which validation rules apply
• add short note that dpop_jkt cannot be used with the combined mode
• update Client Attestation PoP JWT examples to use challenge instead of nonce and include the required iat claim
• clean up references
• fix IANA registrations
• editorial fixes
• add clarification on Client Attester
• remove replay attack consideration to reuse existing artifacts as challenge
• clarifications around implementation consideration for replay attack detection

-09

• restructure draft
• add section how to establish trust and resolve keys
• rephrasing of introduction text
• adding challenge request/response to graphic
• restructure and minor fixes to challenge section
• add mentioning or Resource Server, where applicable
• clarify that alg is required for Client Attestation JWT and Client Attestation PoP JWT

-08

• remove concatenated Serialization for Client Attestations
• update all examples (removal of iss and nbf)
• remove iss from Client Attestation JWT and Client Attestation PoP JWT
• add small security consideration sub-section for MAC-based deployments
• remove public clients reference and clarify this draft targets confidential clients
• clarify this may be a client authentication mechanism but also may be not
• add examples for RS usage and non client authentication
• Add note on protocols providing a challenge on previous responses
• add structured-type to iana header field registration requests
• moving Authorization Server metadata into it's own top level section
• editorial fixes

-07

• remove restrictions to not allow MAC-based algorithms
• require iat in Client Attestation PoP JWT
• clarify use_attestation_challenge and add invalid_client_attestation
• add client_attestation_signing_alg_values_supported and client_attestation_pop_signing_alg_values_supported to IANA registration
• add implementation consideration for Authorization Server Metadata
• clarify refresh token binding
• check client_id at PAR endpoint
• added use_fresh_attestation as an error to signal that the attestation was not deemed fresh enough by the server
• mandate the defined header fields if the attestation and pop are transferred via header fields

-06

• clarify client_id processing in token request with client attestation
• clarify usage of client attestation outside of oauth2 applications
• add oauth error response values invalid_client_attestation and use_attestation_challenge
• revert the HTTP OPTIONS mechanism to fetch nonces and add a dedicated challenge endpoint
• rename nonce to challenge
• rewrite security consideration on replay attacks
• add implementation consideration on replay attacks
• remove exp from Client Attestation PoP JWT
• add verification and processing rules

-05

• add nonce endpoint
• add metadata entry for nonce
• improve introduction
• rename client backend to client attester
• fix missing typ header in examples

-04

• remove key attestation example
• restructured JWT Claims for better readability
• added JOSE typ values for Client Attestation and Client Attestation PoP
• add RATS relation
• add concatenated representation without headers
• add PAR endpoint example
• fix PoP examples to include jti and nonce
• add iana http field name registration

-03

• remove usage of RFC7521 and the usage of client_assertion
• add new header-based syntax introducing Oauth-Client-Attestation and OAuth-Client-Attestation-PoP
• add Client Instance to the terminology and improve text around this concept

-02

• add text on the inability to rotate the Client Instance Key

-01

• Updated eIDAS example in appendix
• Removed text around jti claim in client attestation, refined text for its usage in the client attestation pop
• Refined text around cnf claim in client attestation
• Clarified how to bind refresh tokens to a Client Instance using this client authentication method
• Made it more explicit that the client authentication mechanism is general purpose making it compatible with extensions like PAR
• Updated acknowledgments
• Simplified the diagram in the introduction
• Updated references
• Added some guidance around replay attack detection

-00

• Initial draft

Acknowledgments We would like to thank Babis Routis, Brian Campbell, Dimitris Zarras, Filip Skokan, Francesco Marino, Frederik Krogsdal Jacobsen, Giuseppe De Marco, Joseph Heenan, Kristina Yasuda, Micha Kraus, Michael B. Jones, Takahiko Kawasaki, Timo Glastra and Torsten Lodderstedt for their valuable contributions to this specification.