Internet-Draft Client ID Document July 2024
Parecki & Smith Expires 9 January 2025 [Page]
Workgroup:
Web Authorization Protocol
Internet-Draft:
draft-parecki-oauth-client-id-metadata-document-01
Published:
Intended Status:
Standards Track
Expires:
Authors:
A. Parecki
Okta
E. Smith

OAuth Client ID Metadata Document

Abstract

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.

About This Document

This note is to be removed before publishing as an RFC.

The latest revision of this draft can be found at https://aaronpk.github.io/draft-parecki-oauth-client-id-metadata-document/draft-parecki-oauth-client-id-metadata-document.html. Status information for this document may be found at https://datatracker.ietf.org/doc/draft-parecki-oauth-client-id-metadata-document/.

Discussion of this document takes place on the Web Authorization Protocol Working Group mailing list (mailto:oauth@ietf.org), which is archived at https://mailarchive.ietf.org/arch/browse/oauth/. Subscribe at https://www.ietf.org/mailman/listinfo/oauth/.

Source for this draft and an issue tracker can be found at https://github.com/aaronpk/draft-parecki-oauth-client-id-metadata-document.

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 9 January 2025.

Table of Contents

1. Introduction

In order for an OAuth 2.0 [RFC6749] client to utilize an OAuth 2.0 authorization server, the client needs to establish a unique identifier, and needs to to provide the server with metadata about the application, such as the application name, icon and redirect URIs. In cases where a client is interacting with authorization servers that it has no relationship with, manual registration is impossible.

While Dynamic Client Registration [RFC7591] can provide a method for a previously unknown client to establish itself at an authorization server and obtain a client identifier, this is not always practical in some deployments and can create additional challenges around management of the registration data and cleanup of inactive clients.

This specification describes how an OAuth 2.0 client can publish its own registration information and avoid the need for pre-registering at each authorization server.

2. 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 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

3. Client Identifier

This specification defines the client identifier as a URL with the following restrictions. Client identifier URLs MUST have an "https" scheme, MUST contain a path component, MUST NOT contain single-dot or double-dot path segments, MUST NOT contain a fragment component and MUST NOT contain a username or password component. Client identifier URLs MAY contain a query string component and MAY contain a port.

This specification places no restrictions on what URL is used as a client identifier. A short URL is RECOMMENDED, since the URL may be displayed to the end user in the authorization interface or in management interfaces. Usage of a stable URL that does not frequently change for the client is also RECOMMENDED.

4. Client Information Discovery

One purpose of registering clients at the authorization server is so that the authorization server has additional information about the client that can be used during an OAuth flow, such as presenting information about the client to the user in an authorization consent screen, for example the client name and logo.

The authorization server SHOULD fetch the document indicated by the client_id to retrieve the client registration information.

4.1. Client Metadata

The client metadata document URL is a JSON document containing the metadata of the client. The client metadata values are the values defined in the OAuth Dynamic Client Registration Metadata OAuth Parameters registry https://www.iana.org/assignments/oauth-parameters/oauth-parameters.xhtml#client-metadata.

The client metadata document MUST contain a client_id property whose value MUST compare and match the URL of the document using simple string comparison as defined in [RFC3986] Section 6.2.1.

The client metadata document MAY define additional properties in the response. The client metadata document MAY also be served with more specific content types as long as the response is JSON and conforms to application/<AS-defined>+json.

The token_endpoint_auth_method property MUST NOT include client_secret_post or client_secret_basic, as there is no way to establish a shared secret to be used with these authentication methods. See Section 6.1 for more details.

Other specifications MAY place additional restrictions on the contents of the client metadata document accepted by authorization servers implementing their specification, for instance, preventing the registration of confidential clients by requiring the token_endpoint_auth_method property be set to "none".

4.2. Metadata Discovery Errors

If fetching the metadata document fails, the authorization server SHOULD abort the authorization request.

4.3. Metadata Caching

The authorization server MAY cache the client metadata it discovers at the client metadata document URL.

TBD: recommend a cache lifetime? considerations about stale data?

The authorization server MUST NOT cache error responses. The authorization server also MUST NOT cache documents which are invalid or malformed.

TBD: Do we want to define an endpoint through which a document can be validated by an authorization server, such that a developer can assert that their document is valid?

4.4. Redirect URL Registration

According to [I-D.draft-ietf-oauth-security-topics], the authorization server MUST require registration of redirect URIs, and MUST ensure that the redirect URI in a request is an exact match of a registered redirect URI.

This method of client information discovery establishes a registered redirect URI with the authorization server which is used when comparing the redirect URI in an authorization request against the registered redirect URIs.

5. Authorization Server Metadata

Authorization servers that publish Authorization Server Metadata [RFC8414] MUST include the following property to signal support for client metadata documents as described in this specification.

client_id_metadata_document_supported:

OPTIONAL. Boolean value specifying whether the authorization server supports retrieving client metadata from a client_id URL as described in this specification.

This enables clients to avoid sending the user to a dead end, by only redirecting the user to an authorization server that supports this specification. Otherwise, the client would redirect the user and the user would be met with an error about an invalid client as described by Section 4.1.2.1 of [RFC6749].

6. Security Considerations

In addition to the security considerations in OAuth 2.0 Core [RFC6749], and OAuth 2.0 Threat Model and Security Considerations [RFC6819], and [I-D.draft-ietf-oauth-security-topics] the additional considerations apply.

