]> MongoDB

ietf@justin.richer.org

Okta

aaron@parecki.com

Security OAUTH Internet-Draft This extension to the OAuth 2.0 authorization framework defines a method for using HTTP Message Signatures to bind access tokens to keys held by OAuth 2.0 clients. Discussion Venues Discussion of this document takes place on the Web Authorization Protocol Working Group mailing list (oauth@ietf.org), which is archived at . Source for this draft and an issue tracker can be found at .

Introduction The OAuth 2.0 framework provides methods for clients to get delegated access tokens from an authorization server for accessing protected resources. OAuth access tokens can be bearer tokens, or bound to a variety of mechanisms including mutual TLS, DPoP, or other presentation mechanisms. Bearer tokens are simple to implement but also have the significant security downside of allowing anyone who sees the access token to use that token. defines a generic mechanism that is used to sign HTTP requests and responses. This specification defines means to bind access tokens to a key held by the client, a token type value, a token response for indicating that a token is meant to be used with presentation, and a method for presenting bound access tokens in HTTP requests using . This work complements and builds on experience with and , as well as implementations of , a spiritual predecessor to this specification and other forms of OAuth proof-of-possession work. [[ Editor's note: we want to give developers clear guidance on when to use HTTPSig vs. DPoP vs. mTLS vs. Bearer vs. whatever else ]]

Terminology 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. This document contains non-normative examples of partial and complete HTTP messages, JSON structures, URLs, query components, keys, and other elements. Some examples use a single trailing backslash '' to indicate line wrapping for long values, as per . The \ character and leading spaces on wrapped lines are not part of the value.

Requesting an HTTP Message Signature Bound Access Token To bind an access token to a key, the AS needs to know which key to bind to which token. This specification defines two common methods depending on the needs of the client:

• A static method that depends on key material available as part of the client registration
• A runtime method that allows a client to introduce key material during the token request phase of

As part of its registration, a client MUST indicate which method it will use, using either the httpsig_key_binding_method client registration metadata parameter defined (TBD) in when using Dynamic Client Registration () or Client ID Metadata Document (), or via an out of band method. [[ Editor's note: do we want to add an AS/RS metadata parameter to signal support for each type? ]] [[ Editor's note: Are there any other patterns of key introduction we should cover? I put PAR in the appendix as a note. ]]

Pre-Registration of Keys A client pre-registering its keys for binding MUST include the key in its registered jwks value or make it available from its jwks_uri endpoint. The JWK MUST have a kid field and MUST indicate a signing algorithm in its alg field. The key ID for the public key used for HTTP Message Signature bound access tokens MUST be identified using the httpsig_bound_access_token_kid field in the client's metadata. [[ Editor's note: do we want to have a client field for the signing alg or just leave that to the key all the time? I prefer to keep it in the key. ]] A pre-registered key MAY be a shared secret (such as for use in an HMAC signature), but public key cryptography is RECOMMENDED. Note that pre-registration can occur statically or dynamically (such as by using ), as long as the key is associated with the client's client_id before the token request is made.

Example Client Registration A client can publish the key binding parameters as part of a alongside its jwks or jwks_uri values. For example, a client with the client_id value https://client.example.com/client-metadata.json would publish the following document at that URL, indicating that it uses a pre-registered key:

Token Request Key Introduction Instead of pre-registering a key, a client can introduce its key during the token request in the same fashion as . The client MUST present its public key in the Signature-Key header field. The field is an HTTP Structured Field consisting of a Binary value containing the bytes of the serialized form of the key material. The JWK MUST have a kid field. The key MUST be a public key (and neither a private key nor a shared secret key). The JWK MUST have an alg value that indicates a signature algorithm. For example, the following JWK public key: Can be encoded to the following Signature-Key field value (this example uses a compact JSON serialization that removes whitespace): [[ Editor's note: this is a really awkward way to encode a JWK. We could try to break apart the JSON but there's not a 1:1 map to HTTP Structured Fields we can rely on. We could just put the minified JSON into a string but the double quotes would need to be escaped. This is the least bad version I could come up with right now. ]]

