Scope

A scope is a space-separated list of case-sensitive strings that represent discrete permissions. Each string corresponds to a specific access right the client application requests. Common examples include:

• read:user for viewing a user's profile.
• write:repo for committing code to a repository.
• openid and email for identity claims in OpenID Connect. The authorization server validates requested scopes against those registered for the client and those the resource owner is authorized to grant.

During the authorization flow, requested scopes are presented to the resource owner (the user) in a human-readable format as part of the consent screen. The user can approve or deny the entire request or, if supported, selectively approve individual scopes. The final set of granted scopes is encoded into the resulting access token, typically within the scope claim of a JWT. The resource server must validate that the token's scopes permit the requested action.

Scopes can be assigned dynamically or statically:

• Dynamic Scopes: Requested at runtime by the client application. The authorization server evaluates these per authorization request.
• Static Scopes: Pre-configured and associated with a client's registration. The client may only request from this pre-approved list. This distinction is crucial for security governance, as static scopes limit the potential damage from a compromised client, while dynamic scopes offer greater flexibility for user-centric applications.

While the OAuth 2.0 framework does not define a formal hierarchy, scope design often implies one for API design clarity. For example, admin:write may be considered a superset of user:write. Authorization server logic must enforce these implied relationships. Organizations also define custom, domain-specific scopes for their APIs (e.g., process:invoice, launch:rocket). These must be documented in the API's authorization server and clearly communicated to integrating developers.

Scopes and RBAC are complementary but distinct authorization models:

• Scopes answer "what can this token do?" They are attached to the access token and define permissible actions on APIs.
• RBAC answers "what is this user allowed to do?" It is a system of user roles and permissions managed within the application or identity provider. In a common pattern, a user's RBAC roles are evaluated during authentication, and the resulting permissions are mapped to OAuth scopes issued in the token. The resource server then authorizes based solely on the token's scopes.

Proper scope implementation is critical for the principle of least privilege. Key practices include:

• Use precise, action-oriented scope names (e.g., files:read not just access).
• Validate scopes on both the authorization and resource servers.
• Implement incremental authorization, allowing users to grant additional scopes in future sessions without re-consenting to previously granted ones.
• Document all available scopes and their semantics for API consumers.
• Limit the lifetime and use of refresh tokens to control the duration of granted scopes.

An access token is a credential used in OAuth 2.0 to access protected resources on behalf of a user or client. It is a bearer token that contains authorization information, such as the client identity, user identity, granted scopes, and an expiration time. The resource server validates the token's signature and checks that the token's scopes permit the requested action before granting access.

• Bearer Credential: Possession of the token grants access; it must be kept secret.
• Limited Lifetime: Short-lived to minimize risk if compromised.
• Scope Enforcement: The token is only valid for the specific permissions (scopes) it was issued for.

OAuth 2.0 is the industry-standard authorization framework upon which the scope mechanism is defined. It enables a third-party application to obtain limited access to a user's resources on an HTTP service without sharing the user's credentials. Scopes are the primary vehicle for expressing this limited access.

• Delegated Authorization: Allows users to grant limited access to their data to another application.
• Flow-Based: Defines several grant types (e.g., Authorization Code, Client Credentials) for different client types.
• Scope-Centric: All access tokens issued under OAuth 2.0 are associated with a set of scopes defining the token's authority.

OpenID Connect is an identity layer built on top of OAuth 2.0. While OAuth scopes control access ("what can you do?"), OIDC introduces standard scopes to control identity information ("who are you?").

• Standard Identity Scopes: Defines scopes like openid, profile, email, and address to request specific user claim sets.
• ID Token: Returns a signed JWT containing user identity claims, separate from the OAuth access token.
• Hybrid Use: An AI agent might use OAuth scopes for API access and OIDC scopes to retrieve the user's basic profile for personalization.

Role-Based Access Control is a complementary authorization model often used in conjunction with OAuth scopes. RBAC assigns permissions to roles (e.g., 'admin', 'viewer'), and users are assigned to roles. In enterprise systems, the OAuth scope requested or granted might be derived from a user's RBAC role.

• Coarse-Grained vs. Fine-Grained: RBAC roles are typically broader, while OAuth scopes can be more granular.
• System-Level Enforcement: RBAC is often enforced inside the resource server after the OAuth token (with its scopes) has been validated.
• Example: A user with the 'Editor' RBAC role might be granted the content.read and content.write OAuth scopes automatically.

Token introspection is an OAuth 2.0 extension (RFC 7662) that allows a resource server to query the authorization server to check the active state of an access token and retrieve its metadata. This is a critical mechanism for scope validation in distributed systems.

• Active State Check: Confirms the token has not been revoked or expired.
• Metadata Retrieval: Returns a JSON response containing the token's scope, client_id, username, and expiration.
• Security Posture: Allows resource servers to defer to the central authorization server for the definitive truth about a token's permissions, ensuring consistent scope enforcement.

The consent screen is the user interface presented by the authorization server during the OAuth flow where the user reviews and approves the scopes being requested by the client application. It is the user's point of control for delegated permissions.

• Informed Consent: Clearly lists the scopes (e.g., "Read your email," "Update your profile") in human-readable language.
• Security Best Practice: A key defense against malicious applications requesting excessive permissions.
• Auditability: The user's grant of specific scopes is logged by the authorization server, creating an audit trail.