|Internet-Draft||OAuth 2.0 Authorization Server Discovery||November 2022|
|Parecki & Schwartz||Expires 1 June 2023||[Page]|
- OAuth Working Group
- Intended Status:
- Standards Track
OAuth 2.0 Authorization Server Discovery
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.¶
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 --------------| | | | | | +----------+ +---------------+¶
- The client makes a request to a protected resource without presenting an access token.¶
- The resource server responds with the
WWW-Authenticateheader including the issuer URI of the authorization server.¶
- The client builds the authorization server metadata URL from the provided issuer identifier according to [RFC8414], and makes a request to fetch the authorization server metadata.¶
- The authorization server responds with the metadata document according to [RFC8414].¶
- The client directs the user agent to the authorization server to begin the authorization flow.¶
- The authorization exchange is completed and the authorization server returns an access token to the client.¶
- The client repeats the resource request from step 1, presenting the newly obtained access token.¶
- The resource server returns the requested protected resource.¶
This specification introduces a new parameter in the
WWW-Authenticate response to indicate the issuer URI of the authorization server:¶
The issuer identifier of the authorization server.¶
The response below is an example of a
WWW-Authenticate header that includes the
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"¶
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.¶
- 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/info/rfc2119>.
- Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", RFC 6749, DOI 10.17487/RFC6749, , <https://www.rfc-editor.org/info/rfc6749>.
- Jones, M. and D. Hardt, "The OAuth 2.0 Authorization Framework: Bearer Token Usage", RFC 6750, DOI 10.17487/RFC6750, , <https://www.rfc-editor.org/info/rfc6750>.
- 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/info/rfc8174>.
- Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 Authorization Server Metadata", RFC 8414, DOI 10.17487/RFC8414, , <https://www.rfc-editor.org/info/rfc8414>.
- Bertocci, V. and B. Campbell, "OAuth 2.0 Step-up Authentication Challenge Protocol", Work in Progress, Internet-Draft, draft-ietf-oauth-step-up-authn-challenge-06, , <https://www.ietf.org/archive/id/draft-ietf-oauth-step-up-authn-challenge-06.txt>.
- 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/info/rfc7591>.
- Jenkins, N. and C. Newman, "The JSON Meta Application Protocol (JMAP)", RFC 8620, DOI 10.17487/RFC8620, , <https://www.rfc-editor.org/info/rfc8620>.