OAuth 2.0 Client ID Scheme
Internet-Draft draft-parecki-oauth-client-id-scheme-00
Aaron Parecki
Okta
aaron@parecki.com
Daniel Fett
Authlete
mail@danielfett.de
Joseph Heenan
Authlete
joseph@heenan.me.uk
06 November 2024
Security
Web Authorization Protocol
oauth
This specification defines the concept of a Client Identifier Scheme to enable Authorization Servers and Clients to use more than one mechanism to obtain and validate Client metadata.
About This Document
The latest revision of this draft can be found at https://drafts.aaronpk.com/oauth-client-id-scheme/draft-parecki-oauth-client-id-scheme.html. Status information for this document may be found at https://datatracker.ietf.org/doc/draft-parecki-oauth-client-id-scheme/.
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/oauth-client-id-scheme.
Introduction
A Client Identifier is used by an OAuth 2.0 Client to identify itself to an Authorization Server. The Client Identifier is used in the Authorization Request and various other places throughout OAuth flows. In ecosystems where more than one method of obtaining and validating Client metadata is used, it is necessary to indicate unambiguously which method is used. This specification defines a structure for Client Identifiers that includes a prefix indicating the Client Identifier Scheme.
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.
Client Identifier Scheme
This specification defines the concept of a Client Identifier Scheme that indicates how an Authorization Server is supposed to interpret the Client Identifier and associated data in the process of Client identification, authentication, and authorization. The Client Identifier Scheme enables deployments of this specification to use different mechanisms to obtain and validate metadata of the Client beyond the scope of [RFC6749].
The Client Identifier Scheme is a string that MAY be communicated by the Client in a prefix within the client_id parameter in the Authorization Request. A fallback to pre-registered Clients as in [RFC6749] remains in place as a default mechanism in case no Client Identifier Scheme was provided. A certain Client Identifier Scheme may require the Client to sign the Authorization Request as means of authentication and/or pass additional parameters and require the Authorization Server to process them.
Syntax
In the client_id Authorization Request parameter and other places where the Client Identifier is used, the Client Identifier Schemes are prefixed to the usual Client Identifier, separated by a : (colon) character:

<client_id_scheme>:<orig_client_id>

Here, <client_id_scheme> is the Client Identifier Scheme and <orig_client_id> is an identifier for the Client within the namespace of that scheme. See Section 3.4 for Client Identifier Schemes defined by this specification.
Authorization Servers MUST use the presence of a : (colon) character to determine whether a Client Identifier Scheme is used. If a : character is present, the Authorization Server MUST interpret the Client Identifier according to the Client Identifier Scheme, here defined as the string before the (first) : character. If the Authorization Server does not support the Client Identifier Scheme, the Authorization Server MUST refuse the request.
For example, an Authorization Request might contain client_id=client_attestation:example-client to indicate that the client_attestation Client Identifier Scheme is to be used and that within this scheme, the Client can be identified by the string example-client. The presentation would contain the full client_attestation:example-client string as the audience (intended receiver) and the same full string would be used as the Client Identifier anywhere in the OAuth flow.
Note that the Client needs to determine which Client Identifier Schemes the Authorization Server supports prior to sending the Authorization Request in order to choose a supported scheme.
Pre-Registered Clients
If a : character is not present in the Client Identifier, the Authorization Server MUST treat the Client Identifier as referencing a pre-registered client. This is equivalent to the [RFC6749] default behavior, i.e., the Client Identifier needs to be known to the Authorization Server in advance of the Authorization Request. The Client metadata is pre-registered using [RFC7591] or through out-of-band mechanisms.
For example, if an Authorization Request contains client_id=example-client, the Authorization Server would interprete the Client Identifier as referring to a pre-registered client.
From this definition, it follows that pre-registered clients MUST NOT contain a : character in their Client Identifier.
Pre-Existing Ecosystems using https
Existing deployments that use https URLs as client IDs and that have only one way to resolve client metadata from the URL, MAY use full https URL as the client ID. If there is only one way to resolve client metadata then there is no ambiguity.
For example, an authorization server using only the Client ID Metadata Document [I-D.draft-parecki-oauth-client-id-metadata-document] method to retrieve client metadata MAY accept client IDs such as:

