Internet DRAFT - draft-looker-oauth-client-id-scheme
draft-looker-oauth-client-id-scheme
OAuth Working Group T. Looker
Internet-Draft K. Sivasamy
Intended status: Informational MATTR
Expires: 16 November 2023 15 May 2023
OAuth 2.0 Client ID Scheme
draft-looker-oauth-client-id-scheme-00
Abstract
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
This note is to be removed before publishing as an RFC.
Source for this draft and an issue tracker can be found at
https://github.com/mattrglobal/draft-looker-oauth-client-id-scheme.
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 16 November 2023.
Looker & Sivasamy Expires 16 November 2023 [Page 1]
Internet-Draft OAuth 2.0 Client ID Scheme May 2023
Copyright Notice
Copyright (c) 2023 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 . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1. Conventions and Terminology . . . . . . . . . . . . . . . 3
2. Client ID Scheme . . . . . . . . . . . . . . . . . . . . . . 4
2.1. OAuth Discoverable Client ID Scheme . . . . . . . . . . . 4
2.1.1. Client Metadata . . . . . . . . . . . . . . . . . . . 5
2.1.2. Obtaining Client Metadata . . . . . . . . . . . . . . 5
2.1.3. Authorization Request . . . . . . . . . . . . . . . . 7
2.1.4. Token Request . . . . . . . . . . . . . . . . . . . . 8
3. String Operations . . . . . . . . . . . . . . . . . . . . . . 8
4. Security Considerations . . . . . . . . . . . . . . . . . . . 9
4.1. TLS Requirements . . . . . . . . . . . . . . . . . . . . 9
4.2. Impersonation Attacks . . . . . . . . . . . . . . . . . . 9
4.3. Server Side Request Forgery (SSRF) Attacks . . . . . . . 10
5. Compatibility Notes . . . . . . . . . . . . . . . . . . . . . 10
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10
6.1. OAuth Parameters Registry . . . . . . . . . . . . . . . . 10
6.2. Well-Known URI Registry . . . . . . . . . . . . . . . . . 11
6.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 11
7. Normative References . . . . . . . . . . . . . . . . . . . . 11
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 12
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 12
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.
Looker & Sivasamy Expires 16 November 2023 [Page 2]
Internet-Draft OAuth 2.0 Client ID Scheme May 2023
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 [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. 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.
1.1. 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 [RFC2119] [RFC8174] 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 [RFC6749].
The terms "request" and "response" are imported from [RFC9110].
Looker & Sivasamy Expires 16 November 2023 [Page 3]
Internet-Draft OAuth 2.0 Client ID Scheme May 2023
2. 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":
GET /authorize?response_type=code
&client_id=https%3A%2F%2Fclient.example.com
&client_id_scheme=urn%3Aietf%3Aparams%3Aoauth%3Aclient-id-scheme%3Aexample-value
&state=af0ifjsldkj
&redirect_uri=https%3A%2F%2Fclient.example.com%2Fcb
HOST: server.example.com
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_id_scheme=urn%3Aietf%3Aparams%3Aoauth%3Aclient-id-scheme%3Aexample-value
2.1. 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"
Looker & Sivasamy Expires 16 November 2023 [Page 4]
Internet-Draft OAuth 2.0 Client ID Scheme May 2023
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
(Section 2.1.1).
2.1.1. 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] (https://www.rfc-editor.org/rfc/
rfc7591.html#section-4.1).
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.
2.1.2. 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
[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" (https://www.iana.org/assignments/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".
Looker & Sivasamy Expires 16 November 2023 [Page 5]
Internet-Draft OAuth 2.0 Client ID Scheme May 2023
Some OAuth 2.0 applications will choose to use the well-known URI
suffix "openid-federation", as described in Compatibility Notes
(Section 5).
2.1.2.1. 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:
GET /.well-known/oauth-client HTTP/1.1
Host: client.example.com
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:
GET /.well-known/oauth-client/client1 HTTP/1.1
Host: client.example.com
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 [RFC5785], it does not provide general information
about the host.
2.1.2.2. 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 (Section 2.1.1). 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.
Looker & Sivasamy Expires 16 November 2023 [Page 6]
Internet-Draft OAuth 2.0 Client ID Scheme May 2023
The following is a non-normative example response:
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",
"tos_uri": "https://client.example.com/tos",
"policy_uri": "https://client.example.com/policy",
"example_extension_parameter": "example_value"
}
2.1.2.3. 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.
2.1.3. 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":
GET /authorize?response_type=code
&client_id=a-non-as-assigned-client-id
&client_id_scheme=urn%3Aietf%3Aparams%3Aoauth%3Aclient-id-scheme%3Aoauth-discoverable-client
&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 2.1.2) section.
Looker & Sivasamy Expires 16 November 2023 [Page 7]
Internet-Draft OAuth 2.0 Client ID Scheme May 2023
*TODO stipulate new error responses*
2.1.4. 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":
POST /token
Host: server.example.com
Content-type: application/x-www-form-urlencoded
Accept: application/json
grant_type=authorization_code
&code=xxxxxxxx
&client_id=a-non-as-assigned-client-id
&redirect_uri=https://client.example.com/redirect
&code_verifier=a6128783714cfda1d388e2e98b6ae8221ac31aca31959e59512c59f5
&client_id_scheme=urn%3Aietf%3Aparams%3Aoauth%3Aclient-id-scheme%3Aoauth-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]
(https://www.rfc-editor.org/rfc/rfc6749#section-3.2.1)).
*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] (https://www.rfc-editor.org/rfc/
rfc6749#section-5.2)).
3. 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.
Looker & Sivasamy Expires 16 November 2023 [Page 8]
Internet-Draft OAuth 2.0 Client ID Scheme May 2023
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] (https://www.rfc-editor.org/rfc/
rfc8259#section-8.3)).
4. Security Considerations
4.1. 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 [RFC5246]
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 [RFC6125].
Implementation security considerations can be found in
"Recommendations for Secure Use of Transport Layer Security (TLS) and
Datagram Transport Layer Security (DTLS)" [BCP195].
To protect against information disclosure and tampering,
confidentiality protection MUST be applied using TLS with a
ciphersuite that provides confidentiality and integrity protection.
4.2. Impersonation Attacks
TLS certificate checking MUST be performed by the authorization
server, as described in Section 4.1, 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.
Looker & Sivasamy Expires 16 November 2023 [Page 9]
Internet-Draft OAuth 2.0 Client ID Scheme May 2023
4.3. 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.
5. Compatibility Notes
*TODO*
6. IANA Considerations
The following IANA registration requests are made by this document.
6.1. OAuth Parameters Registry
This specification registers the following parameters in the IANA
"OAuth Parameters" registry defined in OAuth 2.0 RFC 6749 [RFC6749]
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>>
Looker & Sivasamy Expires 16 November 2023 [Page 10]
Internet-Draft OAuth 2.0 Client ID Scheme May 2023
6.2. Well-Known URI Registry
This specification registers the well-known URI defined in Obtaining
Client Metadata (Section 2.1.2) in the (IANA "Well-Known URIs"
registry (https://www.iana.org/assignments/well-known-uris/well-
known-uris.xhtml)) established by RFC 5785 [RFC5785]
6.2.1. Registry Contents
* URI suffix: oauth-client
* Change controller: IESG
* Specification document: Section 2.1.2 of RFC 8414
* Related information: (none)
<< TODO - IANA registration - https://www.iana.org/assignments/well-
known-uris/well-known-uris.xhtml >>
7. Normative References
[BCP195] Moriarty, K. and S. Farrell, "Deprecating TLS 1.0 and TLS
1.1", BCP 195, RFC 8996, March 2021.
Sheffer, Y., Saint-Andre, P., and T. Fossati,
"Recommendations for Secure Use of Transport Layer
Security (TLS) and Datagram Transport Layer Security
(DTLS)", BCP 195, RFC 9325, November 2022.
[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>.
[RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security
(TLS) Protocol Version 1.2", RFC 5246,
DOI 10.17487/RFC5246, August 2008,
<https://www.rfc-editor.org/rfc/rfc5246>.
Looker & Sivasamy Expires 16 November 2023 [Page 11]
Internet-Draft OAuth 2.0 Client ID Scheme May 2023
[RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known
Uniform Resource Identifiers (URIs)", RFC 5785,
DOI 10.17487/RFC5785, April 2010,
<https://www.rfc-editor.org/rfc/rfc5785>.
[RFC6125] Saint-Andre, P. and J. Hodges, "Representation and
Verification of Domain-Based Application Service Identity
within Internet Public Key Infrastructure Using X.509
(PKIX) Certificates in the Context of Transport Layer
Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March
2011, <https://www.rfc-editor.org/rfc/rfc6125>.
[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>.
[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>.
[RFC9110] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
Ed., "HTTP Semantics", STD 97, RFC 9110,
DOI 10.17487/RFC9110, June 2022,
<https://www.rfc-editor.org/rfc/rfc9110>.
Acknowledgments
TODO acknowledge.
Authors' Addresses
Tobias Looker
MATTR
Email: tobias.looker@mattr.global
Karthik Sivasamy
MATTR
Email: karthik.sivasamy@mattr.global
Looker & Sivasamy Expires 16 November 2023 [Page 12]
