Web Authorization Protocol S. F. Lee Internet-Draft 16 October 2026 Intended status: Informational Expires: 19 April 2027 OAuth Scope Metadata Document draft-forten-oauth-scope-metadata-document-00 Abstract This document describes how an OAuth scope value that is an HTTPS URI can be dereferenced to obtain a JSON document describing that scope. The document is descriptive only and does not change the authorization meaning of the scope. Dereferencing follows the pattern and security rules of the OAuth Client ID Metadata Document. About This Document This note is to be removed before publishing as an RFC. 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/. 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 19 April 2027. Copyright Notice Copyright (c) 2026 IETF Trust and the persons identified as the document authors. All rights reserved. Lee Expires 19 April 2027 [Page 1] Internet-Draft OAuth Scope Metadata Document October 2026 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 Definitions . . . . . . . . . . . . . . . 3 2. Scope Metadata URI . . . . . . . . . . . . . . . . . . . . . 3 3. Scope Metadata Document . . . . . . . . . . . . . . . . . . . 3 4. Retrieval . . . . . . . . . . . . . . . . . . . . . . . . . . 4 5. Processing Rules . . . . . . . . . . . . . . . . . . . . . . 5 6. Security Considerations . . . . . . . . . . . . . . . . . . . 5 7. Privacy Considerations . . . . . . . . . . . . . . . . . . . 5 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 5 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 5 9.1. Normative References . . . . . . . . . . . . . . . . . . 5 9.2. Informative References . . . . . . . . . . . . . . . . . 6 Appendix A. Related Work . . . . . . . . . . . . . . . . . . . . 7 Appendix B. Open Issues . . . . . . . . . . . . . . . . . . . . 7 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 7 1. Introduction Scope values are opaque strings (Section 3.3 of [RFC6749]). A client or authorization server that receives a scope from a protected resource it has not seen before has no way to learn what the scope means. The problem is most visible when a single authorization server serves many protected resources behind a gateway. From the scope string alone, the authorization server cannot tell which resource defined it, and scope names may collide across resources. An AI agent acting as a client without prior arrangement has no basis for choosing which scope to request. This document lets the scope value itself be an HTTPS URI from which a description can be obtained. Because the value is the location of its description, no separate discovery and no mapping between scopes and resources is needed. Lee Expires 19 April 2027 [Page 2] Internet-Draft OAuth Scope Metadata Document October 2026 1.1. 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. 2. Scope Metadata URI A Scope Metadata URI is a scope value that adopts the constraints [CIMD] places on a client_id URL: * its scheme is "https"; * it contains a path component; * it MUST NOT contain a fragment, user information, or dot segments; * it SHOULD NOT contain a query component. The entire scope-token (Section 3.3 of [RFC6749]) MUST be a single URI meeting these constraints. A scope value that does not is not a Scope Metadata URI and is processed as an opaque string as in [RFC6749]. In a space-delimited list of scopes, each scope-token is evaluated separately. 3. Scope Metadata Document A Scope Metadata Document is a JSON object [RFC8259], served with a 200 status code and the media type "application/json". It has the following members, whose names and meanings are aligned with the type metadata of [I-D.ietf-oauth-rar-metadata-remediation]. description OPTIONAL. A JSON string containing a human-readable description of what the scope permits. documentation_uri OPTIONAL. A JSON string containing a URI of further documentation. Recipients MUST ignore members they do not understand. The document does not carry information used for authorization decisions, such as permitted ranges or inclusion relationships with other scopes. Example request and response: Lee Expires 19 April 2027 [Page 3] Internet-Draft OAuth Scope Metadata Document October 2026 GET /scopes/files/write HTTP/1.1 Host: gw.example.com Accept: application/json HTTP/1.1 200 OK Content-Type: application/json Cache-Control: max-age=86400 { "description": "Create and modify files in the drive.", "documentation_uri": "https://docs.example.com/scopes#files-write" } 4. Retrieval A dereferencing party (an authorization server or a client) MUST dereference only Scope Metadata URIs that start with a trusted prefix. How trusted prefixes are configured is a matter of deployment policy. The dereferencing party sends an HTTP GET to the URI. As in [CIMD]: * it MUST NOT automatically follow redirects; * it treats any status code other than 200 as a failure; * it MUST NOT retrieve a URI that resolves to a special-purpose IP address [RFC6890]; * it SHOULD limit response size, and caches responses according to [RFC9111]. In addition to [CIMD], the dereferencing party MUST apply the special-purpose address check to the address it actually connects to, not only to the result of an earlier DNS lookup, and SHOULD limit retrieval time. If retrieval fails or the document does not conform to Section 3, then, unlike [CIMD], which aborts the authorization request in that case, the dereferencing party MUST retain the scope value as received and MUST NOT reject an authorization request solely because dereferencing failed; the scope value continues to be processed as an opaque string as in [RFC6749]. It SHOULD cache the failure for a period to avoid repeated retrieval. Lee Expires 19 April 2027 [Page 4] Internet-Draft OAuth Scope Metadata Document October 2026 5. Processing Rules The document is descriptive only. An authorization server MAY use it in a consent screen, and a client MAY use it when choosing scopes to request. The authorization server and the protected resource MUST NOT use it as the basis for granting or enforcing access. 6. Security Considerations SSRF: The dereferencing party retrieves a URI it received from elsewhere. The trusted prefix restriction and the special-purpose address prohibition (Section 4) apply together, and the SSRF considerations of [CIMD] apply in full. A check made only at an initial DNS lookup can be bypassed by DNS rebinding, which is why the address check applies to each connection. Forged descriptions: An attacker could publish a misleading description to induce user consent. Trusted prefixes reduce this risk, but the party controlling documents under a prefix still has to be trusted. Prompt injection: A client based on a large language model MUST treat the description as data, not as instructions. 7. Privacy Considerations The party hosting documents can observe from retrieval requests which client or authorization server handles which scope, and when. Dereferencing parties use caching to reduce retrieval frequency and MUST NOT include user-identifying information in requests. 8. IANA Considerations This document has no IANA actions. 9. References 9.1. Normative References [CIMD] Parecki, A. and E. Smith, "OAuth Client ID Metadata Document", Work in Progress, Internet-Draft, draft-ietf- oauth-client-id-metadata-document-02, 6 July 2026, . Lee Expires 19 April 2027 [Page 5] Internet-Draft OAuth Scope Metadata Document October 2026 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", RFC 6749, DOI 10.17487/RFC6749, October 2012, . [RFC6890] Cotton, M., Vegoda, L., Bonica, R., Ed., and B. Haberman, "Special-Purpose IP Address Registries", BCP 153, RFC 6890, DOI 10.17487/RFC6890, April 2013, . [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, . [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", STD 90, RFC 8259, DOI 10.17487/RFC8259, December 2017, . [RFC9111] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, Ed., "HTTP Caching", STD 98, RFC 9111, DOI 10.17487/RFC9111, June 2022, . 9.2. Informative References [AAUTH] Hardt, D., "AAuth Protocol", Work in Progress, Internet- Draft, draft-hardt-oauth-aauth-protocol-11, 25 September 2026, . [I-D.ietf-oauth-rar-metadata-remediation] Zehavi, Y., "OAuth 2.0 RAR Metadata and Error Remediation", Work in Progress, Internet-Draft, draft- ietf-oauth-rar-metadata-remediation-00, 23 August 2026, . [RFC9396] Lodderstedt, T., Richer, J., and B. Campbell, "OAuth 2.0 Rich Authorization Requests", RFC 9396, DOI 10.17487/RFC9396, May 2023, . Lee Expires 19 April 2027 [Page 6] Internet-Draft OAuth Scope Metadata Document October 2026 [UMA2-FEDAUTHZ] Maler, E., Ed., Machulak, M., and J. Richer, "Federated Authorization for User-Managed Access (UMA) 2.0", Kantara Initiative Recommendation, 7 January 2018, . [UMA-RSR] Hardjono, T., Ed., "OAuth 2.0 Resource Set Registration", Kantara Initiative Recommendation, Version 1.0.1, 28 December 2015, . Appendix A. Related Work * UMA 1.0 [UMA-RSR] required that a scope URI resolve to a scope description document. UMA 2.0 [UMA2-FEDAUTHZ] relaxed this to MAY and does not expect the authorization server to resolve scope descriptions at run time. This document extends the idea to OAuth in general and adds guardrails. * [CIMD] is the source of the dereferencing pattern and security rules. * [I-D.ietf-oauth-rar-metadata-remediation] is the source of the member names. * AAuth [AAUTH] places scope descriptions inline in resource metadata. In this document, the scope value itself is the location of its description. Appendix B. Open Issues This section is to be removed before publishing as an RFC. 1. If [I-D.ietf-oauth-rar-metadata-remediation] factors out a common metadata object, whether Section 3 should reference it instead. 2. Whether a Scope Metadata URI should also be usable as an authorization details type identifier [RFC9396]. 3. How a dereferencing party trusts Scope Metadata URIs of a previously unknown resource, for which no trusted prefix is configured (for example, based on the origin from which the protected resource metadata was obtained). Author's Address Su-hyeon Forten Lee Lee Expires 19 April 2027 [Page 7] Internet-Draft OAuth Scope Metadata Document October 2026 Email: nine01223@naver.com Lee Expires 19 April 2027 [Page 8]