Skip to main content

Scope-Based Access Control (SBAC)

Summary​

Scope-Based Access Control (SBAC) is an authorization model that derives access decisions from OAuth scopes granted to the requesting client. When a client obtains an access token, the token carries a set of scopes that define the operations the client can perform. SBAC policies evaluate whether the token's granted scopes include the scope required by the target resource. This model ties authorization directly to the OAuth consent and scope grant mechanism, making it the natural choice for API-level access control in OAuth-protected ecosystems.

Why It Exists​

OAuth 2.0 defines scopes as the mechanism for limiting what a client can do with an access token. However, OAuth itself does not enforce scope-based authorization at the resource level — it grants scopes during token issuance and leaves enforcement to the resource server. SBAC closes this gap by providing a policy model that evaluates scope grants as authorization decisions. This ensures that resource servers enforce scope boundaries consistently through the same policy evaluation pipeline used by other authorization models.

Where It Fits in Keymate​

SBAC connects the OIDC and OAuth interaction model to the authorization model. During token issuance, the platform grants scopes based on client configuration and user consent. At request time, SBAC policies evaluate the token's scopes against the resource and scope requirements. The policy evaluation engine evaluates SBAC alongside other models, and the gateway enforcement layer enforces the resulting decision.

Boundaries​

This page covers scope-based authorization as a policy model. It does not cover:

How It Works​

Scope Grant and Token Issuance​

When a client requests an access token, it specifies the scopes it needs. The platform evaluates the request against:

  • The client's allowed scopes (configured during client registration)
  • The user's consent decisions (for user-facing applications)
  • The resource's available scopes (defined in the resource catalog)

The resulting access token carries the intersection of requested and allowed scopes. These granted scopes represent the upper bound of what the client can do with the token.

SBAC Policy Evaluation​

An SBAC policy binds to a resource and specifies the required scope. When a request arrives:

  1. The platform identifies the target resource and the required scope
  2. The platform reads the granted scopes from the access token
  3. The SBAC policy checks whether the required scope appears in the token's granted scopes
  4. If the scope is present, the policy returns GRANT; otherwise, it returns DENY

Resource-Scope Mapping​

Resources define which scopes apply to them. A resource representing an API endpoint might require different scopes for different operations:

  • read scope for GET requests
  • write scope for POST and PUT requests
  • delete scope for DELETE requests
  • admin scope for administrative operations

SBAC policies evaluate the specific scope required for the requested operation, not the full set of scopes on the token.

Client-Level and User-Level Scoping​

SBAC operates at two levels:

  • Client-level scopes control what the application itself can access, regardless of which user is authenticated. If a client's registration does not include the admin scope, no user authenticated through that client can access admin resources — even if the user holds an admin role.
  • User-level scopes further restrict access based on the user's consent or the user's available scopes. The effective scope is the intersection of client-level and user-level grants.

Composition with Other Models​

SBAC policies compose with other authorization models through PBAC or the decision strategy:

  • SBAC + RBAC — require both a valid scope grant and a matching role. The scope ensures the client application has permission; the role ensures the user has permission.
  • SBAC + ABAC — combine scope checks with attribute-based conditions for context-aware API authorization.

Diagram​

Example Scenario​

Scenario​

A mobile application registers with scopes read and write but not delete. A user authenticates through the mobile app and receives an access token carrying read and write scopes. The user attempts to delete a record through the app.

Input​

  • Actor: Authenticated user via mobile application
  • Resource: Record management API requiring delete scope
  • Action: Delete a record
  • Context: Access token carries read and write scopes. SBAC policy requires delete scope.

Expected Outcome​

  • Denied — The SBAC policy checks the token's granted scopes and finds that delete is not present. The policy returns DENY regardless of the user's roles or other permissions.
  • Why: SBAC enforces scope boundaries from the token. The mobile application's client registration excludes the delete scope, so no token issued to this client can carry it. The scope limitation protects against unintended operations through constrained clients.

Common Misunderstandings​

  • "Scopes and roles are the same thing" — No. Scopes limit what the client application can do; roles limit what the user can do. A user with the "admin" role accessing through a client without the "admin" scope cannot perform admin operations. Both checks must pass.

  • "All scopes in the token grant access to all resources" — No. SBAC evaluates the specific scope required by the target resource. A token with read and write scopes cannot access a resource that requires admin, even though the token carries other valid scopes.

  • "SBAC alone provides complete authorization" — SBAC verifies scope presence in the token. It does not evaluate who the user is, what role they hold, or under what conditions they access. Combine SBAC with RBAC or ABAC for comprehensive authorization.

warning

Do not use overly broad scopes (such as a single all scope) that bypass SBAC's value. Broad scopes defeat the purpose of scope-based restriction by granting blanket access regardless of the operation.

Design Notes / Best Practices​

  • Define scopes that correspond to meaningful operations (read, write, delete, admin) rather than fine-grained actions. Too many scopes increase management complexity; too few reduce access control granularity.
  • Use SBAC as the first authorization layer for API access. Scope checks are fast and eliminate unauthorized operations early before more expensive policy evaluations (ABAC, RADAC) execute.
  • Configure client registrations with the minimum required scopes. Each client should receive only the scopes it needs for its use case, following the principle of least privilege.
tip

When designing a new API, define scopes alongside the API specification. Map each endpoint operation to a required scope, and document the mapping in the API reference. This makes SBAC policy configuration straightforward for administrators.

  • Restricting mobile application clients to read-only scopes
  • Preventing third-party integrations from accessing administrative operations
  • Combining scope checks with role checks for API-level defense in depth
  • Enforcing scope boundaries across microservices in a multi-application environment

Authorization Model

Multi-model framework that SBAC operates within

OIDC & OAuth Interaction Model

Scope grant during token issuance

Resources & Scopes

Resource and scope definitions that SBAC evaluates

RBAC

Role-based model that complements scope checks