Token Request The presence of an HTTP Message Signature with the tag httpsig-oauth-token-request indicates that the client is requesting a bound token. The client MUST include a message signature of the indicated key. Additionally, the client MUST calculate and include the digest of the request body and include it as the Content-Digest header defined in . For example, a form-encoded request body consisting of: Would create the following Content-Digest header: A client using this method MUST sign the token endpoint request using with the appropriate key. The covered components MUST include:

• @method the HTTP method of the request
• @target-uri the full request URI of the request (note that this includes the scheme, authority, path, and query)
• content-digest the digest of the request body

If a signature key is presented at runtime as described in , the covered components MUST include:

• signature-key the encoded public key used to sign this request

The covered components MUST include the client's authentication, if available. If using HTTP Basic, this means including the authorization field. The signature MUST include the following parameters:

• created a timestamp for signature creation; this MUST be within a small number of seconds of issuance (e.g. 30 seconds to account for clock skew)
• nonce a random unique value that the AS can use to prevent signature replay within the small validity time window
• tag a string indicating that this is being used for requesting a bound token, MUST be the value "httpsig-oauth-token-request"
• keyid the kid value for the key to be used for binding the token; if client uses pre-registered keys as in , the value MUST match the httpsig_bound_access_token_kid value; if the key is presented at runtime as in , the value MUST match the kid of the JWK in the Signature-Key field

The signature algorithm MUST be derived from the indicated key. The alg signature parameter MUST NOT be used. An example request to the token endpoint (using a runtime-provided key here) can look like the following:

Issuing an HTTP Message Signature Bound Access Token The AS MUST validate the signature of the token request sent in against the identified key and the algorithm associated with that key. The request MUST fail with an error if any of the following occur:

• The key named in kid cannot be found or is not associated with the requesting client
• There is more than one signature with the tag "httpsig-oauth-token-request"
• The created value of the signature is too far in the past
• The nonce value is used more than once within the validity window of the signature

When issuing an access token bound to a key using HTTP Message Signatures, the AS associates the granted token with the key used in the requesting signature. All presentations of this token at any RS MUST contain an HTTP message signature as described in . An HTTP Message Signature bound access token MUST have a token_type value of httpsig. The client MUST associate this returned access token with the key used to make the requst. [[ Editor's note: we should define confirmation methods for access tokens here, including JWT values and introspection response values to allow the RS to verify the signature w/o the client's registration information. Leaving the following sections as placeholders. ]]

Encoding Confirmation in a JWT

Returning Confirmation in Token Introspection

Presenting an HTTP Message Signature Bound Access Token HTTP Message Signature bound access token MUST be presented in an HTTP Authorization field using the HTTPSig authorization scheme. Note that HTTP authorization schemes defined in are case-insensitive, and so all the following are equivalent: When presenting an HTTP Message Signature bound access token to an RS, the client MUST include a signature compliant with . The covered components MUST include:

• @method the HTTP method of the request
• @target-uri the full request URI of the request (note that this includes the scheme, authority, path, and query)
• authorization the access token value being presented

The RS MAY require additional components to be covered by the signature, and the client MUST include any additional fields or components of the HTTP request that are relevant to the security of the RS. For example, if the API being served by the RS declares that incoming content type makes a material difference, the RS SHOULD require signing of the Content-Type header in addition to the above. The request MAY include multiple signatures to serve different needs. If the request includes an entity body (such as a POST, PUT, or QUERY), the client SHOULD calculate the digest as per and also sign the digest header (such as Content-Digest). The signature MUST include the following parameters:

• created a timestamp for signature creation; this MUST be within a small number of seconds of issuance (e.g. 30 seconds to account for clock skew)
• nonce a random unique value that the AS can use to prevent signature replay within the small validity time window
• tag a string indicating that this is being used for requesting a bound token, MUST be the value "httpsig-oauth"
• keyid the kid value for the key used to sign the request

The client MUST NOT include an alg signature parameter. For example, the following signed request includes a signature with the needed parameters:

Validating an HTTP Message Signature Bound Access Token Request In order for a request protected by an HTTP Message Signature bound access token to be considered valid, the RS MUST perform the following checks:

• The presented signature validates using the key associated with the token
• The signature validates using the algorithm associated with the key
• The created value is not too far in the past (e.g. 30 seconds to account for clock skew and network delays)
• The nonce value has not been previously used within the time validity window of this request
• The tag value is "httpsig-oauth"
• The covered components and parameters include all items enumerated in

