OAuth

By Dan Moore

OAuth grants specify particular flows of formatted data between the various parties, including the authorization server, the client and the resource server. At the end of a grant, one or more tokens are delivered. These tokens are time bound credentials that give access to protected data and functionality.

Summary - Storing OAuth Tokens

Key Takeaways

• Enhanced Security Architecture: FusionAuth’s flexible token storage options enable secure, scalable authentication while maintaining complete control over your security infrastructure through self-hosting capabilities
• Single-Tenant Advantage: Unlike shared-tenant solutions, FusionAuth’s single-tenant architecture ensures your OAuth tokens and user data remain completely isolated, reducing security risks and compliance concerns
• Deployment Flexibility: FusionAuth supports multiple token storage strategies including secure cookies, server-side sessions, and native secure storage, adapting to your specific infrastructure requirements
• Transparent Implementation: FusionAuth’s clear token validation processes and standards compliance eliminate vendor lock-in while providing enterprise-grade security features at predictable pricing
• Performance Optimization: FusionAuth’s efficient token validation and introspection capabilities minimize authentication latency while supporting horizontal scaling for high-volume applications

---

Definitions

• Access Token: A time-bound credential that grants access to protected APIs and resources. FusionAuth issues signed JWT access tokens that can be validated locally by APIs without requiring additional server calls, improving performance and reducing dependencies.
• Refresh Token: A long-lived credential used to obtain new access tokens without requiring user re-authentication. FusionAuth’s refresh token implementation includes configurable expiration policies and automatic rotation for enhanced security.
• Backend for Frontend (BFF): An architectural pattern where tokens are stored server-side in sessions rather than client-side. FusionAuth supports BFF implementations through its comprehensive session management and API proxy capabilities.
• Token Introspection: The process of validating an access token by querying the authorization server. FusionAuth provides OAuth 2.0 compliant introspection endpoints that return detailed token information including custom claims and user context.
• HttpOnly Secure Cookies: Browser cookies configured to be inaccessible to JavaScript and transmitted only over HTTPS connections. FusionAuth automatically configures these security settings when delivering tokens to web applications, preventing XSS-based token theft.

---

Frequently Asked Questions

Q: How does FusionAuth handle passwordless login and token storage for modern authentication flows?

A: FusionAuth supports multiple passwordless authentication methods including magic links, WebAuthn, and social login, with flexible token storage options. Whether using secure cookies for web applications or native secure storage for mobile apps, FusionAuth ensures tokens are protected while maintaining seamless user experiences across all authentication methods.

Q: Can FusionAuth be deployed using Docker or Kubernetes for scalable token management?

A: Yes, FusionAuth provides official Docker images and Kubernetes deployment guides, allowing you to scale token validation and storage horizontally. The single-tenant architecture means each deployment handles only your organization’s tokens, eliminating the security and performance concerns associated with shared-tenant solutions while providing complete infrastructure control.

Q: How does FusionAuth’s single-tenant architecture enhance security for OAuth token storage?

A: FusionAuth’s single-tenant architecture ensures complete data isolation where your tokens, user data, and cryptographic keys remain exclusively within your infrastructure. This eliminates the multi-tenancy risks present in shared SaaS solutions, provides better compliance positioning, and allows for customized security configurations that meet your specific requirements.

Q: How do I migrate users securely between authentication providers while preserving token functionality?

A: FusionAuth provides comprehensive migration tools and APIs that preserve user sessions and token validity during provider transitions. The import APIs support bulk user migration with password preservation, while the flexible token configuration allows gradual migration strategies that maintain service availability throughout the transition process.

Q: How does FusionAuth compare to Auth0 for user authentication and token management?

A: FusionAuth offers transparent pricing without per-user costs, complete deployment flexibility including self-hosting options, and single-tenant architecture for enhanced security. Unlike Auth0’s shared infrastructure, FusionAuth gives you full control over token storage, validation logic, and security configurations while providing the same OAuth 2.0 and OIDC compliance with better performance predictability.

---

These tokens include an access token, an optional refresh token (if the proper scope is requested), and an optional id token (if using OpenID Connect).

At a high level, these each serve different purposes.

• The access token allows for access to different APIs and protected resources.
• The refresh token lets you mint new access tokens.
• The id token from OpenID Connect (OIDC) is used by the client to display information about the user.

What should you do with all of these tokens? How can they be used by your application to ensure that only the correct users get access to data and functionality?

Here’s a diagram of a common grant, the Authorization Code grant, from the start until tokens are obtained.