6.1. Client Authentication

Since the client establishes its own registration data at the authorization server, prior coordination of client credentials is not possible. However, clients MAY establish credentials at the authorization server by using authentication methods that use public/private key pairs, by publishing the public key in their metadata document.

For example, the client MAY include the following properties in its metadata document to establish a public key and the private_key_jwt authentication method defined in [OpenID]:

{
  ...
  "token_endpoint_auth_method": "private_key_jwt",
  "jwks_uri": "https://client.example.com/jwks.json"
  ...
}

This establishes this client as a confidential client, and any communication with the authorization server MUST include client authentication of the registered type.

6.2. OAuth Phishing Attacks

Authorization servers SHOULD fetch the client_id metadata document provided in the authorization request in order to provide users with additional information about the request, such as the application name and logo. If the server does not fetch the client metadata document, then it SHOULD take additional measures to ensure the user is provided with as much information as possible about the request.

The authorization server SHOULD display the hostname of the client_id on the authorization interface, in addition to displaying the fetched client information if any. Displaying the hostname helps users know that they are authorizing the expected application.

If fetching the client metadata document fails for any reason, the client_id URL is the only piece of information the user has as an indication of which application they are authorizing.

6.3. Server Side Request Forgery (SSRF) Attacks

Authorization servers fetching the client metadata document and resolving URLs located in the metadata document should be aware of possible SSRF attacks. Authorization servers SHOULD avoid fetching any URLs using private or loopback addresses and consider network policies or other measures to prevent making requests to these addresses. Authorization servers SHOULD also be aware of the possibility that URLs might be non-http-based URI schemes which can lead to other possible SSRF attack vectors.

6.4. Maximum Response Size for Client Metadata Documents

Authorization servers SHOULD limit the response size when fetching the client metadata document, as to avoid denial of service attacks against the authorization server by consuming excessive resources (memory, disk, database). The recommended maximum response size for client metadata documents is 5 kilobytes.

7. IANA Considerations

7.1. OAuth Authorization Server Metadata Registry

The following authorization server metadata value is defined by this specification and registered in the IANA "OAuth Authorization Server Metadata" registry established in OAuth 2.0 Authorization Server Metadata [RFC8414].

  • Metadata Name: client_id_metadata_document_supported:

  • Metadata Description: JSON boolean value specifying whether the authorization server supports retrieving client metadata from a client_id URL.

  • Change Controller: IETF

  • Specification Document: Section 5 of [draft-parecki-oauth-client-id-metadata-document-01]

8. References

8.1. Normative References

[I-D.draft-ietf-oauth-security-topics]
Lodderstedt, T., Bradley, J., Labunets, A., and D. Fett, "OAuth 2.0 Security Best Current Practice", Work in Progress, Internet-Draft, draft-ietf-oauth-security-topics-29, , <https://datatracker.ietf.org/doc/html/draft-ietf-oauth-security-topics-29>.
[RFC2119]
Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, , <https://www.rfc-editor.org/rfc/rfc2119>.
[RFC3986]
Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, DOI 10.17487/RFC3986, , <https://www.rfc-editor.org/rfc/rfc3986>.
[RFC6749]
Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", RFC 6749, DOI 10.17487/RFC6749, , <https://www.rfc-editor.org/rfc/rfc6749>.
[RFC6819]
Lodderstedt, T., Ed., McGloin, M., and P. Hunt, "OAuth 2.0 Threat Model and Security Considerations", RFC 6819, DOI 10.17487/RFC6819, , <https://www.rfc-editor.org/rfc/rfc6819>.
[RFC7591]
Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", RFC 7591, DOI 10.17487/RFC7591, , <https://www.rfc-editor.org/rfc/rfc7591>.
[RFC8174]
Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, , <https://www.rfc-editor.org/rfc/rfc8174>.
[RFC8414]
Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 Authorization Server Metadata", RFC 8414, DOI 10.17487/RFC8414, , <https://www.rfc-editor.org/rfc/rfc8414>.

8.2. Informative References

[IndieAuth]
Parecki, A., "IndieAuth", , <https://indieauth.spec.indieweb.org/>.
[OpenID]
Sakimura, N., Bradley, J., Jones, M., Medeiros, B. de., and C. Mortimore, "OpenID Connect Core 1.0", , <https://openid.net/specs/openid-connect-core-1_0.html>.
[OpenID.Federation]
Hedberg, R., Jones, M.B., Solberg, A.Å., Bradley, J., Marco, G. D., and V. Dzhuvinov, "OpenID Federation 1.0", , <https://openid.net/specs/openid-federation-1_0.html>.
[Solid-OIDC]
Coburn, A., elf Pavlik, and D. Zagidulin, "Solid-OIDC", , <https://solidproject.org/TR/2022/oidc-20220328>.

Acknowledgments

The idea of using URIs as the client_id in OAuth based authorization requests is not new, and has previously been specified in varying ways by [IndieAuth], [Solid-OIDC], and [OpenID.Federation]. This specification is largely inspired by the work of Aaron Coburn, elf Pavlik, and Dmitri Zagidulin in their [Solid-OIDC] specification which defined dereferenceable Client Identifier Documents.

The authors would like to thank the following people for their contributions and reviews of this specification: Dick Hardt, Matthieu Sieben.

Document History

(This appendix to be deleted by the RFC editor in the final specification.)

-01

-00

Authors' Addresses

Aaron Parecki
Okta
Emelia Smith