| Internet-Draft | extensions for Scope | March 2026 |
| Chen, et al. | Expires 2 September 2026 | [Page] |
This specification defines an extension to the OAuth 2.0 scope
parameter, as specified in RFC 6749, which is used to express the
permissions granted to an access token. The proposed extension
introduces a structured syntax for scope values to enable fine-grained
authorization for the installation and execution of Modular Capability
Units (encapsulated and reusable functional modules such as skills)
within Agent ecosystems. However, current mechanisms for authorizing
such modules generally lack a standardized way to express and obtain
consent for the complex, fine-grained permissions they require during
installation.¶
This document addresses this limitation by defining a structured
format for the scope parameter. The format extends the simple space-
delimited strings with a colon-separated syntax:
[resource_type]:[action]:[target][:constraints]. This syntax allows
for the precise description of permissions for operations such as
file system access, command-line execution, network access, tool
invocation, and scheduled tasks. These extensions provide a
standardized, machine-readable way to request, convey, and validate
detailed permissions, thereby enhancing users' security control over
their resources while maintaining compatibility with the existing
OAuth token issuance and validation flows.¶
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 2 September 2026.¶
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.¶
The OAuth 2.0 scope parameter [RFC6749] serves as a widely adopted mechanism for expressing permissions, defining the access token's authority. However, in emerging scenarios such as the installation and execution of third-party skills within Agent ecosystems which require the declaration of complex, fine-grained operational permissions its expressive power becomes limited.¶
scope Extensions in AI Agent Ecosystems
In current Agent architectures, users typically extend their Agent's functionality by installing third-party developed Modular Capability Units. These Modular Capability Units MAY be specifically called "Skills" etc.,¶
but their essence is installable components that add specific capabilities to an Agent. However, this installation process presents significant security and privacy risks:¶
Lack of Source Authentication: Users cannot verify the identity of the capability module's publisher or the integrity of its code.¶
Coarse-Grained or No Permission Control: During installation, capability modules either obtain all requested permissions (often presented as a broad, unstructured list) or rely entirely on user trust, lacking a standardized process for fine-grained, interactive authorization confirmation at installation time.¶
Runtime Permission Abuse Risk: Once installed, capability modules MAY access local or remote resources with permissions exceeding user expectations.¶
The OAuth 2.0 framework [RFC6749] provides a
standardized mechanism for delegated authorization. This proposal
applies this framework to the Agent skill authorization model and,
crucially, extends the OAuth scope parameter to support the
expression of fine-grained permissions required by Modular Capability Units such as skills.
This allows the installation and execution of a skill to be modeled
as a process where a client obtains user consent for a specific set
of structured permissions (scope), which are then executed during
resource access.¶
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 document uses the terms "Authorization Server" (AS), "Client", "Resource Server" (RS), and "Access Token" as defined in The OAuth 2.0 Authorization Framework [RFC6749].¶
scope Format Extension
To meet the needs of Agent skills for describing complex, fine-
grained operation permissions, this specification defines a
structured extension to the OAuth scope parameter value syntax,
building upon the ABNF defined in [RFC6749] :¶
The value of the scope parameter is expressed as a list of
space-delimited, case-sensitive structured scope tokens.
The syntax for a structured scope token is defined as:¶
structured-scope-token = resource-type
":" action
":" target
[ ":" constraints ]
[ ":" reserve ]
resource-type = 1*( %x21-2F ; visible chars except ":" and ";"
/ %x30-3A
/ %x3C-7E
)
action = 1*( %x21-2F / %x30-3A / %x3C-7E )
target = 1*( %x21-2F / %x30-3A / %x3C-7E )
constraints = constraint *( ":" constraint )
constraint = 1*( %x21-2F ; often key=value pairs
/ %x30-3A
/ %x3C-7E
)
¶
resource-type: Identifier for the type of resource. This field is REQUIRED. New
types introduced by this extension include:¶
fs: File system operations.¶
cmd: Command-line execution.¶
net: Network access.¶
tool: Tool/API invocation.¶
scheduler: Scheduled tasks.¶
othertype: Other resource types are reserved for resource types not defined in this specification. the specific semantics of other resource types are defined by the target component and/or through agreement between the AS and RS.¶
action: The operation permitted on the specific resource
type. This field is REQUIRED. For example:¶
For fs: read, write, list, delete.¶
For cmd: execute.¶
For net: connect, send, receive.¶
For tool: invoke.¶
For scheduler: create, read, update, delete.¶
For all resource-type: otheraction (Other operations. The precise operation is defined by the combination of resource-type and target. Implementations MUST be prepared to handle unknown action values for a given resource-type`.)¶
target: Identifier for the target of the operation. This field is REQUIRED. Its
syntax and meaning depend on resource-type and action.
For example:¶
File path: /home/user/documents/*¶
Command line: /usr/bin/git¶
Network endpoint: api.example.com:443¶
Tool ID: weather_forecast¶
Scheduled task ID: daily_backup¶
When resource-type is othertype or action is otheraction, the target field MAY contain an implementation-specific or a more complex structured identifier (e.g., a URI or a name spaced string.¶
constraints (Optional): Additional constraints on the
authorization, in the form of key=value pairs. This field is OPTIONAL. Multiple
constraints are separated by :. For example:¶
Time constraints: expires=2026-12-31T23:59:59Z,
duration=PT2H (2 hours).¶
Logical constraints: if_condition=user_consented.¶
Regex constraints:
path_regex=^/home/user/[^/]+/\.config$.¶
Recursion and depth limits:
recursive=true:max_depth=5.¶
Authorization and resource servers SHOULD ignore any constraint key they do not understand.¶
reserve (Optional): A reserved field for future extensibility. This field is OPTIONAL. This field contains an opaque string whose syntax and semantics are defined by a future specification. Implementations that do not understand the content of the reserve field MUST ignore it. This provides a standardized location for future extensions without breaking existing parsers.¶
This structured extension itself is optional to implement. When parsing the scope value, the authorization server and resource server SHOULD first verify if a token's format conforms to the structured syntax defined in this specification. A token is interpreted and processed as a structured scope only if the format is strictly compliant; otherwise, it MUST be treated as a plain (non-extended) scope token.¶
Clients, AS, and RS implementing this specification SHOULD be designed to tolerate unknown values in the resource-type, action, and constraint keyfields. The preferred behavior upon encountering an unknown component is to treat that specific structured scope token as not granting the requested permission, rather than failing the entire request or token validation, unless a policy explicitly mandates strict validation of all components.¶
scope parameter values
Example scope parameter values (each line represents one possible
space-delimited token within a scope string):¶
fs:read:/home/user/documents/:recursive=true:max_depth=5 cmd:execute:/usr/bin/git net:connect:api.example.com:443 tool:invoke:weather_forecast scheduler:create::interval=P1D (create a daily task)¶
The authorization server MAY fully or partially ignore the scope
requested by the client, based on the authorization server policy or
the resource owner's instructions. If the issued access token scope
is different from the one requested by the client, the authorization
server MUST include the "scope" response parameter to inform the
client of the actual scope granted, as per [RFC6749].¶
scope Validation and Least Privilege: Authorization Servers and
Resource Servers MUST strictly enforce validation of the
structured scope. The granted permissions scope_granted
MUST be a subset explicitly consented to by the user. When
processing requests, the Resource Server MUST verify that the
token's scope contains a structured token that precisely
matches the requested operation, including resource-type,
action, target, and any constraints.¶
Skill Metadata Integrity: The Authorization Server's
authentication of the skill's source and integrity (Step D) is
critical. Strong cryptographic signatures (e.g., code signing
certificates) SHOULD be used to prevent injection or tampering
with malicious skills, especially their advertised
scope_initial.¶
User Consent Interface: The authorization consent interface
(Step E) MUST clearly and unambiguously present the specific
meaning of the structured scope_request tokens to the user,
avoiding situations where users over-authorize due to
misunderstanding.¶
When a request is denied due to a failure in validating the structured scope(e.g., malformed syntax, unsupported resource-typeor action), the AS returns an error response with the following error code:¶
Error Code: scope_validation_failed¶
Description: The requested structured scope is invalid, malformed, or contains unsupported values.¶
The AS SHOULD include an error_description parameter to provide developers with more specific diagnostic information (e.g., "Unrecognized resource-type: 'custom_db'", "Malformed constraints segment").¶
This specification requests the registration of the following error code in the OAuth Extensions Error Registry:¶
Error Code: scope_validation_failed¶
This document based on RFC6749¶