OAuth Client ID Metadata Document
draft-parecki-oauth-client-id-metadata-document-01
This document is an Internet-Draft (I-D).
Anyone may submit an I-D to the IETF.
This I-D is not endorsed by the IETF and has no formal standing in the
IETF standards process.
| Document | Type | Active Internet-Draft (individual) | |
|---|---|---|---|
| Authors | Aaron Parecki , Emelia Smith | ||
| Last updated | 2024-07-08 | ||
| RFC stream | (None) | ||
| Intended RFC status | (None) | ||
| Formats | |||
| Stream | Stream state | (No stream defined) | |
| Consensus boilerplate | Unknown | ||
| RFC Editor Note | (None) | ||
| IESG | IESG state | I-D Exists | |
| Telechat date | (None) | ||
| Responsible AD | (None) | ||
| Send notices to | (None) |
draft-parecki-oauth-client-id-metadata-document-01
Web Authorization Protocol A. Parecki
Internet-Draft Okta
Intended status: Standards Track E. Smith
Expires: 9 January 2025 8 July 2024
OAuth Client ID Metadata Document
draft-parecki-oauth-client-id-metadata-document-01
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:[email protected]), 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/.
Parecki & Smith Expires 9 January 2025 [Page 1]
Internet-Draft Client ID Document July 2024
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.
Copyright Notice
Copyright (c) 2024 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 . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Conventions and Definitions . . . . . . . . . . . . . . . . . 3
3. Client Identifier . . . . . . . . . . . . . . . . . . . . . . 3
4. Client Information Discovery . . . . . . . . . . . . . . . . 4
4.1. Client Metadata . . . . . . . . . . . . . . . . . . . . . 4
4.2. Metadata Discovery Errors . . . . . . . . . . . . . . . . 4
4.3. Metadata Caching . . . . . . . . . . . . . . . . . . . . 5
4.4. Redirect URL Registration . . . . . . . . . . . . . . . . 5
5. Authorization Server Metadata . . . . . . . . . . . . . . . . 5
6. Security Considerations . . . . . . . . . . . . . . . . . . . 6
6.1. Client Authentication . . . . . . . . . . . . . . . . . . 6
6.2. OAuth Phishing Attacks . . . . . . . . . . . . . . . . . 6
6.3. Server Side Request Forgery (SSRF) Attacks . . . . . . . 7
6.4. Maximum Response Size for Client Metadata Documents . . . 7
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7
7.1. OAuth Authorization Server Metadata Registry . . . . . . 7
8. References . . . . . . . . . . . . . . . . . . . . . . . . . 7
8.1. Normative References . . . . . . . . . . . . . . . . . . 7
8.2. Informative References . . . . . . . . . . . . . . . . . 8
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 9
Document History . . . . . . . . . . . . . . . . . . . . . . . . 9
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 9
Parecki & Smith Expires 9 January 2025 [Page 2]
Internet-Draft Client ID Document July 2024
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.
Parecki & Smith Expires 9 January 2025 [Page 3]
Internet-Draft Client ID Document July 2024
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
(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.
Parecki & Smith Expires 9 January 2025 [Page 4]
Internet-Draft Client ID Document July 2024
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].
Parecki & Smith Expires 9 January 2025 [Page 5]
Internet-Draft Client ID Document July 2024
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.
Parecki & Smith Expires 9 January 2025 [Page 6]
Internet-Draft Client ID Document July 2024
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
Parecki & Smith Expires 9 January 2025 [Page 7]
Internet-Draft Client ID Document July 2024
[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, 3 June 2024,
<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, March 1997,
<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, January 2005,
<https://www.rfc-editor.org/rfc/rfc3986>.
[RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework",
RFC 6749, DOI 10.17487/RFC6749, October 2012,
<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, January 2013,
<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, July 2015,
<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,
May 2017, <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, June 2018,
<https://www.rfc-editor.org/rfc/rfc8414>.
8.2. Informative References
[IndieAuth]
Parecki, A., "IndieAuth", 12 February 2022,
<https://indieauth.spec.indieweb.org/>.
Parecki & Smith Expires 9 January 2025 [Page 8]
Internet-Draft Client ID Document July 2024
[OpenID] Sakimura, N., Bradley, J., Jones, M., Medeiros, B. de.,
and C. Mortimore, "OpenID Connect Core 1.0", 15 December
2023,
<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",
17 May 2024,
<https://openid.net/specs/openid-federation-1_0.html>.
[Solid-OIDC]
Coburn, A., elf Pavlik, and D. Zagidulin, "Solid-OIDC", 28
March 2022,
<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
* Added recommendation of max metadata document size
* Changed metadata property reference to IANA registry instead of
Dynamic Client Registration
-00
* Initial draft
Authors' Addresses
Parecki & Smith Expires 9 January 2025 [Page 9]
Internet-Draft Client ID Document July 2024
Aaron Parecki
Okta
Email: [email protected]
URI: https://aaronparecki.com
Emelia Smith
Email: [email protected]
URI: https://thisismissem.social
Parecki & Smith Expires 9 January 2025 [Page 10]