The Authorization Code grant up to the point where tokens are requested from the token endpoint.

This article will look at the options for storing these tokens.

Why Use OAuth Grants?

But first, why use the Authorization Code grant or other grants at all? There are, after all, simpler ways to offload authentication. You could use the direct username and password flows. Why bother with the OAuth dance of redirects?

When you use the OAuth grants, you stand on the shoulders of giants. Many people in the Internet Engineering Task Force (IETF) working group have spent lots of time refining this grant, poking and fixing holes in these flows’ security, as well as documenting and building libraries for them. You also benefit from documents such as OAuth 2.0 for browser based apps, currently being developed, and OAuth 2.0 for native apps.

Using standard OAuth grants to integrate a third party authorization server into your application architecture allows you to leverage these benefits. It also leaves open migration possibilities, should your authorization server fail to meet your needs. (OIDC is another standard which layers identity information onto OAuth grants.)

When using the Authorization Code grant in particular, in addition to the wisdom of the IETF members, you get the following benefits:

• Users’ personally identifiable information is stored in one safe and secure location. You can take extra steps to defend and protect this location, or outsource it to a vendor focused on the problem.
• You gain a single view of your customer across all your apps.
• You can offer users granular control of data permissions using standardize and custom scopes.
• Advanced authentication functionality such as multi-factor authentication, enterprise single sign-on and login rate limiting are implemented in one place for all your applications.
• You can upgrade authentication functionality without modifying downstream applications.
• With proper configuration, you can offer single sign-on across all your custom, commercial and open source applications.
• Common login related workflows such as changing profile data or passwords are centralized.

If you’ve decided to use an OAuth grant, you need to store the resulting tokens. There are two main options:

• storing them on the client
• storing them in a server-side session

Storage Options

In a hurry? Here’s our recommendations on how to store tokens such as JWTs.

• Cookie: send the token down to the browser as a Secure, HttpOnly cookie. If you don’t require cross-site cookie sharing, set SameSite to Strict. Otherwise, set SameSite to Lax, which will share the cookies in certain situations. Learn more about SameSite settings.
• BFF/Server-side Session: store the token server side, in a session. This is also known as the “backend for frontend” or BFF pattern. The session is typically managed by a framework, and ideally adheres to the same cookie storage recommendations. Learn more about server-side sessions. Please consult your framework documentation around securing sessions and data in sessions.
• Native Secure Storage: when the client is a native mobile app, store the token in a secure storage area such as iOS Keychain or Android Keystore.

Here is a table of characteristics of recommended JWT storage options.

Feature	Cookie	BFF/Server-side Session	Native Secure Storage
Scalable client API requests	Yes	No	Yes
Revocation possible	Yes	Yes	Yes
Revocation straightforward	No	Yes	No
Sticky sessions or session datastore required	No	Yes	No
Token sent on HTTP API requests automatically	Yes (you may need to tweak the credentials option)	No	No
Token can be presented to APIs on other domains	No	Yes (via server-side requests)	Yes
Works in a web browser	Yes	Yes	No

The proper JWT storage choice is based on your threat modeling and how much risk a particular service can tolerate. You can also configure your JWTs to be short lived, which minimizes the amount of time a stolen JWT can be used.

If you need to lock down JWTs further, implement token sidejacking protection using cookies and a nonce. An alternative is DPoP, an open feature request for FusionAuth.

Here’s a table with all token storage options, including the strengths and weaknesses of each choice.

