DEV Community: Curity

Scope Best Practices in OAuth 2.0

Nadja — Thu, 04 Sep 2025 11:53:57 +0000

The biggest problem in API security is over-privileged access. Many of the risks mentioned in the OWASP API Security Top 10 stem from this issue. To solve these problems, developers and architects need an API security design that enables APIs and clients to run with the least privilege.

Scalable least-privilege access is the problem that OAuth 2.0 solves. You use scopes to set security boundaries and to reduce API privileges granted to clients. Often, however, developers do not understand scope best practices. Therefore, this article provides some practical guidance for using scopes effectively.

What Are OAuth 2.0 Scopes?

Scopes are strings attached to access tokens that define what the token can do. APIs then use these scopes to enforce access rules.

A simple example might look like this:

Resource Type - order
Access Level - read
Scope Value - order_read

The OAuth 2.0 spec doesn’t tell you how to design scopes; it leaves that to you. So let’s talk about how to do it well.

Example Scenario

Imagine you’re building a system that sells products online. You’ve got multiple APIs (orders, shipping, inventory) and multiple types of clients (customer app, admin portal, supplier dashboard).

Each client needs access to different parts of your APIs. That’s where scopes come in.

Scopes in Clients & User Consent

Clients are configured with scopes that limit their API privileges.
After login, the authorization server issues an access token with those scopes so that the user can control the access granted to the client.
If it’s a third-party client, show a consent screen so the user can pick what to allow.

For first-party clients (where you own both the API and the client), you can skip the consent screen to avoid user confusion.

Designing Scopes

Good scope design keeps your system flexible and secure.

1. Use Hierarchical Scopes

You can model subresources with colon-separated scopes:

2. Keep Scopes Stable

Start simple. Use broad scopes for major business areas (e.g., marketing, finance) and add detail only when you really need it.

3. Give Clients Least Privilege Scopes

Only grant scopes to clients that they need so that they cannot access APIs outside of their area. Use readonly scopes where possible. Also consider threats based on the type of client or its environment. For example, use more restrictive scopes if you expose API endpoints to AI agents.

4. Avoid Scope Explosion

Avoid frequently upgrading clients to use new scopes.

Avoid the need for access token versioning in your APIs.
Avoid deploying frequent scope configuration updates to your authorization server.

Consider an incorrectly designed scope of 'orders:admin:usa' that could lead to scope explosion. To avoid that, use a single scope of 'orders' and two claims for 'role=admin' and 'country=USA'.

Include Scopes in your API Authorization Strategy

OAuth-secured APIs apply security in 3 main steps:

Validate JWT access tokens
Enforce required scopes
Implement claims-based authorization

To implement the first step, follow JWT best practices. Then, enforce required scopes for each API request. If an API ever receives a valid access token but without the required scopes, the API should return an HTTP 403 forbidden response. The code to do so is straightforward and is sufficient to set API security boundaries and enforce least privilege access.

Scopes Contain Claims

Scopes do not provide a full authorization solution. Scopes are fixed at design time and do not vary per user. Scopes set security boundaries as part of a least privilege strategy. To complete API authorization, use claims.

Whenever you issue a scope to access tokens, you can issue one or more claims. Claims are evaluated at runtime and can have different values per user. To read more about claims and how they relate to scopes, see the claims best practices.

Advanced Scope Techniques

Although you need claims to complete authorization, scopes are versatile and also have some advanced use cases. For example, you can use the following techniques:

High-Privilege Scopes Request extra scopes only when needed (e.g., order:payment during checkout).
Prefix Scopes Design scopes with a dynamic suffix like transaction-12345.
Scope Expiry (TTL) Configure short-lived high-privilege scopes (e.g., 15 minutes).
Token Exchange Downscope tokens when passing between APIs. Example: Orders API → Shipping API.

Always design scopes in terms of end-to-end flows between the client and the set of API calls the client initiates. The Token Sharing article explains some ways to scale the use of scopes.

Best Practices Recap

Use the following best practices to use scopes effectively:

Design scopes to set API security boundaries
APIs must always enforce scopes for every request
Keep scopes stable and business-focused
Keep scopes manageable and avoid scope explosion
Understand how to scale the use of scopes

Have a look at the scope best practices for a more detailed description of the aforementioned points.

Conclusion

Scopes are a simple concept that requires only trivial code to apply. However, they provide a highly effective way for users to run applications with the least privilege access to APIs.

The heart of using OAuth correctly is to design access tokens with scopes and claims. Use scopes for coarse-grained access, and pair them with claims for fine-grained control.

With a smart scope design, you’ll have APIs that are secure, scalable, and easier to maintain.