If the request includes an entity body (such as a POST, PUT, or QUERY) and a digest as per , the RS MUST validate the digest. If the request includes multiple signatures tagged "httpsig-oauth", all signatures MUST be validated. For example, to validate the request: The RS determines the key bound to the token and validates the kid value against that key. The RS determines the algorithm from the key and performs signature validation per on the In this example, the client has a key with the kid value of test-key-rsa-pss which uses the JWA alg value of PS512. The signature input string is: This results in the following signed HTTP message, including the access token. An RS receiving such a signed message and a bound access token MUST verify the HTTP Message Signature as described in . The RS MUST verify that all required portions of the HTTP request are covered by the signature by examining the contents of the signature parameters.

Acknowledgements

IANA Considerations [[ TBD: register the token type and new parameters into their appropriate registries, as well as the JWT and introspection parameters needed for confirmation methods. ]]

Security Considerations [[ TBD. ]]

• All requests have to be over TLS or equivalent as per .
• Leakage of a private key alongside a token allows for re-presentation of that token.
• Insufficient coverage of a message allows a signature to be attached to a different message.
• Failure to check derived attributes allows a signature to be replayed.
• Signatures could be replayed outside of their vailidty window if not checked.

Privacy Considerations [[ TBD. ]]

• Re-use of a public-key for tokens at multiple RS's can allow tracking of a client/user combination based on the key identity.

