]> MATTR

tobias.looker@mattr.global

paul.bastian@bdr.de

This specification defines a new method of client authentication for OAuth 2.0 by extending the approach defined in . This new method enables client deployments that are traditionally viewed as public clients to be able to authenticate with the authorization server through an attestation based authentication scheme. About This Document The latest revision of this draft can be found at . Status information for this document may be found at .

Introduction defines a way for a client to include an assertion in a token request to an authorization server for the purposes of client authentication. This specification uses this framework to define a new assertion type that provides a way for a client instance to authenticate itself with the authorization server through an assertion that is bound to a public key (for proof of possession). This assertion is designated with the name of Client Attestation in this draft. The following diagram depicts the overall architecture and protocol flow. | | | | (1) | | Client | (6) | Authorization | | | Instance |<--------->| Server | +------| | | | +---------------+ +---------------+ / \ | | | +-------+ (5) ]]> The following steps describe this OAuth flow: (1) The Client Instance generates a key (Client Instance Key) and optional further attestations (that are out of scope) to prove its authenticity to the Client Backend. (2) The Client Instance sends this data to the Client Backend in request for a Client Attestation JWT. (3) The Client Backend validates the Client Instance Key and optional further data. It 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 Backend responds to the Client Instance by sending the Client Attestation JWT. (5) The Client Instance generates a Proof of Possession (PoP) with the Client Instance Key. (6) The Client Instance sends both the Client Attestation JWT and the Client Attestation PoP JWT to the authorization server, e.g. within a token request. The authorization server validates the Client Attestation and thus authenticates the Client Instance. Note that the protocol for steps (2) and (4) and how the Client Instance authenticates to the Client Backend is out of scope of this specification. Note also that this specification can be utilized without the client having a backend server at all; in this case, each client instance will perform the functions described as being done by the backend for itself. This specification defines the format of the Client Attestation that a Client Instance uses to authenticate in its interactions with an authorization server, which is comprised of two key parts:

1. A Client Attestation JWT - typically produced by the client backend.
2. A Client Attestation Proof of Possession (PoP) - produced by the client instance.

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 backend which is bound to a key managed by a client instance which can then be used by the instance for client authentication.

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 Key:

A cryptographic, asymmetric key generated by the client instance and proven to the client backend. The public key is contained in the Client Attestation JWT and is used to sign the Client Attestation Proof of Possession.

Client Authentication To perform client authentication using this scheme, the client instance uses the following parameter values and encodings. The value of the "client_assertion_type" parameter (as defined in ) set to "urn:ietf:params:oauth:client-assertion-type:jwt-client-attestation". The value of the "client_assertion" parameter (as defined in ) set to a value containing two JWTs, separated by a '~' character. It MUST NOT contain more or less than precisely two JWTs separated by the '~' character. The first JWT MUST be the client attestation JWT defined in , the second JWT MUST be the client attestation PoP defined in . The following example demonstrates client authentication using this scheme during the presentation of an authorization code grant in an access token request (with extra line breaks for display purposes only):

JWT Format and Processing Requirements In order to authenticate the client using this scheme, the authorization server MUST validate BOTH the JWTs present in the "client_assertion" parameter according to the criteria below. It is RECOMMENDED that the authorization server validate the Client Attestation JWT prior to validating the Client Attestation PoP.

Client Attestation JWT The following rules apply to validating the client attestation JWT. Application of additional restrictions and policy are at the discretion of the authorization server.

1. The JWT MUST contain an "iss" (issuer) claim that contains a unique identifier for the entity that issued the JWT. In the absence of an application profile specifying otherwise, compliant applications MUST compare issuer values using the Simple String Comparison method defined in Section 6.2.1 of .
2. The JWT MUST contain a "sub" (subject) claim with a value corresponding to the "client_id" of the OAuth client.
3. The JWT MUST contain an "exp" (expiration time) claim that limits the time window during which the JWT can be used. The authorization server MUST reject any JWT with an expiration time that has passed, subject to allowable clock skew between systems.
4. The JWT MUST contain an "cnf" claim conforming that conveys the key to be used for producing the client attestation pop for client authentication with an authorization server. The key MUST be expressed using the "jwk" representation.
5. The JWT MAY contain an "nbf" (not before) claim that identifies the time before which the token MUST NOT be accepted for processing.
6. The JWT MAY contain an "iat" (issued at) claim that identifies the time at which the JWT was issued.
7. The JWT MAY contain other claims.
8. The JWT MUST be digitally signed using an asymmetric cryptographic algorithm. The authorization server MUST reject the JWT if it is using a Message Authentication Code (MAC) based algorithm. The authorization server MUST reject JWTs with an invalid signature.
9. The authorization 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.

Client Attestation PoP JWT The following rules apply to validating the Client Attestation JWT. Application of additional restrictions and policy are at the discretion of the Authorization Server.

