]> MATTR

tobias.looker@mattr.global

MATTR

karthik.sivasamy@mattr.global

AREA OAuth Working Group oauth This specification defines a new extensibility point to OAuth 2.0 which allows clients to identify through different methods to an authorization server using an identifier not assigned or managed by the authorization server. Beyond this general extensibility point, the specification defines one client ID scheme "urn:ietf:params:oauth:client-id-scheme:oauth-discoverable-client", including the nessary rules around how the client makes its metadata available for an authorization server and how an authorization server can obtain this metadata without the need for a registration process. Discussion Venues Source for this draft and an issue tracker can be found at .

Introduction In the traditional OAuth 2.0 model , the authorization server (AS) registers and assigns an identifier to a client through a registration process, during which the authorization server records certain characteristics about the client, commonly known as its metadata. This requirement for registration greatly reduces how dynamic the relationship between a client and authorization server can be. For instance, a client that is updating the capabilities it supports must update its registration(s) with affected authorization servers for this change to be recognized. To enable a more dynamic relationship between a client and an authorization server, dynamic client registration via was introduced. This model allows a client to register dynamically with a supporting authorization server by sending a registration request. Although this mechanism does provide some benefits it also introduces new operational challenges for both the client and AS. For instance clients that interface with many authorization servers are burdened with having to manage a client identifier per authorization server and in some cases forced to re-register the same client instance multiple times due to local storage limitations. Protecting the authorization servers client registration endpoint can also force other design tradeoffs, typically either the authorization server requires some form of authentication (e.g a "registration_token") for registration requests, which is often problematic for public clients to obtain and or manage. Or the authorization server permits any registration request and has to mitigate potential spam/malicious registration requests via some other mechanism. Instead of being limited to approaches which requiring a registration process for the client, this specification defines an extensibility point to allow clients to identify with the authorization server using an identifier not assigned by the authorization server.

Conventions and 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 specification uses the terms "access token", "refresh token", "authorization server", "resource server", "authorization endpoint", "authorization request", "authorization response", "token endpoint", "grant type", "access token request", "access token response", "client", "public client", and "confidential client" defined by The OAuth 2.0 Authorization Framework . The terms "request" and "response" are imported from .

Client ID Scheme A client can indicate to an authorization server that it is using a client identifier not assigned by the authorization server in an authorization request and or token request via the "client_id_scheme" request parameter. The value of the client_id_scheme request parameter indicates to the authorization server how it should process the "client_id" parameter which may include how to obtain the endpoint locations and capabilities of the client and validate that the party making the authorization request is infact the client represented by the reported "client_id". The following are non-normative example requests of a client making an authorization and a token request to an authorization server with the "client_id_scheme" parameter present and set to a value of "urn:ietf:params:oauth:client-id-scheme:example-value":

OAuth Discoverable Client ID Scheme The following section defines the the "client_id_scheme" of "urn:ietf:params:oauth:client-id-scheme:oauth-discoverable-client" including the requirements placed on both the client and authorization server when using this scheme. When the "client_id_scheme" parameter is present and is set to "urn:ietf:params:oauth:client-id-scheme:oauth-discoverable-client" in an authorization and or token request, it indicates to the receiving authorization server that the value of the "client_id" parameter in the request is an HTTPS based URL corresponding to the "client_uri" for the client and if the authorization server does not already have the metadata for the identified client, it can retrieve the metadata by following the procedure outlined in Obtaining Client Metadata.

Client Metadata Clients can have metadata described in their configuration. Examples of existing registered metadata fields that a client can make use of can be found at the OAuth 2.0 dynamic client registration metadata IANA registry [RFC 7591]. The client's published metadata MUST include the client_uri field as defined in section 2 of RFC7591 . The value of this field MUST be a URI as defined in RFC3986 with a scheme component that MUST be https, a host component, and optionally, port and path components and no query or fragment components. Additionally, host names MUST be domain names and MUST NOT be IPv4 or IPv6 addresses.

