OAuth Scope Metadata Document

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.¶

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

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.¶

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:¶

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.¶

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.¶

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