Join our Newsletter — 33% off our NHI Course

OAuth Scopes and Claims

OAuth scopes and claims are the permissions and identity details used to control what an access token can do and who or what is using it. Scopes define allowed actions or data access. Claims are assertions inside tokens, such as subject, issuer, roles, or tenant, that support authorization decisions and auditing.

What OAuth scopes and claims do

OAuth scopes and claims work together to constrain token use and make authorisation decisions more precise. Scopes express the access a token is allowed to request, while claims carry attributes that software can inspect to confirm the token’s issuer, subject, audience, tenant, or role context.

That distinction matters because scopes are usually coarse-grained and consent-oriented, whereas claims are data points used by resource servers, gateways, and policy engines to decide whether a request fits the intended trust boundary. The same token can therefore be broadly acceptable in one context and rejected in another if the claims do not match the resource or user relationship.

Why scopes and claims are paired

Scopes answer the question “what may this token do?”, while claims help answer “who or what is presenting it?” and “does this token belong in this context?”. In practice, many deployments use both: scopes to gate actions such as reading mail or writing data, and claims to validate tenancy, audience, identity assurance, or role-based entitlement.

This pairing is one reason OAuth can support both delegated access and machine-to-machine access without relying on a single, overloaded token field. When the design is sound, scopes limit blast radius and claims reduce the chance that a valid token is accepted by the wrong API, tenant, or workflow.

For the underlying protocol model, RFC 6749: The OAuth 2.0 Authorization Framework defines OAuth 2.0’s token-based access model, including how access is granted and constrained.

When readers need the practical identity-side model, the OAuth 2.0 and OpenID Connect Guide for Identity Teams explains how scopes, tokens, and OIDC claims fit together in real deployments.

Common claim types and how they affect authorisation

Some claims are foundational and appear in many systems. The iss claim identifies the token issuer, sub identifies the principal, and aud identifies the intended recipient. Others, such as roles, groups, tenant IDs, or authentication context values, are application-specific and often drive finer-grained access logic.

Claims become security-relevant when systems treat them as trustworthy inputs. A resource server may use a role claim to authorise a high-risk action, or a tenant claim to keep one customer’s data separate from another’s. If those claims are absent, stale, misread, or taken from the wrong token type, the result can be incorrect access decisions.

Claims also shape auditing because they make token use explainable after the fact. A log that records the token subject, issuer, and audience gives investigators a clearer trail than a token that only carries a broad scope string.

For identity detail and token context, OpenID Connect Core 1.0 shows how identity claims layer on top of OAuth to support authentication and session context.

How misuse of scopes and claims creates exposure

Problems usually appear when scopes are too broad, claims are overtrusted, or both are used as a substitute for real authorisation logic. A token with expansive scopes can expose more data or functionality than the user intended, while a weak claim check can allow the wrong subject, tenant, or audience to reuse a token successfully.

Another recurring issue is confusion between authentication and authorisation. A claim may prove that a token was issued, but that does not mean the request should be allowed. Likewise, a scope may say a client may access a resource class, but it does not prove the request is safe for every object or action inside that class.

That is why strong implementations combine scopes and claims with audience restriction, token validation, and explicit application-side policy checks. Where the resource is exposed through APIs, the access decision should be tied to the actual API object and operation, not just to a generic token statement.

For API-focused guidance, RFC 8707: Resource Indicators for OAuth 2.0 helps narrow tokens to the intended resource audience, reducing accidental overuse.

Where token misuse becomes an operational pattern, SaaS-to-SaaS and OAuth App Governance Guide covers consent, scopes, token risk, and revocation discipline for connected applications.

Practical design choices for safer token decisions

The safest pattern is to keep scopes narrow, make claims explicit, and treat both as inputs to policy rather than as policy by themselves. Use audience-restricted tokens where possible, avoid storing assumptions in custom claims unless they are authoritative, and prefer short-lived tokens where the use case allows it.

When your environment depends on delegated access, review whether the token should carry consented scope, role-like claims, or both. Many organisations also separate user-facing identity signals from machine or application context so that the authorisation layer can distinguish interactive use from service use without guessing.

For teams designing or reviewing these flows, the key question is not “does the token contain enough data?” but “does the receiving service verify the right data for the right purpose?”. That discipline is what keeps claims useful for authorisation and auditing without turning them into a weak trust shortcut.

To see how modern OAuth guidance tightens those controls, RFC 9700: Best Current Practice for OAuth 2.0 Security is the authoritative reference for safer deployment patterns and token hardening.

For broader authorisation design, Authorisation Models Guide helps place scopes and claims inside a larger access-control model instead of treating them as the entire decision mechanism.

Risk and Threat Considerations

oauth scopes and claims become dangerous when they are too broad, misvalidated, or accepted by the wrong service. Attackers often target the gap between what a token says and what a resource server actually enforces, because that gap can expose data, enable impersonation, or extend access beyond the intended boundary.

Failure mechanism: A token is issued with excessive scope, stale claims, or weak audience checks, then replayed or accepted in a context that should have rejected it.

Impact: The result can be data exfiltration, privilege expansion, cross-tenant access, or persistent misuse of a stolen or overpowered token.

Standards & Framework Alignment

This section maps relevant standards and security frameworks to the operational risks and controls described in this guidance.

OWASP API Security Top 10 addresses the attack and risk surface, while NIST SP 800-53 Rev 5 and OWASP ASVS set the governance and control requirements practitioners need to meet.

Framework Control / Reference Relevance
NIST SP 800-53 Rev 5 IA-5 — Authenticator Management Covers token and credential lifecycle controls that support OAuth token handling.
AC-3 — Access Enforcement Defines enforcing access decisions from scopes and claims at the resource server.
AU-3 — Content of Audit Records Supports logging token subject, issuer, audience, and scope for auditability.
Recommendation — Apply IA-5 to manage token lifetimes, revocation, and rotation for OAuth credentials. Use AC-3 to enforce scope- and claim-based access decisions at the point of request. Record subject, issuer, audience, and scope details in audit logs for token use.
OWASP ASVS V8 — Authorization Directly addresses authorisation logic that should evaluate OAuth scopes and claims.
V10 — OAuth and OIDC Covers OAuth and OIDC token handling, claims, and trust decisions.
Recommendation — Verify that application authorisation checks use claims and scopes consistently for each protected action. Validate OAuth and OIDC processing so tokens, claims, and audiences are checked correctly.
OWASP API Security Top 10 API1 — Broken Object Level Authorization Scope and claim mistakes often surface as object-level authorisation failures in APIs.
API5 — Broken Function Level Authorization Scopes are commonly used to gate API functions and need explicit enforcement.
Recommendation — Test object-level checks so scopes and claims do not bypass per-resource authorization. Enforce function-level checks so token scopes cannot unlock unintended API operations.

Practitioner Guidance

Governance implication: Treat scopes as a consent and capability boundary, and treat claims as verification inputs that must be validated by the receiving service. The most common design error is assuming either one is sufficient on its own.

Practitioner note: Review custom claims carefully, because they often carry the highest risk when teams start using them as policy shortcuts. If a claim changes authorisation behaviour, it deserves the same scrutiny as any other security control input.