DEV Community: Nadja

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.

SPAs deliver seamless UX - but storing tokens in the browser opens the door to attacks. With third-party cookies on the way out, it's time for a safer approach. Enter the Token Handler Pattern: secure, modern, and built for today’s frontend-driven apps.

Nadja — Tue, 08 Jul 2025 15:27:47 +0000

Token Handling 101: Keep Single Page Apps Secure

Nadja for Curity ・ Jul 8

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.

[Boost]

Nadja — Tue, 08 Jul 2025 15:24:39 +0000

Nadja

May 8 '25

Implementing OAuth for Secure and Scalable API Access Control

#oauth #tokens #accesscontrol #security

Comments

5 min read

Implementing OAuth for Secure and Scalable API Access Control

Nadja — Thu, 08 May 2025 07:24:09 +0000

Introduction

Access control refers to the cybersecurity practice of determining whether a user, API, application, or device (requesting party) should have access to a resource, system, or service or perform an action. This process is called authentication (verifying the identity of the requesting party) and authorization (determining their access rights).

OAuth 2.0 has become the go-to protocol for authorization and access delegation, which facilitates fast and secure authentication and authorization for users to APIs, servers, devices, and apps. This is done without sharing any user credentials, like passwords. Instead, access tokens are used to prove an identity, keeping user credentials safe. By using a centralized OAuth server to issue tokens, you can achieve fine-grained access control at the API level for robust API security. This article will go through the basics of OAuth and how to implement it to secure API access.

OAuth Flow Overview

There are four different parties in the OAuth 2.0 specification published in the RFC 6749 document:

Resource owner: refers to the entity that grants access to the protected resource, which is often an end-user.
Client: refers to the system or application that requests access on behalf of the resource owner (typically an app requesting access).
Authorization server: the entity that authenticates the resource owner and issues OAuth tokens to the client.
Resource server: refers to the entity hosting the protected resource, which is often a backend API. It protects its data via access tokens, which are issued by the authorization server on behalf of the client.

Once you understand the key roles in OAuth, the next step is choosing the right flow based on how your application interacts with users and systems.

Choosing the Right OAuth Flow

To choose the right OAuth flow, you need to consider the characteristics of the application and the use case. Authorization flows in OAuth 2.0 fall into two categories: user-centric flows that involve end-user authentication and machine-to-machine flows where no user is involved. In this case, the client credential flow should be used to get an access token that represents the client, as no user authentication is involved in the process.

When users have to be authenticated by the authorization server, the client must choose the correct user interface. There are two approaches to trigger user interactions:

Same-device authentication: If the device that runs the client application can also open a browser, and the user can conveniently operate the device (like enter their password), then you should use the code flow. It allows both mobile and web clients to obtain tokens securely and gain access to APIs. The code flow uses a redirect approach, where the user is redirected in the browser to the authorization server for authentication. For security reasons, the authorization server never returns tokens directly to the client but sends a temporary grant — an authorization code. The client must subsequently exchange the code for a set of tokens: an access token and, optionally, an ID token and a refresh token.

Cross-Device Authentication: In some cases, such as with smart TVs, IoT devices, or remote consoles, users can't authenticate directly on the device they're interacting with due to limited input or browser support. If the user can still interact with the client and the client can present a code and link (or a QR code) for the user to authenticate on a separate device, then the device flow is a suitable option for this decoupled authentication scenario.

If the user needs to be authenticated remotely and the client cannot communicate the authentication information to the user, you should use the client-initiated backchannel authentication (CIBA) flow. It allows the client to remotely initiate an authorization flow that the user can complete on their own device. As the client needs to initiate the flow for a concrete user, CIBA requires that the user is already registered with the authorization server through an out-of-band process, and the client must know the user’s identifier beforehand.

In general, the most recommended flow for the majority of cases is the OAuth code flow in combination with Proof Key for Code Exchange (PKCE). It enhances the security of the authorization code flow, ensuring that the application initiating the authorization flow is the same one that finishes it.

Handling Tokens

Once an OAuth flow completes, the client gets a set of tokens to use. One of them is the access token that allows the client to call APIs and access the user’s data. As the access token is a powerful credential, it should always be kept safe. While it’s simpler for backend services and mobile apps to keep such a token secure, browser-based applications have a much more difficult task. JavaScript applications are susceptible to cross-site scripting (XSS) attacks, which can steal the token. The best practice is to keep the token out of the browser altogether and utilize secure cookies instead, through solutions like the token handler pattern.

Implementing OAuth Step-by-Step

Once you’ve picked the right flow, here’s how to actually implement OAuth. The steps below cover the main building blocks for implementing OAuth, but they are not exhaustive. Depending on your security requirements and particular use case, you’ll likely need to explore the topic deeper, but hopefully this will be enough to get you started.

1. Set Up an Authorization Server

The first step is to set up an authorization server, such as the Curity Identity Server, Okta, or Auth0. This acts as the central component responsible for issuing and managing tokens, handling user authentication, and enforcing security policies. The authorization server must be configured according to your specific requirements and use cases.

*2. Register Your Client Application
*
Now it’s time to register your app with the authorization server. This usually involves generating a client ID and secret, setting up redirect URIs, and choosing which grant types and scopes your app will use. It's also here that scopes play a crucial role — they define the level of access your client is requesting, and when combined with a consent screen, they ensure users are informed and in control of what permissions they’re granting.

3. Obtain and Use Access Tokens

With your client registered, your app can begin requesting access tokens. The flow you use depends on the nature of your application. Once access tokens are obtained, they allow the client to make authenticated requests to resource servers. To maintain security, follow token expiration and refresh best practices: use short-lived access tokens and secure, time-limited refresh tokens to minimize the impact of a compromised token.

4. Validate and Introspect Tokens

Before trusting any access token, you must validate it. This can involve checking the token’s signature and claims (in the case of JWTs) or performing token introspection against the authorization server. Validation ensures the token is still active, correctly scoped, and has not been tampered with or revoked.

*5. Secure the Token *

Once you have an end-to-end flow up and running, you can further enhance the security of your solution. All token-related communication should happen over HTTPS to prevent interception. Store tokens and credentials securely and apply logging and monitoring to detect unusual activity. You can further strengthen security by implementing token binding and client attestation. These techniques ensure that only the authorized client can use access tokens, preventing token theft and replay attacks by binding the token to the client's identity or device.

Conclusion

OAuth 2.0 provides a flexible and secure framework for managing API access control in modern applications. Selecting the right flow for your specific use case is crucial for maintaining usability and security. Ultimately, OAuth isn’t just about obtaining access tokens — it's about building trust between users, clients, and APIs. A well-designed OAuth implementation puts security first while also delivering a smooth and secure user experience that scales with your system's needs.

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.