Option	Strengths	Weaknesses	Security Considerations	Recommended	Supported By FusionAuth
Secure, HTTPOnly cookies	Tokens sent automatically when credentials option sent, widely supported	Won’t work if clients are not on same domain as the APIs, requires a browser, APIs must look for access token in cookie header, not in other places	Reduces attack surface by preventing JavaScript from accessing tokens, XSS resistant, but requires correct cookie configuration and same-domain policies	**	Yes
Backend for frontend (BFF)/Sessions	Easy to revoke tokens, works with any client, can be combined with cookie approach to provide cross domain access if some APIs live on different domains	Additional server side component, less scalable because you are routing all API requests through the BFF, single point of failure for all API access	Minimizes token exposure by never sharing tokens with the client, but introduces a new critical infrastructure component that must be secured	**	Yes
Native secure storage	OS-provided secure storage options like iOS Keychain or Android Keystore prevent token exfiltration	Platform-specific implementation	Prevents exfiltration by malicious apps, use TLS to prevent attacker-in-the-middle attacks	**	Yes
Mutual-TLS (MTLS)	Tokens are bound to client, IETF standard	Not widely supported, requires every client to have an X.509 certificate	Offers strong token-binding security, but operational complexity and certificate management introduce significant overhead	** (when available)	No; tracking issue
Distributed Proof of Possession (DPoP)	Tokens are bound to client, IETF standard	Not widely supported, requires APIs to do extra work to verify the token, client must do extra work to send the token, still must take care to avoid exfiltration of key	Enhances token security by binding it to a client, but susceptible to implementation flaws and requires stringent key management	** (when available)	No; tracking issue
Local Storage, IndexedDB	JavaScript can access token and send requests using Authorization or other expected header, supported by some frameworks (Amplify)	Tokens vulnerable to exfiltration by any JavaScript running on the page	Highly vulnerable to XSS attacks	**	Yes, but you have to write your own backend to deliver the token
In Memory	Your code can access tokens but other code cannot	Tokens lost when the client reloads	Reduces persistence of tokens, limiting exposure	**	Yes, but you have to write your own backend to deliver the token
Web workers	Browser APIs provide a layer of isolation between the web worker and the access token	All fetch calls must pass through web worker, have to use a library or write web worker integration code, malicious code may still be able to get data via the web worker, access token is removed when page is reloaded	Provides isolation for tokens, but risks persist with malicious code targeting the web worker or intercepting network traffic	**	Yes, but you have to write your own backend to deliver the token and front end JavaScript to store

Client-side Storage

The first option is to store the access token and refresh token on the client, whether that is a browser, desktop or native application. Only the access token is presented to APIs or protected resources. The refresh token should be presented to the authorization server, but that workflow will be covered in more detail below. If the refresh token cookie is sent to a resource server, it can be safely ignored.

When using a browser, store these as HttpOnly, secure cookies with a SameSite value of Lax or Strict.

If you choose this option, the browser, whether a simple HTML page with some JavaScript or a complicated single page application (SPA), makes requests against APIs; the access token is then taken along for the ride.

This works great as long as APIs and the server setting the token cookies live on a domain with shared cookies. For example, the code which gets the tokens can live at auth.example.com and if you set the cookie domain to .example.com, APIs living at api.example.com, todo.example.com, or any other host under .example.com, will receive the token.

Storing the tokens as secure, HttpOnly cookies.

When using a native app, store these tokens in a secure location, such as the iOS Keychain or Android internal data. This protects these credentials from any other applications running on your device. Retrieve them and append them to the proper header before making API requests.

Validating the Tokens At the Resource Server

In the diagram above, there’s a Validate Access Token step. Validating the access token when it is presented to securing your application. Each API validates the token presented by the client every time, even if the token has been seen before, as is the case with api.example.com.

One validation approach that is an option if the token is signed and has internal structure is illustrated below. This is true of a JSON Web Token (JWT) based access token. JWTs are used by FusionAuth and other authorization servers for access tokens, but this is not guaranteed by the OAuth specification.

With a signed token, an API server validates the access token without communicating with any other system, by checking the signature and the claims.

Zooming in on token validation.

The APIs must validate the following:

• the signature
• the expiration time (the exp claim)
• the not valid before time (the nbf claim)
• the audience (the aud claim)
• the issuer (the iss claim)
• any other business specific claims: this is important, make sure you validate non-standard claims

This validation should be performed as soon as the request is received, possibly by an API gateway. If any of these checks fail, the requester is essentially unknown. Therefore, the request is from, at best, buggy software and, at worst, an attacker.

The signature and standard claims checks can and should be done with a language specific open source library, such as fusionauth-jwt (Java), node-jsonwebtoken (JavaScript), or golang-jwt (golang).

Checking other claims is business logic and can be handled by the API developer. Again, it’s important that you take this extra step.

Token Validation With Introspection

If the access token doesn’t meet the criteria above, you can introspect the token by presenting it to the authorization server. With this process, the validity of the token is confirmed by the token issuing software.

Storing the tokens as secure, HttpOnly cookies and using introspection to validate them.

A successful introspection request returns JSON. Claims in this response still need to be checked:

• the expiration time (the exp claim)
• the not valid before time (the nbf claim)
• the audience (the aud claim)
• the issuer (the iss claim)
• any other business specific claims

Using introspection adds a dependency on the authorization server, but removes the need for APIs to validate the token signature.

Using the Refresh Token Grant

At some point every access token expires, and the client will, when presenting it to an API, be denied access. The client must be ready to handle this type of error.

When you initially request the offline_access scope, you will receive a refresh token as well as an access token after a user authenticates.

