Do not treat a scope as a resource permission

Protection need

An API must ensure that the current subject can perform one action on one resource in its current tenant and state. OAuth scope usually describes authority requested or granted to a client. It does not, by itself, name every protected object, prove ownership, or encode the application's complete policy.

Security objectives and requirements

Define the terms:

• A scope constrains delegated token authority for a client and resource server.
• A role groups expected responsibilities.
• An entitlement is an assigned access right or package.
• Consent records a user's grant to a client within policy limits.
• A permission is the application's allow for a subject, action, and resource.

The resource server validates issuer, audience, token status, subject or client, and scope. It then performs its own tenant, object, action, relationship, and state checks.

Security invariants and evidence

• A token for one audience never authorizes another resource server.
• A broad scope never skips object and action authorization.
• Client identity and human subject identity remain distinct.
• Revoked or changed application authority takes effect within a stated time.
• Decision evidence records both the token constraints and local permission result.

Failure cases

• The API maps write to every write function and tenant.
• A token intended for one resource is accepted by another.
• A client-credentials token is treated as a human user.
• User consent is treated as administrator approval.
• A role or entitlement remains after the application's relationship changed.
• Token introspection succeeds, so the application skips local permission checks.

Design tradeoffs and residual risk

Fine scopes can reduce token authority but create vocabulary and consent complexity. Coarse scopes are easier to manage but leave more work to application policy. Putting dynamic object IDs in scopes can create token growth, disclosure, and revocation problems.

Use scopes to bound token use. Keep fast-changing object permission close to the application that owns it.

Pomerium boundary

Pomerium can authenticate the requester, authorize a route, and pass verified identity context. It does not convert an OAuth scope into permission for an upstream record or action. The resource server must validate tokens it accepts and enforce its own permission model.

Exercise

Take an API with read and write scopes, two tenants, three object types, and an approval action. Build a table that separates token validation from local authorization. Add tests for the wrong audience, another tenant's object, an administrative action, a client-only token, and a revoked relationship.

Evaluation checklist

• Can the design define scope, role, entitlement, consent, and permission separately?
• Does the resource server validate issuer, audience, status, and granted scope?
• Does every action still receive an object and application-policy check?
• Are client and user authority represented without identity collapse?
• Can local permission changes take effect without waiting for every token to expire?