| Internet-Draft | OAuth 2.0 Authorization Server Discovery | November 2022 |
| Parecki & Schwartz | Expires 1 June 2023 | [Page] |
This specification provides a mechanism for an access-controlled HTTP resource to indicate which OAuth authorization server it is protected by. This allows the use of OAuth 2.0 authorization by clients that do not have prior knowledge about the resource server's configuration.¶
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/oauth-authorization-server-discovery/draft-parecki-oauth-authorization-server-discovery.html. Status information for this document may be found at https://datatracker.ietf.org/doc/draft-parecki-oauth-authorization-server-discovery/.¶
Source for this draft and an issue tracker can be found at https://github.com/aaronpk/oauth-authorization-server-discovery.¶
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 1 June 2023.¶
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.¶
In order to obtain an access token to access an HTTP resource, an OAuth 2.0 client needs to know the authorization server to use for the request. OAuth 2.0 [RFC6749] does not provide any mechanism for authorization server discovery, and other OAuth 2.0 extensions have left authorization server discovery out of scope as well.¶
This specification provides a mechanism for a resource server to indicate which authorization server it accepts access tokens issued by, so that an OAuth client can be configured with only the location of the resource server.¶
For example, an email client could provide an interface for a user to enter the URL of their JMAP server [RFC8620]. The email client would make a request to the JMAP server to discover the authorization server, then initiate an OAuth authorization flow to obtain tokens.¶
This specification extends the WWW-Authenticate response header defined by OAuth 2.0 Bearer Token Usage [RFC6750] to include an optional issuer URI (defined in OAuth 2.0 Authorization Server Metadata [RFC8414]) of the authorization server.¶
This specification is intended for use with access-controlled HTTP resources that conform to a standardized or well-known format or protocol. When such resources proliferate, it becomes impractical for clients to maintain advance knowledge about every HTTP origin that offers such a resource. Instead, in this specification, the client is presumed to be configured with a URI for this resource at runtime.¶
At present, access control in this situation is generally limited to the HTTP Basic and Digest authentication schemes. These schemes use only a simple username and password, and cannot support modern authentication capabilities such as Two-Factor Authentication, Single Sign-On, and password recovery flows. This specification enables clients to make use of these richer authentication procedures via the OAuth 2.0 system.¶
This specification can be used whether or not the authorization server has prior knowledge of the specific client implementation. For example, an authorization server might restrict authorization to a small number of well-known clients, or it might authorize any compatible client.¶
Authorization Server Discovery allows an unrecognized resource to initiate an OAuth 2.0 authorization flow. This carries significant security risks; see Section 7 for details.¶
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", "Authorization Code", "Authorization Endpoint", "Authorization Server", "Client", "Client Authentication", "Client Identifier", "Client Secret", "Grant Type", "Protected Resource", "Redirection URI", "Refresh Token", "Resource Owner", "Resource Server", "Response Type", and "Token Endpoint" defined by [RFC6749], as well as "Issuer", and "Issuer Identifier" defined by [RFC8414].¶
The following is a typical end-to-end flow implemented according to the specification. Note that while this example uses the OAuth 2.0 Authorization Code flow, a similar sequence could also be implemented with any other OAuth flow as well.¶
+----------+ +--------------+ | | | | | |-------(1) resource request-------------->| | | | | | | |<--(2) authorization server issuer--------| Resource | | | | Server | | Client | | | | |-------(7) resource request ------------->| | | | | | | |<-----(8) protected resource -------------| | | | +--------------+ | | | | | | +---------------+ | |-------(3) AS metadata request---------->| | | | | | | |<-----(4) AS metadata response-----------| | | | | | | | +-------+ | | | |->| | | | | | | |--(5) authorization request-->| | | | | User | | | | | | Agent |<-----------[...]------------>| Authorization | | | | | | Server | | |<-| | | | | | +-------+ | | | | | | | |<-------- (6) access token --------------| | | | | | +----------+ +---------------+¶
WWW-Authenticate header including the issuer URI of the authorization server.¶
This specification introduces a new parameter in the WWW-Authenticate response to indicate the issuer URI of the authorization server:¶
issuerThe issuer identifier of the authorization server.¶
The response below is an example of a WWW-Authenticate header that includes the issuer URL.¶
HTTP/1.1 400 Bad Request
WWW-Authenticate: Bearer error="invalid_request",
error_description="No access token was provided in this request",
issuer="https://as.example.com/issuer1"
¶
The HTTP status code and error string in the response are defined by [RFC6750].¶
The issuer parameter MAY be combined with other parameters defined in other extensions, such as the max_age parameter defined by [I-D.ietf-oauth-step-up-authn-challenge].¶
At any point, for any reason determined by the resource server, the resource server MAY respond with a new WWW-Authenticate challenge, including a new value for the issuer. If the client receives a WWW-Authenticate response indicating that its current token is no longer valid, it is expected to start a new authorization flow, and SHOULD use the new issuer value indicated in the response. This enables a resource server to change which authorization server it uses without any other coordination with clients.¶
The way in which the client identifier is established at the authorization server is out of scope of this specification.¶
This specification is intended to be deployed in scenarios where the client has no prior knowledge about the resource server, and the resource server might or might not have prior knowledge about the client.¶
There are some existing methods by which an unrecognized client can make use of an authorization server, such as using Dynamic Client Registration [RFC7591] to register the client prior to initiating the authorization flow. Future extensions may define alternatives, such as using a URL to identify clients.¶
The client is expected to fetch the authorization server metadata based on the value of the issuer returned by the resource server. Since this specification is designed to allow clients to interoperate with RSs and ASs it has no prior knowledge of, this opens a risk for SSRF attacks by malicious users or malicious resource servers. Clients SHOULD take appropriate precautions against SSRF attacks, such as blocking requests to internal IP address ranges. Further recommendations can be found in the OWASP SSRF Prevention Cheat Sheet.¶
This specification assumes that the desired HTTP resource is identified by a user-selected URL. If this resource is malicious or compromised, it could mislead the user into revealing their account credentials or authorizing unwanted access to OAuth-controlled capabilities. This risk is reduced, but not eliminated, by following best practices for OAuth user interfaces, such as providing clear notice to the user, displaying the authorization server's domain name, supporting the use of password managers, and applying heuristic checks such as domain reputation.¶
If the client does know the identity of the authorization server in advance, it SHOULD ignore the issuer=... parameter. Otherwise, an attacker who compromises the resource server could mount a phishing attack via the authorization flow.¶
Resource servers MAY return other WWW-Authenticate headers indicating various authentication schemes. This allows the resource server to support clients who may or may not implement this specification, and allows clients to choose their preferred authentication scheme.¶
The editors of this draft would like to thank the attendees of the IETF 115 OAuth Working Group and HTTP API Working Group where this proposal was initially presented. The editors would also like to thank....¶