1. The JWT MUST contain an "iss" (issuer) claim with a value corresponding to the "client_id" of the OAuth client.
2. The JWT MUST contain an "exp" (expiration time) claim that limits the time window during which the JWT can be used. The authorization server MUST reject any JWT with an expiration time that has passed, subject to allowable clock skew between systems. Note that the authorization server may reject JWTs with an "exp" claim value that is unreasonably far in the future.
3. The JWT MUST contain a "jti" (JWT ID) claim that provides a unique identifier for the token. The authorization server MAY ensure that JWTs are not replayed by maintaining the set of used "jti" values for the length of time for which the JWT would be considered valid based on the applicable "exp" instant.
4. The JWT MUST contain an "aud" (audience) claim containing a value that identifies the authorization server as an intended audience. The issuer identifier URL of the authorization server MUST be used as a value for an "aud" element to identify the authorization server as the intended audience of the JWT.
5. The JWT MAY contain an "nonce" claim containing a String value that is provided by the authorization server to associate the Client Attestation PoP JWT with a particular transaction and prevent replay attacks.
6. The JWT MAY contain an "nbf" (not before) claim that identifies the time before which the token MUST NOT be accepted for processing.
7. The JWT MAY contain an "iat" (issued at) claim that identifies the time at which the JWT was issued. Note that the authorization server may reject JWTs with an "iat" claim value that is unreasonably far in the past.
8. The JWT MAY contain other claims.
9. The JWT MUST be digitally signed using an asymmetric cryptographic algorithm. The authorization server MUST reject the JWT if it is using a Message Authentication Code (MAC) based algorithm. The authorization server MUST reject JWTs with an invalid signature.
10. The public key used to verify the JWT MUST be the key located in the "cnf" claim of the corresponding client attestation JWT.
11. The authorization 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.

Implementation Considerations

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, 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 "urn:ietf:params:oauth:client-assertion-type:jwt-client-attestation" client authentication method MUST bind the refresh token to the client instance, and NOT just the client as specified in section 6 . To prove this binding, the client instance MUST authenticate itself to the authorization server when refreshing an access token using the "urn:ietf:params:oauth:client-assertion-type:jwt-client-attestation" authentication method. The client MUST also use the same key that was present in the "cnf" claim of the client attestation that was used for client authentication when the refresh token was issued.

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 Backend.

Privacy Considerations

Client Instance Tracking Across Authorization Servers Implementers should be aware that using the same client attestation across multiple authorization servers could result in correlation of the end user using the client instance through claim values (including the public key in the cnf claim). Client deployments are therefore RECOMMENDED to use different client attestations across different authorization servers.

Security Considerations The guidance provided by and applies.

Replay Attack Detection The following mechanisms exist within this client authentication method in order to allow an authorization server to detect replay attacks for presented client attestation PoPs:

• The client uses "jti" (JWT ID) claims for the Client Attestation PoP JWT and the authorization server maintains a list of used (seen) "jti" values for the time of which the JWT would be considered valid based on the applicable "exp" claim. If any Client Attestation PoP JWT would be replayed, the authorization server would recognize the "jti" and respond with an authentication error.
• The authorization server provides a nonce for the particular transaction and the client uses it for the "nonce" claim in the Client Attestation PoP JWT. The authorization server validates that the nonce matches for the transaction. This approach may require an additional roundtrip in the protocol. The authorization server MUST ensure that the nonce provides sufficient entropy.
• The authorization server may expect the usage of a nonce in the Client Attestation PoP JWT, but instead of providing the nonce explicitly, the client may implicitly reuse an existing artefact, e.g. the authorization code. The authorization server MUST ensure that the nonce provides sufficient entropy.

The approach using a nonce explicitly provided by the authorization server gives stronger replay attack detection guarantees, however support by the authorization server is OPTIONAL to simplify mandatory implementation requirements. The "jti" method is mandatory and hence acts as a default fallback.

Appendix A IANA Considerations

Sub-Namespace Registration of urn:ietf:params:oauth:client-assertion-type:jwt-client-attestation This section registers the value "client-assertion-type:jwt-client-attestation" in the IANA "OAuth URI" registry established by "An IETF URN Sub-Namespace for OAuth" .

• URN: urn:ietf:params:oauth:client-assertion-type:jwt-client-attestation
• Common Name: OAuth 2.0 Attested Key-Based Client Authentication
• Change Controller: IESG
• Specification Document: TBC

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): TBC

References Normative References A Uniform Resource Identifier (URI) is a compact sequence of characters that identifies an abstract or physical resource. This specification defines the generic URI syntax and a process for resolving URI references that might be in relative form, along with guidelines and security considerations for the use of URIs on the Internet. The URI syntax defines a grammar that is a superset of all valid URIs, allowing an implementation to parse the common components of a URI reference without knowing the scheme-specific requirements of every possible identifier. This specification does not define a generative grammar for URIs; that task is performed by the individual specifications of each URI scheme. [STANDARDS-TRACK] 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. This document establishes an IETF URN Sub-namespace for use with OAuth-related specifications. This document is not an Internet Standards Track specification; it is published for informational purposes. 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 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. 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 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 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. n.d.

Additional Examples

Wallet Instance Attestation This non-normative example shows a client attestations used as an wallet instance attestation in the context of eIDAS 2.0 , e.g. to secure a Type-1 configuration credential. The additional claims describe the wallet's device binding und user binding capabilities and the achievable level of assurance.

Document History -02

• Add text on rotation of the confirmation 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 Brian Campbell, Francesco Marino, Guiseppe De Marco, Kristina Yasuda, Michael B. Jones, Takahiko Kawasaki and Torsten Lodderstedt for their valuable contributions to this specification.