https://client.example.com/metadata.json

This results in this non-normative example of an authorization request:

GET /authorize?
  response_type=code
  &client_id=https%3A%2F%2Fclient.example.org%2Fmetadata.json
  &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcallback
  &code_challenge=GdE4nqBrwRxQfN2Y8fq3rrYk_kkpwg6tQ74J94-2nHw
  &code_challenge_method=S256
  &scope=write

Defined Client Identifier Schemes
This specification defines the following Client Identifier Schemes, followed by the examples where applicable:
- redirect_uri: This value indicates that the Client Identifier (without the prefix redirect_uri:) is the Client's Redirect URI (or Response URI when Response Mode direct_post is used). The Authorization Request MUST NOT be signed. The Client MAY omit the redirect_uri Authorization Request parameter. Example Client Identifier: redirect_uri:https%3A%2F%2Fclient.example.org%2Fcb.
- federation: This value indicates that the Client Identifier is an Entity Identifier defined in OpenID Federation [OpenID.Federation]. Since the Entity Identifier is already defined to start with federation:, this Client Identifier Scheme MUST NOT be prefixed additionally. Processing rules given in [OpenID.Federation] MUST be followed. Automatic Registration as defined in [OpenID.Federation] MUST be used. The Authorization Request MAY also contain a trust_chain parameter. The final Client metadata is obtained from the Trust Chain after applying the policies, according to [OpenID.Federation]. Example Client Identifier: federation:https://federation-client.example.com.
- did: This value indicates that the Client Identifier is a DID defined in [DID-Core]. Since the DID URI is already defined to start with did:, this Client Identifier Scheme MUST NOT be prefixed additionally. The request MUST be signed with a private key associated with the DID. A public key to verify the signature MUST be obtained from the verificationMethod property of a DID Document. Since DID Document may include multiple public keys, a particular public key used to sign the request in question MUST be identified by the kid in the JOSE Header. To obtain the DID Document, the Authorization Server MUST use DID Resolution defined by the DID method used by the Client. Example Client Identifier: did:example:123#1.
- client_attestation: This Client Identifier Scheme allows the Client to authenticate using a JWT that is bound to a certain public key as defined in (OpenID4VP: Client Attestation). When the Client Identifier Scheme is client_attestation, the Client Identifier MUST equal the sub claim value in the Client attestation JWT. The request MUST be signed with the private key corresponding to the public key in the cnf claim in the Client attestation JWT. This serves as proof of possesion of this key. The Client attestation JWT MUST be added to the jwt JOSE Header of the request object (see (OpenID4VP: Client Attestation)). The Authorization Server MUST validate the signature on the Client attestation JWT. The iss claim value of the Client Attestation JWT MUST identify a party the Authorization Server trusts for issuing Client Attestation JWTs. If the Authorization Server cannot establish trust, it MUST refuse the request. If the issuer of the Client Attestation JWT adds a redirect_uris claim to the attestation, the Authorization Server MUST ensure the redirect_uri request parameter value exactly matches one of the redirect_uris claim entries. Example Client Identifier: client_attestation:client.example.
- x509_san_dns: When the Client Identifier Scheme is x509_san_dns, the Client Identifier MUST be a DNS name and match a dNSName Subject Alternative Name (SAN) [RFC5280] entry in the leaf certificate passed with the request. The request MUST be signed with the private key corresponding to the public key in the leaf X.509 certificate of the certificate chain added to the request in the x5c JOSE header [RFC7515] of the signed request object. The Authorization Server MUST validate the signature and the trust chain of the X.509 certificate. If the Authorization Server can establish trust in the Client Identifier authenticated through the certificate, e.g. because the Client Identifier is contained in a list of trusted Client Identifiers, it may allow the client to freely choose the redirect_uri value. If not, the FQDN of the redirect_uri value MUST match the Client Identifier without the prefix x509_san_dns:. Example Client Identifier: x509_san_dns:client.example.org.
- x509_san_uri: When the Client Identifier Scheme is x509_san_uri, the Client Identifier MUST be a URI and match a uniformResourceIdentifier Subject Alternative Name (SAN) [RFC5280] entry in the leaf certificate passed with the request. The request MUST be signed with the private key corresponding to the public key in the leaf X.509 certificate of the certificate chain added to the request in the x5c JOSE header [RFC7515] of the signed request object. The Authorization Server MUST validate the signature and the trust chain of the X.509 certificate. If the Authorization Server can establish trust in the Client Identifier authenticated through the certificate, e.g., because the Client Identifier is contained in a list of trusted Client Identifiers, it may allow the client to freely choose the redirect_uri value. If not, the redirect_uri value MUST match the Client Identifier without the prefix x509_san_uri:. Example Client Identifier: x509_san_uri:https://client.example.org/cb.
- https: This Client Identifier Scheme MUST NOT be registered.
Example
The following is a non-normative example of an authorization request with the redirect_uri Client ID Scheme:

