Skip to main content

OAuth2 Scopes

Scope design

When designing a system that uses OAuth2, you have to decide how scopes map to resources that the client will attempt to access. "Resource access" is typically a specific REST-style HTTP operation on a specific URL, e.g. POST /products/staplers/1.

Broad scopes are generally high level e.g., a scope that gives access to a certain use case or larger group of resources. Narrow scopes are often low-level e.g., a scope that gives read access to a specific resource, limited set of resources or operations. Examples scopes for an employee that's authorized to buy supplies for their employer:

  • Very broad: buyer
  • Broad: buyer office (office supplies only)
  • Broad: buyer lt-1000 (orders less than 1000 euros)
  • Narrower: buyer office:staplers (staplers only)
  • Very narrow: buyer office:staplers:red lt-10 (red staplers only, less than 10 euros)

How scopes are mapped to operations on resources influences:

  • How often clients need to request a new access token, if the previous token does not give access to a required resource.
  • When access to a specific resource is authorized: when the access token is issued, or when it's used.

Broad, high-level Scopes

High-level, broad scopes typically give access to an entire use case, service, or group of resources. Checks that are executed before an access token is issued are limited to the Verifiable Credentials the client can present.

  • Identification and authentication (user/client identity)
  • General user access to the functionality (e.g. is admin, can buy supplies, etc.)

A real-life example of a broad scope is the Nuts eOverdracht use case, which specifies the following scopes:

  • eOverdracht-sender which gives access to the receiver's services required by a care organization that wants to transfer a patient to another organization.
  • eOverdracht-receiver which gives access to the sender's services to the transfer receiver.

However, when a resource is accessed, the system needs to verify that the scope gives access to the specific resource operation.

This type of scope is supported by the Nuts node.

Narrow, low-level Scopes

Narrow, low-level scopes typically give access to specific operations on specific resources, e.g. reading a specific patient's medical summary.

Back to top