OAuth 2.0 Client Discovery

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶

This Internet-Draft will expire on 12 May 2023.¶

Copyright Notice

Copyright (c) 2022 IETF Trust and the persons identified as the document authors. All rights reserved.¶

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶

Table of Contents

1. Introduction

In the traditional OAuth 2.0 model [RFC6749], 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. This requirement also affects deployments that feature many clients and authorization servers whereby requiring the client to be registered with and maintain this registration with an authorization server is costly.¶

To enable a more dynamic relationship between a client and an authorization server, dynamic client registration via [RFC7591] 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. Furthermore, protecting the authorization servers registration endpoint forces other design tradeoffs, typically either the authorization server enforces some form of authentication (e.g a "registration_token") for registration requests, which is often problematic for public clients to manage/obtain. Or the authorization server permits any registration request and has to mitigate potential spam/malicious registration requests via some other mechanism.¶

Instead of requiring a registration process, this specification describes a model where a client identifies itself to the authorization server with its client_uri, which can be resolved to its metadata in a similar way to how an authorization server makes its metadata available to a client via [RFC8414].¶

The metadata for a client is retrieved from a .well-known location as a JSON [RFC8259] document, which declares its endpoint locations and client capabilities, this process is described in Obtaining Client Metadata (Section 3). Once the client metadata is retrieved and processed by the authorization server, the client can interact with the authorization server like any other client.¶

This specification defines a new request parameter 'client_discovery' to indicate that the interacting client has no prior registration with the authorization server and instead has resolvable metadata that describes its endpoint locations and capabilities.¶

This specification uses the metadata elements defined in the client registration specification [RFC7591] and no additional metadata fields or formats are defined in this specification.¶

2. 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 [RFC7591]. The value of this field MUST be a URI as defined in RFC3986 [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.¶

3. Obtaining Client Metadata

A Client supporting metadata discovery MUST make a JSON document containing metadata as specified in RFC7591 [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 [RFC5785]. 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 (Section 8).¶

GET /.well-known/oauth-client HTTP/1.1
Host: client.example.com

GET /.well-known/oauth-client/client1 HTTP/1.1
Host: client.example.com

HTTP/1.1 200 OK
Content-Type: application/json

{
    "client_uri": "https://client.example.com",
    "client_name": "My Example Client",
    "redirect_uris": [
        "https://client.example.com/cb",
        "https://client.example.com/cb2"
    ],
    "logo_uri": "https://client.example.com/logo.png",
    "jwks_uri": "https://client.example.com/my_public_keys.jwks",
    "example_extension_parameter": "example_value"
}

4. Authorization Request Using Client Discovery

A client can indicate to an authorization server that it has discoverable metadata in an authorization request via the "client_discovery" request parameter. Presence of this parameter in an authorization request with a value of "true" indicates to the authorization server that the "client_id" value of the authorization request is a URL encoded value 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 Client Metadata Section (Section 2).¶

The following is a non-normative example request of a client making an authorization request to an authorization server with the "client_discovery" parameter:¶

GET /authorize?response_type=code
    &client_id=https%3A%2F%2Fclient.example.com
    &client_discovery=true
    &state=af0ifjsldkj
    &redirect_uri=https%3A%2F%2Fclient.example.com%2Fcb
HOST: server.example.com

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 3) section.¶

TODO stipulate new error responses¶

5. Token Request Using Client Discovery

A client can indicate to an authorization server that it has discoverable metadata in an token request via the "client_discovery" request parameter. Presence of this parameter in a token request with a value of "true" indicates to the authorization server that the "client_id" value of the token request represents then "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 Client Metadata Section (Section 2).¶

The following is a non-normative example request of a client making an token request using "client_discovery" parameter:¶

POST /token
Host: server.example.com
Content-type: application/x-www-form-urlencoded
Accept: application/json

grant_type=authorization_code
&code=xxxxxxxx
&client_id=https://client.example.com/
&redirect_uri=https://client.example.com/redirect
&code_verifier=a6128783714cfda1d388e2e98b6ae8221ac31aca31959e59512c59f5
&client_discovery=true

The "client_id" parameter is passed to the token request during client authentication (as described in the Section 3.2.1 of [RFC6749]). Clients in possession of a client password MAY use the HTTP Basic authentication scheme as defined in RFC 2617 [RFC2617] or MAY include the client credentials in the request-body to authenticate with the authorization server.¶

In case of any errors, error response is returned (as described in the Section 5.2 of [RFC6749]). TODO expand¶

6. 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]).¶

7. Security Considerations

8. Compatibility Notes

TODO¶

9. IANA Considerations

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

Acknowledgments

TODO acknowledge.¶

Authors' Addresses