GET /authorize?
  response_type=code
  &client_id=redirect_uri:https%3A%2F%2Fclient.example.org%2Fcb
  &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb
  &code_challenge=GdE4nqBrwRxQfN2Y8fq3rrYk_kkpwg6tQ74J94-2nHw
  &code_challenge_method=S256
  &scope=write

Todo: Server Metadata
e.g., a client_id_schemes_supported parameter in the Server Metadata and a client_id_scheme_default parameter.
Todo: Registry
Security Considerations
Client Identifier Mixups
Confusing Clients using a Client Identifier Scheme with those using none can lead to attacks. Therefore, Authorization Servers MUST always use the full Client Identifier, including the prefix if provided, within the context of the Authorization Server or its responses to identify the client. This refers in particular to places where the Client Identifier is used in [RFC6749] as well as in any artifacts such as the aud claim of JWT access tokens [RFC9068].
IANA Considerations
This document has no IANA actions.
References
Normative References
[RFC6749]

The OAuth 2.0 Authorization Framework
D. Hardt, Ed.
October 2012
RFC 6749
DOI 10.17487/RFC6749
[RFC5280]

Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile
D. Cooper
S. Santesson
S. Farrell
S. Boeyen
R. Housley
W. Polk
May 2008
RFC 5280
DOI 10.17487/RFC5280
[RFC7515]

JSON Web Signature (JWS)
M. Jones
J. Bradley
N. Sakimura
May 2015
RFC 7515
DOI 10.17487/RFC7515
[DID-Core]

DID Core
19 July 2022
[OpenID.Federation]

OpenID Federation 1.0
R. Hedberg
independent
M.B. Jones
Self-Issued Consulting
A.Å. Solberg
Sikt
J. Bradley
Yubico
G. De Marco
independent
V. Dzhuvinov
Connect2id
17 May 2024
[RFC2119]

Key words for use in RFCs to Indicate Requirement Levels
S. Bradner
March 1997
BCP 14
RFC 2119
DOI 10.17487/RFC2119
[RFC8174]

Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words
B. Leiba
May 2017
BCP 14
RFC 8174
DOI 10.17487/RFC8174
Informative References
[RFC7591]

OAuth 2.0 Dynamic Client Registration Protocol
J. Richer, Ed.
M. Jones
J. Bradley
M. Machulak
P. Hunt
July 2015
RFC 7591
DOI 10.17487/RFC7591
[RFC9068]

JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens
V. Bertocci
October 2021
RFC 9068
DOI 10.17487/RFC9068
[I-D.draft-parecki-oauth-client-id-metadata-document]

OAuth Client ID Metadata Document
Aaron Parecki
Okta
Emelia Smith
8 July 2024
Internet-Draft draft-parecki-oauth-client-id-metadata-document-01
[OpenID]

OpenID Connect Core 1.0
N. Sakimura
NAT.Consulting
J. Bradley
Yubico
M. Jones
Self-Issued Consulting
B. de Medeiros
Google
C. Mortimore
Disney
15 December 2023
Acknowledgments
TODO acknowledge.