How to Use Claims for Fine-Grained Access Control in APIs

Nadja — Tue, 29 Jul 2025 15:15:25 +0000

As applications and user bases grow more complex, so must the access policies governing them. One powerful mechanism for implementing fine-grained access control is the use of claims. In this article, we take a look at what claims are and how to implement them to secure your APIs effectively.

What are Claims?

Claims are part of tokens that provide information about an entity or granted access. In particular, in OpenID Connect, an ID token can contain claims with information about the user, such as their first and last names, their role, or the region they are based in. Claims are asserted by the asserting party, which states that the subject has some attribute. The asserting party is usually an identity provider (IdP). Essentially, claims are assertions that allow applications and APIs to trust attributes about a user.

Why Use Claims for Fine-Grained Access Control?

A common approach for providing access control is to base it on a user’s role. While roles offer a simple way to group users and assign permissions, they are often too static and coarse-grained for today’s complex applications. Claims, on the other hand, are dynamic key-value pairs issued by an identity provider that describe various attributes of a user, such as department, region, clearance level, or authentication context. Unlike roles, claims provide rich, contextual information that allows access decisions to be based not just on who the user is, but on how, where, and under what conditions they are accessing a resource.

Elevating access control from basic role checks to claims-based authorization is essential for implementing fine-grained, context-aware policies that align with a zero-trust architecture. Some scenarios where using claims is essential include:

Multi-tenant architectures, where each tenant needs isolated access to its own resources.
Distributed teams, where access must vary across departments or regions.
Attribute-based access control (ABAC) needs, where access is determined by multiple attributes beyond just roles.

Claims allow services to evaluate access dynamically based on the context provided at runtime. For example, an API can use the department claim to ensure only users from "marketing" can access specific endpoints or the tenant_id claim to verify ownership of a resource. This makes authorization more flexible, scalable, and secure, especially in zero-trust environments where contextual awareness is crucial.

How to Implement Claims

Before implementing claims, determine what attributes are relevant for access decisions. An attribute is minimally defined as a name/value pair, specifying some attribute and the value for that attribute. These attributes contain the information needed to form a claim. Consider what resources need to be protected, who can access what, and under what conditions. In addition, you should think about the contextual factors that influence access, such as the user’s role, department, or geographic location. From this, derive a schema for the claims you need, such as tenant_id, access_level, resource_owner, etc.

Next, you should use your identity provider to issue these claims. This includes collecting user attributes during authentication and mapping them to claims. For example, in the Curity Identity Server, this may involve defining attribute sources (authentication, account, external APIs), creating claims rules, and associating claims with scopes in the Claims Mapper.

Once the client requests authentication with specific scopes, the IdP issues a token containing claims that correspond to these scopes. Apart from any user-related attributes, this can also mean the contextual data that APIs will later rely on.

On the API side, tokens are validated by verifying their signature and checking standard claims like exp (expiration time), iss (issuer), and aud (audience). Then, custom claims are used in business-level access control logic. For example, you might check that a department claim matches the expected value before allowing access.

Claims-based policies can be enforced inline in code or externally using policy engines like OPA (Open Policy Agent), depending on the complexity and scalability needs of your system.

Finally, claims usage should be monitored and audited. Log access decisions and token contents for visibility, and continuously evaluate whether your claims model still fits your application’s security posture. Claims-based access control is an evolving process, not a one-time configuration.

Ensure that access decisions are logged with claim context for auditability. Monitor tokens and access patterns to:

Detect abuse or misconfiguration
Tune claim granularity and scope boundaries
Improve policy accuracy

Claims implementation is not a one-off task. It’s an iterative design that evolves with application complexity and security posture.

Conclusion

Claims provide a flexible, context-rich foundation for fine-grained access control in APIs. When implemented thoughtfully, they enable attribute-based policies that scale across teams, tenants, and geographies. By shifting authorization logic to leverage claims, API developers can secure services with higher precision, without locking into rigid roles or complex ACLs.

Ready to upgrade your API authorization? Start by identifying the claims that matter most in your domain, and enforce them smartly where it counts.

Token Handling 101: Keep Single Page Apps Secure

Nadja — Tue, 08 Jul 2025 15:26:56 +0000

Single page applications (SPAs) have changed how web apps are delivered by separating the user interface from backend services. They offer fast, seamless user experiences by dynamically updating content without full-page reloads and enable a clear separation between frontend and backend, improving scalability and development speed. SPAs also support rich interactivity, efficient state management, and easy deployment via CDNs. But this architecture also introduces new security challenges, especially around token handling in the browser.

The Problem with Browser-Based Tokens