Using a refresh token.

When the access token expires, the client can present the refresh token to the authorization server. That server validates the user’s account is still active, that there is still an active session, and any other required logic. The authorization server can then issue a new access token. This can be sent to the client and transparently extends the user’s access to the APIs.

Benefits of Client-side Tokens

If you use client stored tokens, you gain horizontal scalability, since each API can take requests directly from every client. As mentioned above, this approach is a great fit for a single page JavaScript application using data from multiple APIs on the same domain.

Using secure HttpOnly cookies protects you from cross-site scripting (XSS) attacks. XSS is a common way for attackers to gain access to tokens. When they gain the tokens, they can make requests masquerading as the user for whom the token was granted. Secure HttpOnly cookies, however, are not available to JavaScript running on the page, and therefore can’t be accessed by malicious scripts.

If your APIs are on multiple domains, or on domains different than what can set a token cookie, you have two options:

• You can use a proxy which can ingest the token, validate it and pass on requests to other domains.
• You can use a session based approach, discussed later.

Below is a diagram of the proxy approach, where an API from todos.com is called via a proxy at proxy.example.com. Cookies set from the .example.com domain will never be sent to the todos.com domain due to browser rules.

Using a proxy to access APIs on different domains.

Alternatives To Browser Client-side Tokens

Why use browser cookies as opposed to another storage mechanism such as memory or localstorage? Why not bind the cookie to the browser? All options have tradeoffs, and using cookies works for many applications.

Localstorage is an insecure option because, unless you also set a fingerprint cookie, as recommended by OWASP, you are exposed to XSS attacks. Any JavaScript running on the page has access to localstorage. If you do follow the OWASP recommendations by adding a fingerprint to your token and sending a cookie down with a related value, you are limited to API requests on the domain to which the cookie is scoped, which doesn’t win you much.

If you use an in-memory storage solution, when the browser is refreshed, the token is gone. The user has to log in again; not a great experience.

Another option is a service worker to isolate access to the tokens. This is a good choice, but then all requests from the application must then pass through the service worker. You’re essentially building an in-browser proxy, which may be over-complicated.

Client binding measures, such as Distributed Proof of Possession (DPoP) and Mutual-TLS (MTLS), remove the danger of XSS. A token can’t be used without the private key only the proper client possesses. However, these approaches require additional setup on the client side. DPoP is relatively new and requires the API server to take additional verification steps.

If client storage options don’t meet your needs, another option is web sessions.

Server-side Token Storage

You can store the access token and refresh token in the server-side session. The application can use web sessions to communicate with the server. The token is then available for any requests originating from server-side code. This is also known as the backend for frontend (BFF) proxy.

Storing the tokens server-side in a session.

If you need to retrieve data from other APIs with no domain limits, over secure, server-side channels, this is a good option. If you don’t really care about what the token gets you access to, you can examine the claims and validity, then discard it, assured the user has authenticated at the authorization server.

Below is an example of proxying API requests through server-side components. The APIs receiving the tokens still need to validate them.

Proxying API calls using tokens stored in a server-side session.

Even if you don’t use token to gain access to APIs from server-side code, you still get benefits from using the OAuth Authorization Code grant:

• Customer personally identifiable information (PII) is stored in one safe and secure location.
• You have one view of your customer across all your apps.
• Granular user permissions with scopes, some of which are standardized.
• Advanced authentication functionality such as MFA, enterprise single sign-on and login rate limiting can be implemented in one place for all applications.
• You can upgrade such authentication functionality without modifying downstream applications.
• You can offer single sign-on across all your custom, commercial and open source applications.
• Common login related workflows such as changing profile data or passwords can be centralized and managed by the authorization server.

The Id Token

What about the id token? That was mentioned above as an optional token, but not discussed further.

The token is delivered when you request a scope of profile in the initial authorization sequence. After successful authentication, there is an id token as well as an access token provided by the authorization server. There are other OIDC scopes as well, beyond profile, which can get you access to different user data.

The id token can be safely sent to the browser or client and stored in a relatively insecure location, such as localstorage. The id token should never be used to access protected data, but instead is for displaying information about a user such as their name. Id tokens are guaranteed to be JWTs, so you can validate them client side.

Summing Up

The two options of client-side cookie based token storage or server-side session based token storage handle many systems using OAuth and OIDC to safely authenticate and authorize users.

Client-side storage is a great choice when you have disparate APIs and need to scalably support highly distributed clients such as mobile devices or browsers. Server-side session storage is simpler and easier to integrate into monolithic applications.