References Normative References This document formally deprecates Transport Layer Security (TLS) versions 1.0 (RFC 2246) and 1.1 (RFC 4346). Accordingly, those documents have been moved to Historic status. These versions lack support for current and recommended cryptographic algorithms and mechanisms, and various government and industry profiles of applications using TLS now mandate avoiding these old TLS versions. TLS version 1.2 became the recommended version for IETF protocols in 2008 (subsequently being obsoleted by TLS version 1.3 in 2018), providing sufficient time to transition away from older versions. Removing support for older versions from implementations reduces the attack surface, reduces opportunity for misconfiguration, and streamlines library and product maintenance. This document also deprecates Datagram TLS (DTLS) version 1.0 (RFC 4347) but not DTLS version 1.2, and there is no DTLS version 1.1. This document updates many RFCs that normatively refer to TLS version 1.0 or TLS version 1.1, as described herein. This document also updates the best practices for TLS usage in RFC 7525; hence, it is part of BCP 195. Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS) are used to protect data exchanged over a wide range of application protocols and can also form the basis for secure transport protocols. Over the years, the industry has witnessed several serious attacks on TLS and DTLS, including attacks on the most commonly used cipher suites and their modes of operation. This document provides the latest recommendations for ensuring the security of deployed services that use TLS and DTLS. These recommendations are applicable to the majority of use cases. RFC 7525, an earlier version of the TLS recommendations, was published when the industry was transitioning to TLS 1.2. Years later, this transition is largely complete, and TLS 1.3 is widely available. This document updates the guidance given the new environment and obsoletes RFC 7525. In addition, this document updates RFCs 5288 and 6066 in view of recent attacks. This document defines HTTP fields that support integrity digests. The Content-Digest field can be used for the integrity of HTTP message content. The Repr-Digest field can be used for the integrity of HTTP representations. Want-Content-Digest and Want-Repr-Digest can be used to indicate a sender's interest and preferences for receiving the respective Integrity fields. This document obsoletes RFC 3230 and the Digest and Want-Digest HTTP fields. The Hypertext Transfer Protocol (HTTP) is a stateless application-level protocol for distributed, collaborative, hypertext information systems. This document defines HTTP caches and the associated header fields that control cache behavior or indicate cacheable response messages. This document obsoletes RFC 7234. A JSON Web Key (JWK) is a JavaScript Object Notation (JSON) data structure that represents a cryptographic key. This specification also defines a JWK Set JSON data structure that represents a set of JWKs. Cryptographic algorithms and identifiers for use with this specification are described in the separate JSON Web Algorithms (JWA) specification and IANA registries established by that specification. 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] This document describes a set of data types and associated algorithms that are intended to make it easier and safer to define and handle HTTP header and trailer fields, known as "Structured Fields", "Structured Headers", or "Structured Trailers". It is intended for use by specifications of new HTTP fields. This document obsoletes RFC 8941. This document describes OAuth client authentication and certificate-bound access and refresh tokens using mutual Transport Layer Security (TLS) authentication with X.509 certificates. OAuth clients are provided a mechanism for authentication to the authorization server using mutual TLS, based on either self-signed certificates or public key infrastructure (PKI). OAuth authorization servers are provided a mechanism for binding access tokens to a client's mutual-TLS certificate, and OAuth protected resources are provided a method for ensuring that such an access token presented to it was issued to the client presenting the token. This document describes a mechanism for creating, encoding, and verifying digital signatures or message authentication codes over components of an HTTP message. This mechanism supports use cases where the full HTTP message may not be known to the signer and where the message may be transformed (e.g., by intermediaries) before reaching the verifier. This document also describes a means for requesting that a signature be applied to a subsequent HTTP message in an ongoing HTTP exchange. 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 document specifies the Time Zone Information Format (TZif) for representing and exchanging time zone information, independent of any particular service or protocol. Two media types for this format are also defined. This document replaces and obsoletes RFC 8536. 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 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. JavaScript Object Notation (JSON) is a lightweight, text-based, language-independent data interchange format. It was derived from the ECMAScript Programming Language Standard. JSON defines a small set of formatting rules for the portable representation of structured data. This document removes inconsistencies with other specifications of JSON, repairs specification errors, and offers experience-based interoperability guidance. The Hypertext Transfer Protocol (HTTP) is a stateless application- level protocol for distributed, collaborative, hypermedia information systems. This document defines the HTTP Authentication framework. 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. This document defines two strategies for handling long lines in width-bounded text content. One strategy, called the "single backslash" strategy, is based on the historical use of a single backslash ('\') character to indicate where line-folding has occurred, with the continuation occurring with the first character that is not a space character (' ') on the next line. The second strategy, called the "double backslash" strategy, extends the first strategy by adding a second backslash character to identify where the continuation begins and is thereby able to handle cases not supported by the first strategy. Both strategies use a self-describing header enabling automated reconstitution of the original content. Informative References Ping Identity ARM Limited This document a method for offering data origin authentication and integrity protection of HTTP requests. To convey the relevant data items in the request a JSON-based encapsulation is used and the JSON Web Signature (JWS) technique is re-used. JWS offers integrity protection using symmetric as well as asymmetric cryptography. Okta This specification defines a mechanism through which an OAuth client can identify itself to authorization servers, without prior dynamic client registration or other existing registration. This is through the usage of a URL as a client_id in an OAuth flow, where the URL refers to a document containing the necessary client metadata, enabling the authorization server to fetch the metadata about the client as needed. This specification proposes an additional response secured by JSON Web Token (JWT) for OAuth 2.0 Token Introspection.

Document History

• -02
  • Editorial fixes
  • Added example of client registration metadata parameter in CIMD
• -01
  • Added key binding semantics
  • Updated references
  • Updated presentation requirements
  • Added appendix for potential future work
  • Added some basic security and privacy considerations, to be expanded upon group discussion
• -00
  • Initial individual draft.

Potential Other Work provides a generic mechanism for signing arbitrary HTTP messages, both requests and responses. While this specification is focused solely on OAuth access token issuance and usage, could be used in other places in the OAuth ecosystem and this appendix exists to capture some of those ideas.

Client Authentication Similarly to , could be used as a generic client authentication mechanism for the client calling the AS for any authenticated call, including token PAR, the token endpoint. Since allows for multiple signatures with different usage parameters (including tag), this could be layered on top of even the runtime token request key binding, allowing a client to use one key for authentication and another for token use.

AS Responses Since can be used to sign responses, an AS could sign its responses from backend endpoints (including the token endpoint, revocation endpoint, discovery endpoint, introspection endpoint, etc) with an issuer-based key, providing a layer of protection in addition to the TLS transport. Signed response mechanisms like could be replaced with this method in many use cases.

Non-Repudiation of Requests Since allows a signed response to contain elements of the request that triggered the response, an AS or RS could use this mechanism to provide non-repudiation of a response to bind it to a particular request parameter set.

PAR Key Introduction Keys for this purpose could be introduced during a request phase, as part of the call to the PAR endpoint.

Accept-Signature Support The Accept-Signature mechanism in allows for runtime discovery of not only the applicability of signatures but also the expected coverage, for particular uses.