]>

nine01223@naver.com

Security Web Authorization Protocol OAuth scope metadata 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 Discussion of this document takes place on the Web Authorization Protocol Working Group mailing list (mailto:oauth@ietf.org), which is archived at .

Introduction Scope values are opaque strings (). 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.

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 when, and only when, they appear in all capitals, as shown here.

Scope Metadata URI A Scope Metadata URI is a scope value that adopts the constraints 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 () 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 . In a space-delimited list of scopes, each scope-token is evaluated separately.

Scope Metadata Document A Scope Metadata Document is a JSON object , 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 .

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:

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 :

• 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 ;
• it SHOULD limit response size, and caches responses according to .

In addition to , 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 , then, unlike , 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 . It SHOULD cache the failure for a period to avoid repeated retrieval.

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.

Security Considerations SSRF: The dereferencing party retrieves a URI it received from elsewhere. The trusted prefix restriction and the special-purpose address prohibition () apply together, and the SSRF considerations of 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.

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.

IANA Considerations This document has no IANA actions.

References Normative References Work in Progress Informative References Work in Progress Kantara Initiative Recommendation, Version 1.0.1 Kantara Initiative Recommendation Work in Progress

Related Work

• UMA 1.0 required that a scope URI resolve to a scope description document. UMA 2.0 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.
• is the source of the dereferencing pattern and security rules.
• is the source of the member names.
• AAuth places scope descriptions inline in resource metadata. In this document, the scope value itself is the location of its description.

Open Issues

1. If factors out a common metadata object, whether should reference it instead.
2. Whether a Scope Metadata URI should also be usable as an authorization details type identifier .
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).