Traditional web applications used server-side sessions with HTTP-only cookies, which provided a strong defense against common attacks like Cross-Site Scripting (XSS). In contrast, SPAs store tokens in JavaScript-accessible storage, leaving them exposed to XSS attacks, which could allow malicious scripts to steal tokens and impersonate users, even after the session has ended.

When tokens are stored in the browser, they create a security vulnerability, as attackers can exfiltrate them to maintain access long after a user leaves the app. Moreover, the ongoing deprecation of third-party cookies is disrupting some token flows that SPAs have traditionally relied on, like a silent refresh.

Rethinking Token Security in SPAs

Given the lack of secure storage in browsers, the best way to protect tokens is to avoid placing them in the browser at all. This is where the Token Handler Pattern comes into play. Inspired by the current best security practice — the Backend for Frontend (BFF) approach, this architecture delegates token management to a secure backend service.

In this pattern, the SPA communicates with an OAuth Agent, which is a backend component that performs authorization flows and manages tokens securely. The agent exchanges credentials with the authorization server and issues session cookies to the SPA. These cookies, being HTTP-only and bound to the SPA’s domain, give better protection against XSS.

A key advantage of this setup is that the SPA still behaves like a modern, front-end-driven application. It doesn’t need to proxy every business request through a traditional backend or give up its CDN-based deployment model. Instead, it simply delegates authentication to the OAuth Agent, which can be deployed separately and scaled independently.

Implementation Approaches: Stateful vs. Stateless

Token handler components can be implemented in stateful or stateless modes. A stateful version stores tokens in a secure backend database, issuing cookies with session identifiers that reference stored tokens. This design is straightforward and supports session tracking but might synchronize if the backend components are deployed to multiple locations.

Stateless implementations, on the other hand, store tokens directly in the session cookies. These cookies are unreadable by JavaScript and their values could even be encrypted to remain secure when intercepted. This approach eliminates the need for backend storage but results in larger cookie sizes, particularly when using JWTs. Developers can influence cookie sizes by using opaque tokens with the phantom token approach or by ensuring smaller JWT signatures with cryptographic algorithms like ES256 or EdDSA.

Deployment Flexibility

The token handler pattern is lightweight by design and can be deployed as a backend service, serverless function, or even directly on CDNs that support edge computing. Regardless of deployment strategy, the key requirement is that the token handler must operate on the same or a sibling domain as the SPA to ensure cookies are treated as first-party.

Improving User Experience and Reducing Complexity

One of the main benefits of the token handler approach is that it enhances security without compromising user experience. SPAs retain control over navigation, redirects, and state restoration. They can initiate OAuth flows when needed, and the backend can handle complex security requirements such as Pushed Authorization Requests or JWT-based client authentication transparently. This separation of concerns improves developer productivity by reducing cognitive load, improving security, and allowing frontend teams to focus on building features while backend teams can manage authentication logic centrally and consistently.

Scaling Security Across SPAs

For organizations managing multiple single-page applications, it’s critical to design deployments that minimize the potential for security breaches. Assigning separate domains or subdomains per product area (e.g., product1.example, product2.example) helps isolate session cookies. Each SPA can have its own OAuth scopes and security configuration, limiting the impact of vulnerabilities.

In cases where multiple micro-frontends share a domain, the same token handler can support all apps by sharing session cookies. Developers can also mix static, unauthenticated pages with secured SPAs in a single domain by carefully segmenting the app paths and authentication scope.

Ready-Made Solution from Curity

SPAs need a secure mechanism to interact with APIs, one that doesn’t compromise user data through browser vulnerabilities. The Token Handler Pattern is the recommended modern approach: it reintroduces secure, cookie-based sessions in a way that complements OAuth standards and SPA architectures. Curity provides a robust, tested open source solution that is production-ready and fully aligned with OAuth and OpenID Connect standards. For those interested in learning more, Curity offers example projects, comprehensive documentation, and a white paper that outlines SPA security strategies in depth.

How Adaptive Authentication Keeps Users Happy Without Compromising Security

Nadja — Wed, 12 Mar 2025 15:20:40 +0000

Authentication is important to make sure users have the right access to systems and data. This protects sensitive information from unauthorized access and breaches.

However, a big challenge of modern authentication is balancing strong security with an easy login experience. Users should be able to log into applications or services without friction, but security can’t be an afterthought.

To address this challenge, you need the right architectural setup that centralizes authentication and provides more options—one solution is adaptive authentication.

The Need for Adaptive Authentication

Cyberattacks are constantly evolving, becoming more sophisticated and harder to detect. Attackers can leverage advanced techniques to bypass traditional security measures.