Obtaining Client Metadata A client supporting the "client_id_scheme" of "urn:ietf:params:oauth:client-id-scheme:oauth-discoverable-client" MUST make a JSON document containing metadata as specified in RFC7591 available at a path formed by inserting a well-known URI string into the client_uri between the host component and the path component, if any. By default, the well-known URI string used is "/.well-known/oauth-client". This path MUST use the "https" scheme. The syntax and semantics of ".well-known" are defined in RFC 5785 . The well-known URI suffix used MUST be registered in the IANA "Well-Known URIs" registry. Different clients utilizing OAuth 2.0 in application-specific ways may define and register different well-known URI suffixes used to publish client metadata as used by those applications, for example using a well-known URI string such as "/.well-known/example-configuration". Alternatively, many such clients will use the default well-known URI string "/.well-known/oauth-client", which is the right choice for general-purpose OAuth 2.0 applications. An OAuth 2.0 client using this specification MUST specify what well-known URI suffix it will use for this purpose. The same client MAY choose to publish its metadata at multiple well-known locations derived from its client_uri, for example, publishing metadata at both "/.well-known/example-configuration" and "/.well-known/oauth-client". Some OAuth 2.0 applications will choose to use the well-known URI suffix "openid-federation", as described in Compatibility Notes.

Client Metadata Request A client metadata document MUST be queried using an HTTP "GET" request at the previously specified path. The OAuth 2.0 authorization server would make the following request when the client_uri is "https://client.example.com" and the well-known URI suffix is "oauth-client" to obtain the metadata, since the client_uri contains no path component: If the client_uri value contains a path component, any terminating "/" MUST be removed before inserting "/.well-known/" and the well-known URI suffix between the host component and the path component. The OAuth 2.0 authorization server would make the following request when the client_uri is "https://client.example.com/client1" and the well-known URI suffix is "oauth-client" to obtain the metadata, since the client_uri contains a path component: Using path components enables supporting multiple clients per host. This is required in some complex client configurations. This use of ".well-known" is for supporting multiple clients per host; unlike its use in RFC 5785 , it does not provide general information about the host.

Client Metadata Response The response is a set of metadata values describing client's configuration, including all valid redirection URIs and features supported by the client. A successful response MUST use the 200 OK HTTP status code and return a JSON object using the "application/json" content type that contains a set of metadata fields and values as defined in Client Metadata. Other metadata fields MAY also be returned. Metadata fields that return multiple values are represented as JSON arrays. Metadata fields with no values MUST be omitted from the response. An error response uses the applicable HTTP status code value. The following is a non-normative example response:

Client Metadata Validation The client_uri value returned in the client metadata response MUST be identical to the client_uri value into which the well-known URI string was inserted to create the URL used to retrieve the metadata. If these values are not identical, the data contained in the response MUST NOT be used.

Authorization Request The following is a non-normative example request of a client making an authorization request to an authorization server with the "client_id_scheme" parameter set to "urn:ietf:params:oauth:client-id-scheme:oauth-discoverable-client": The value of the "client_id" parameter in the authorization request MUST represent the URL encoded form of the "client_uri" value for the corresponding client. The "client_id" value MUST be URL decoded by the authorization server to obtain the "client_uri" value which can be used to resolve the client metadata as described in the Obtaining Client Metadata section. TODO stipulate new error responses

Token Request The following is a non-normative example request of a client making a token request using the "client_id_scheme" parameter set to "urn:ietf:params:oauth:client-id-scheme:oauth-discoverable-client": The "client_id" parameter is passed to the token request during client authentication (as described in the Section 3.2.1 of [RFC6749]). TODO stipulate on other possible methods of client authentication In case of any errors, error response is returned (as described in the Section 5.2 of [RFC6749]).

String Operations Processing some OAuth 2.0 messages requires comparing values in the messages to known values. For example, the member names in the metadata response might be compared to specific member names such as "client_uri". Comparing Unicode [UNICODE] strings, however, has significant security implications. Therefore, comparisons between JSON strings and other Unicode strings MUST be performed as specified below:

1. Remove any JSON-applied escaping to produce an array of Unicode code points.
2. Unicode Normalization [USA15] MUST NOT be applied at any point to either the JSON string or the string it is to be compared against.
3. Comparisons between the two strings MUST be performed as a Unicode code-point-to-code-point equality comparison.

Note that this is the same equality comparison procedure described in ( Section 8.3 of [RFC8259]).

Security Considerations

TLS Requirements Implementations MUST support TLS. Which version(s) ought to be implemented will vary over time and depend on the widespread deployment and known security vulnerabilities at the time of implementation. The client MUST support TLS version 1.2 and MAY support additional TLS mechanisms meeting its security requirements. When using TLS, the authorization server MUST perform a TLS/SSL server certificate check, per RFC 6125 . Implementation security considerations can be found in "Recommendations for Secure Use of Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS)" . To protect against information disclosure and tampering, confidentiality protection MUST be applied using TLS with a ciphersuite that provides confidentiality and integrity protection.

Impersonation Attacks TLS certificate checking MUST be performed by the authorization server, as described in , when making a client metadata request. Checking that the server certificate is valid for the "client_uri" URL prevents man-in-middle and DNS-based attacks. These attacks could cause a authorization server to be tricked into using an attacker's keys and endpoints, which would enable impersonation of the legitimate client. If an attacker can accomplish this, they can access the resources that the affected client has access to by impersonating their profile. An attacker may also attempt to impersonate a client by publishing a metadata document that contains a "client_uri" claim using the "client_uri" URL of the client being impersonated, but with its own endpoints and signing keys. This would enable it to impersonate that client, if accepted by the authorization server. To prevent this, the authorization server MUST ensure that the "client_uri" URL it is using as the prefix for the metadata request exactly matches the value of the "client_uri" metadata value in the client's metadata document received by the authorization server.

Server Side Request Forgery (SSRF) Attacks Authorization servers resolving metadata of a client and resolving URLs located in the metadata document should be aware of possible SSRF attacks. Authorization servers should pay attention to the possibility of these URLs using private or loopback based addresses and consider network policies or other measures to prevent making requests to these addresses. Authorization servers should also be aware of the possibility of some URLs featuring non-http based URI schemes which can lead to other possible SSRF attack vectors.

Compatibility Notes TODO

IANA Considerations The following IANA registration requests are made by this document.

OAuth Parameters Registry This specification registers the following parameters in the IANA "OAuth Parameters" registry defined in OAuth 2.0 RFC 6749 client_id_scheme - Authorization request

• Parameter name: client_id_scheme
• Parameter usage location: authorization request
• Change controller: IESG
• Specification document(s): RFC XXXX (this document)

client_id_scheme - Token request

• Parameter name: client_id_scheme
• Parameter usage location: token request
• Change controller: IESG
• Specification document(s): RFC XXXX (this document)

<< TODO registering the OAuth urn parameter value>>

Well-Known URI Registry This specification registers the well-known URI defined in Obtaining Client Metadata in the (IANA "Well-Known URIs" registry) established by RFC 5785

Registry Contents

• URI suffix: oauth-client
• Change controller: IESG
• Specification document: of RFC 8414
• Related information: (none)

<< TODO - IANA registration - https://www.iana.org/assignments/well-known-uris/well-known-uris.xhtml >>

Normative 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 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. 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. 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. 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 memo defines a path prefix for "well-known locations", "/.well-known/", in selected Uniform Resource Identifier (URI) schemes. [STANDARDS-TRACK] This document specifies Version 1.2 of the Transport Layer Security (TLS) protocol. The TLS protocol provides communications security over the Internet. The protocol allows client/server applications to communicate in a way that is designed to prevent eavesdropping, tampering, or message forgery. [STANDARDS-TRACK] Many application technologies enable secure communication between two entities by means of Internet Public Key Infrastructure Using X.509 (PKIX) certificates in the context of Transport Layer Security (TLS). This document specifies procedures for representing and verifying the identity of application services in such interactions. [STANDARDS-TRACK] 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.

Acknowledgments TODO acknowledge.