Some key trends driving the need for stronger authentication include the rise of credential-based attacks, advanced malware and ransomware, AI-powered threats, API and session hijacking, phishing attacks, and MFA bypass techniques.

At the same time, users also demand a seamless authentication experience. Lengthy login processes, frequent password resets, and excessive MFA prompts frustrate users and create fatigue. In a survey carried out by Storyblok in 2023, it was found that 60% of consumers abandon purchases due to poor website user experience.

What is Adaptive Authentication?

Traditional authentication relies on static, predefined authentication steps, typically requiring a username and password. Conventional authentication methods often include:

single-factor authentication, which refers to a user using a password to log in
multi-factor authentication, where the user has to provide two or more factors
two-factor authentication, a subset of MFA using two factors

However, these methods are insufficient because they don't consider important contexts that could impact the auth flow, like location, time of day, or device used.

Adaptive authentication takes traditional authentication further, dynamically adjusting security measures based on user behavior, risk signals, and contextual data.

By leveraging OAuth 2.0 and centralized authentication, organizations can implement adaptive authentication efficiently while maintaining a seamless user experience.

Example: Location-Based Adaptive Authentication

Let's see how a financial organization could implement adaptive authentication to harden logins and protect against threats — without negatively impacting the user's everyday experience.

Normal Login: The customer authenticates with their normal main factor, such as a password. The system recognizes the device, location, and typical behavior. Since no risk signals are detected, the system authenticates the customer with just a password (or Single Sign-On if enabled via OAuth 2.0).

Suspicious Login Attempt: The same customer attempts to log in from an unfamiliar device in a different city. The system detects this unusual activity and prompts for an additional authentication factor, such as an SMS OTP or push notification approval.

High-Risk Scenario: Someone tries to log in using the customer’s credentials from a location associated with recent cyber attacks. The system flags this as high risk and denies access outright or requires biometric authentication before proceeding.

Implementing Adaptive Authentication

OAuth 2.0, combined with OpenID Connect (OIDC), enables centralized authentication where applications delegate user authentication to an authorization server.

There are a handful of benefits to centralizing authentication with OAuth and OpenID Connect:

You can choose from many advanced authentication methods the authorization server provides and apply consistent security policies across all applications.
You can allow users to choose their preferred authentication factors.
Users authenticate once via the identity provider and gain secure access to multiple services.
OAuth tokens manage user session continuity without exposing credentials
Finally, you should be able to implement adaptive user authentication at any time without redeploying applications.

When you use OAuth, your APIs can play an important role in blending security with user experience. For example, APIs can allow frictionless access to non-sensitive data but require access tokens with high privilege scopes for more valuable data. When such a scope is missing, an API can trigger step-up authentication.

In addition, stronger authentication may be required (e.g., MFA) based on context (e.g., logging in from an untrusted device), and login patterns are monitored, prompting additional verification if unusual behavior is detected. A risk level is applied to authentication requests, and security measures are adjusted accordingly.

Adaptive Authentication in OAuth Workflows

When adaptive authentication is implemented in OAuth workflows, the following scenario happens:

The application triggers user authentication on behalf of the user, and the authorization server enforces user authentication
The authorization server can also check factors such as location, device, and previous user behavior
The identity server issues tokens with minimal friction if the risk is low. If the risk is medium, the user is prompted for additional verification, and if the risk is high, the identity server either denies access or enforces stricter authentication.
When the user is authenticated, an access token is granted, and session behavior is analyzed for anomalies, triggering re-authentication if required.

By centralizing authentication with a customer identity and access management solution, you can provide context-aware access and support passwordless authentication and passkeys.

You can also leverage standards-based solutions like OAuth, OpenID Connect, and FIDO2, and use centralized logging and monitoring to track authentication patterns and ensure compliance with regulations like GDPR and PSD2 that require adaptive security measures.

The Goal: Reduce Authentication Friction

As cyber threats evolve, adaptive authentication remains a critical defense mechanism, enhancing security while maintaining usability by carrying out the right checks and the right situation. By combining OAuth, centralized authentication, and adaptive authentication, you can balance security and user experience, ensuring secure access while reducing authentication friction.

Scopes and Claims Explained

Maria Pelagia — Thu, 02 May 2024 08:45:43 +0000

In OAuth and OpenID Connect, scopes and claims appear quite often. However, many times their explanation is overlooked. This brief article will explain what scopes and claims are and how you can use them.

Claims Explained

Claims are statements of facts that are only believable if the asserting party is trusted. In OAuth and OpenID Connect, the asserting party is the authorization server. A claim can be asserted about a subject or an entity—often the user—that is claimed to be true by an asserting party. The subject is the resource owner; the API or the client is the relying party.

Scopes Explained

Scopes are a set of claims. They are a shorthand way of requesting a level of access from the authorization server. Clients request one or more scopes to be issued to access tokens so that they get the API permissions they need.

Standard Claims and Scopes

In OpenID Connect, a profile scope consists of a group of claim names that include claim values. The claim names usually contain these variables: name, family_name, given_name, middle_name, profile, picture, website, gender,etc. When a user logs in, the values for those claims - if the authorization server can assert them - will be asserted as claim values. Instead of having to ask for a dozen different claims, you can simply request one scope that will contain this information.

Examples of standard OpenID groupings include: profile, openid, offline_access, email, address, phone. When a user logs in and is being authenticated, and their data is released in claims format, this information can be passed into an ID token user info or to an access token. Consequently, these claim values would end up manifesting themselves.

How are Claims and Scopes Useful?

Business Value

Scopes and claims provide the heart of a scalable security architecture for your APIs and clients. Scopes enable you to set security boundaries to define which clients can access which API endpoints. You can create custom scopes that are defined in terms of areas of your business.

Your APIs use claims to implement their business authorization. You can define custom claims to implement any finer-grained identity values your APIs need. Both scopes and claims are issued to access tokens returned to clients so that each client calls APIs with the correct level of business access.

User Consent

The consent user experience should be based on scopes not claims. The user sees a plain English message of a scope's meaning rather than technical information about many fine-grained permissions.

Summary & Conclusion

Claims are assertions made by one party about another. The authorization server is the asserting party, the user is the subject, the API and the client are the relying parties. Scopes are a group of claims and with claims less data is released. Lastly, claims provide a finer-grained authorization model.

Further Reading:

Scopes vs Claims
Introduction to Claims
Introduction to Scopes
Using Claims in APIs
Scopes, Claims and the Client
Consent and Claims

Best Practices for Handling JWTs

Maria Pelagia — Wed, 11 Jan 2023 12:34:43 +0000

Even though JSON Web Tokens (JWT) are widely used in the OAuth and OpenID protocols, maintaining a high level of security while using them is not always easy. This article will focus on some best practices for handling JWTs so that you can maintain a high level of security in your applications.

What is a JWT?

JWTs are not protocols, they are message formats.
They are used to pass messages between two parties, e.g., a client and a server, or between services.
A JSON Web Token has a form of a string divided into parts which are base64 encoded and separated by dots.
A JWT can either be a JWS (a signed token) or a JWE (an encrypted token). These types of tokens define the parts that the JSON Web Token will consist of.
Most often JWTs are used as Access Tokens or ID Tokens (but they can also be used in other scenarios as well).

JWT Best Practices

Protect Valuable API Data in Access Tokens

When JWTs are issued to your clients to be used as Access Tokens, client developers are able to access the data in the token. In such cases developers can start using the data from JWTs in their applications which can cause issues if you decide to change the structure of the data in the JWT. As the token can easily be accessed or read, personal information about users can also be easily leaked and valuable API data can become prone to cyber attacks. Either avoid adding sensitive data to access tokens or utilise a pattern like the Phantom Token, where the data is concealed by an opaque token.

JWTs and Algorithms

Encrypted and signed tokens always contain an alg claim in the header to show which algorithm has been used. When verifying and decrypting tokens it is considered a best practice to check the value of this claim against a list of algorithms that your system accepts and which are verified to be secure. If the alg claim contains a none value, make sure that you know both the identity of the issuer of the token and of the client that uses the token before proceeding.

Always Validate an Incoming JWT

Another best practice is to always validate an incoming token. This should be done even when a service is only accessible on an internal network, to prevent situations where someone manages to make requests from inside the network. Many times when services are moved to a public domain the security measures are overlooked, thus it’s important to have them properly protected from the beginning.

Verify the Issuer

Always check the issuer of the JWT to make sure that you can trust them by checking the iss claim. This is especially important when downloading the keys needed to validate / decrypt the tokens. Make sure to confirm that any cryptographic keys used to sign or encrypt the token belong to the issuer. The verification of the issuer depends on the implementation of the JWT. For example, when using OpenID Connect the issuer should be an HTTPS URL. This makes it easier to confirm the ownership.

Conclusion

In this article we have explored a few best practices when using JWTs. It's important to remember that JWT safety depends greatly on how the tokens are implemented and used. At Curity, we have written a complete guide on how to keep your JWTs secure, following best practices. Make sure to also check any changes in the RFCs which talk about the good practices for JWTs: in RFC 8725 JSON Web Token Best Current Practices and in RFC 7518 JSON Web Algorithms (JWA).