BROUGHT TO YOU IN PARTNERSHIP WITH
CONTENTS
OAuth Patterns
∙ What is OAuth?
∙ OAuth Terminology
∙ Common OAuth Patterns and Anti-Patterns
and Anti-Patterns
‑ Keep Client Credentials Secure
‑ Use PKCE Instead of Implicit Flow
‑ Keep Tokens Secure in the Browser
‑ Access Tokens vs. ID Tokens
‑ Remote vs. Local Token Validation
∙ References and Resources
AARON PARECKI
SENIOR SECURITY ARCHITECT, OKTA
OAuth is used all around the world in countless systems to provide CLIENT
secure access to APIs and other data. However, getting it right isn’t The term "client" is how OAuth refers to applications.
always easy. As software development continues to evolve, so do Specifically, it refers to the piece of software that
the number of attackers trying to take advantage of flaws within obtains the access token and makes API requests to
these systems. the resource server. The authorization server’s job is
to make sure it only gives access tokens to legitimate clients.
WHAT IS OAUTH?
AUTHORIZATION SERVER
OAuth is the industry-standard framework for securing access to
The "authorization server" is what protects access
APIs and other resources. In addition to being used for first-party and
to the APIs and is responsible for authenticating
third-party delegation, it also provides the foundation upon which
users and issuing access tokens to clients. The
the OpenID Connect identity and authentication framework is built.
authorization server may have its own policies
While OAuth provides a lot of the necessary components and tools to
around which users are allowed to use certain applications,
build a secure system, it can be a challenge to understand all of the
and it can decide how long access tokens are valid based on a
parts that are involved. In particular, OAuth has evolved quite a lot
number of factors it chooses as well as its own risk assessment.
over the last 10 years, and some of the original parts of the spec have
been replaced by newer, more secure recommendations.
OAUTH TERMINOLOGY
RESOURCE OWNER
The "resource owner" is the OAuth 2.0 spec term for
what is most often the end user who uses the client
application. The user owns some resources stored
at the resource server and attempts to log in to the
application so that they can access the resources.
USER AGENT
In the case of web applications, the "user agent" is
the web browser being used to access the application.
For a mobile app, the user agent is the mobile phone
operating system. In both scenarios, the user agent is
something that the user trusts that the app does not control.
1
Painless
User Auth
Start your free trial at:
developer.okta.com/signup/
REFCARD | OAUTH PATTERNS AND ANTI-PATTERNS
RESOURCE SERVER On the other hand, "public clients" are applications that don’t have
The "resource server" is what the spec calls the API, or the ability to keep a secret secure, so they aren’t given a client secret
the server that contains the resources being requested in the first place. The most common example of public clients are
by the client application. This may contain a user’s mobile apps and single-page apps. If you included a client secret in a
data (e.g., photos, contacts), or it could contain other single-page app, anyone who uses the app would first download the
data that a user is authorized to access. Client applications will make JavaScript code, including the secret, which would then be visible to
an API request to the resource server with an access token it obtained anyone using the app. These kinds of apps can’t keep secrets secure,
from the authorization server. so instead, we use an OAuth flow that doesn’t require a secret at all.
ACCESS TOKEN USE PKCE INSTEAD OF THE IMPLICIT FLOW
An "access token" is a string that the client application
PATTERN ANTI-PATTERN
uses to make requests to the resource server. The client
obtains an access token from the authorization server, Use the Authorization Code
Using the Implicit flow to
usually after asking a user to log in. The resource server flow with PKCE for public and
get access tokens
confidential clients.
needs to know how to validate the access token in order to confirm
whether the requests from the client application are legitimate.
The Implicit flow in OAuth 2.0 was created over 10 years ago,
Access tokens may be random strings or may also be structured
when browsers worked very differently than they do today. The
tokens such as JWTs.
primary reason the Implicit flow was created was because of an old
limitation in browsers that prevented them from making cross-
COMMON OAUTH PATTERNS AND
domain requests.
ANTI-PATTERNS
The standard OAuth Authorization Code flow requires that a POST
KEEP CLIENT CREDENTIALS SECURE request is made to the OAuth server’s token endpoint. In the past,
PATTERN ANTI-PATTERN if the token endpoint was on a different domain than the app,
JavaScript would be unable to make this request due to cross-origin
Only issue client secrets to "confidential Putting client secrets
limitations. The Implicit flow worked around this limitation by
clients," and store them like you’d store in a single-page app or
any sensitive API keys. mobile app avoiding the POST request, and instead, returning the access token
immediately in the redirect, as shown in the figure below:
When you first register an app at the OAuth server,
Figure 1: OAuth Implicit flow
you’ll get a client ID to identify the app, and you
may also get a client secret used to authenticate the
app. This client secret is effectively the application’s
password, and you need to treat it as such. That
means making sure it’s kept secure, only sent to the authorization
server, and never shared with anyone.
Only certain types of applications have this ability and are known as
"confidential clients" in OAuth terms. The most common example
of a confidential client is one that runs server-side code (e.g., .NET,
Java), where the code on the server can be configured with this client
secret, and the secret won’t be visible to users of the application.
Working around the browser limitations came with the tradeoff
of this flow being inherently less secure. The problem is that the
access token is delivered to the client through the front channel
(the browser redirect), rather than the client retrieving it from the
authorization server itself via the back channel.
3 BROUGHT TO YOU IN PARTNERSHIP WITH
REFCARD | OAUTH PATTERNS AND ANTI-PATTERNS
For a more in-depth analysis of the risks, please visit: LOCALSTORAGE AND SESSIONSTORAGE
oauth.net/implicit The most common method of storing tokens in the browser is to use
the browser’s storage APIs, LocalStorage and SessionStorage.
Modern browsers no longer have these old limitations, and we can
These two APIs are similar, the difference being how long the browser
now use the more secure Authorization Code flow from the browser
will store data. LocalStorage is intended to be a more or less
itself. In order to secure this flow without a client secret, we use a
permanent storage for application data. The application can store
mechanism known as PKCE.
data there, and it will be shared across multiple browser tabs open to
Figure 2: OAuth Authorization Code flow the same page and persist even when the tab and browser are closed.
On the other hand, SessionStorage data is isolated to each
individual tab and will be cleared when the tab is closed. You should
use LocalStorage over SessionStorage if you want the user’s
session to persist for longer than they have a particular window open.
The downside of storing access tokens with these APIs is that the
APIs are not safe from cross-site scripting attacks. If your application
code can read the token data from storage, then an attacker can too
if they find a cross-site scripting vulnerability. This is true regardless
of whether the application stores the tokens in LocalStorage,
SessionStorage, or even a client-side cookie.
STORING TOKENS WITH A SERVICE WORKER
In the PKCE model, the only data going through the less secure front One way to work around the limitation of storing tokens using
channel is the temporary authorization code rather than the access LocalStorage is to tuck them inside of a service worker. The idea
token itself. The client first generates a PKCE Code Verifier when it with this technique is to create a service worker that is your OAuth
starts the request and uses it when exchanging the authorization client, so it’s responsible for getting and keeping the tokens, and
code for an access token in the second part of the flow. The access never letting your main JavaScript app access the tokens directly.
token is delivered via the back channel where it can be protected and
kept secure in transit. Service workers have their own storage that’s inaccessible from the
main JavaScript on the page, meaning that even if your application
In short, there isn’t any need for the Implicit flow anymore, and it has a cross-site scripting vulnerability, the attacker cannot read
will be removed in a future update of the OAuth specification. The the service worker’s storage since your app can’t access it either.
Authorization Code flow with PKCE provides better security and is the However, this doesn’t ensure that you’re completely protected from
best option to use in place of the Implicit flow. cross-site scripting attacks. An attacker could still call methods in the
service worker and make API requests using the access token, but the
KEEP TOKENS SECURE IN THE BROWSER access token itself could not be extracted.
PATTERN ANTI-PATTERN
KEEPING TOKENS OUT OF THE BROWSER
Use the most appropriate method for Not considering The only real way to keep tokens safe from cross-site scripting attacks
your application based on your desired the various options
is to avoid giving JavaScript apps access tokens in the first place. If
architecture and risk tolerance. available to you
the application never has the access token, then it can’t be stolen!
Single-page apps running in a browser face a particular challenge of If your single-page application is served by a dynamic server backend,
being in a relatively high-risk environment compared to server-side the idea is to use that backend for the OAuth flow and to manage
apps. There are many ways browser-based apps can be attacked tokens, sharing only a session cookie with the JavaScript application.
and taken advantage of — everything from cross-site scripting (XSS) While this pattern isn’t always an option for everyone, it is the most
attacks to users installing malicious browser extensions. So once secure. You won’t be able to use this pattern if you’re firmly set on
you have an access token in a single-page app, how do you keep it serving your single-page app from a static web host (e.g., Amazon S3)
secure? There are generally three different patterns, each with their and having the application talk to your APIs directly.
own advantages and disadvantages.
4 BROUGHT TO YOU IN PARTNERSHIP WITH
REFCARD | OAUTH PATTERNS AND ANTI-PATTERNS
But if your single-page application is backed by a .NET or Java app, access token, it will either look up the token in the shared database
then you can use that dynamic backend to secure the tokens. or call back to the authorization server over HTTPS to ask the server
whether a token is valid.
To achieve this pattern, treat your backend application as the OAuth
client. As the OAuth client, the back-end application performs In some cases, an authorization server may use the JWT format to
the Authorization Code flow and does the final exchange of the access tokens as well. This provides a standardized way for resource
authorization code for an access token. Rather than send the access servers to validate tokens without asking the authorization server.
token to the browser, the backend sets a new HttpOnly cookie While this is a useful pattern, in some systems, access tokens and ID
with a session identifier, storing the tokens in the backend associated tokens look very similar. It’s important to remember that they are not
with this session. the same and cannot be used interchangeably.
When the single-page app wants to make an API request, it proxies Note: Access tokens and ID tokens are not the same and cannot be
its request through the back-end server where the browser attaches used interchangeably.
the cookie. Then the backend can look up the actual access token to
From the client application’s point of view, access tokens do not have
make the API request.
any defined structure and are known as "opaque" tokens. Even if an
This is more secure because the HttpOnly cookie can’t be read access token is actually a JWT, the client cannot attempt to parse any
by JavaScript, making even that session identifier safe from cross- information from the token as that crosses a security boundary in
site scripting attacks. However, again, this doesn’t mean that your the spec and will very likely lead to unexpected security issues down
application is 100% safe from cross-site scripting attacks, but that an the road. From the resource server’s point of view, it will only ever be
attacker could only proxy requests through your backend rather than seeing access tokens.
acquire the access token itself.
Client applications should never send ID tokens to resource servers
So which of these three methods is the right one for you? Each as the ID token is intended to be read by the client only.
has its own advantages and drawbacks, so it will depend on your
Figure 3: Token Audiences
architecture and how complex you’re willing to make things.
ACCESS TOKENS VS. ID TOKENS
PATTERN ANTI-PATTERN
Use access tokens to make API Using ID tokens as
requests and ID tokens to learn authentication in an
information about the user. API request
Access tokens and ID tokens sometimes look similar but are used
for completely different things. Access tokens are what the client
application can use to make API requests, while ID tokens are a way
for the authorization server to communicate information about the
user to the client application.
ID tokens are defined in the OpenID Connect spec and always take If you are using an authorization server that uses JWTs for both ID
the same format, a JSON Web Token (JWT). This format defines tokens and access tokens, you can see that one of the differences is
some properties for returning user information and properties of the the aud claim — the "audience" of the token. The "audience" claim
authentication event itself, such as whether the user logged in with describes who is meant to read the token. The audience of the ID
multifactor authentication. token will be the application’s client_id, whereas the audience of
the access token will be the resource server’s identifier, as illustrated
Access tokens do not have a defined format in the OAuth spec. in Figure 3.
Authorization servers are free to define their own formats or even
use random strings as a token, storing information about the token It is critical for the overall security of the system to keep these tokens
in a database. In this case, if a resource server needs to validate an separate and use them only for their intended purposes.
5 BROUGHT TO YOU IN PARTNERSHIP WITH
REFCARD | OAUTH PATTERNS AND ANTI-PATTERNS
REMOTE VS. LOCAL TOKEN VALIDATION For example, use local validation for a first-pass validation at an API
gateway, ensuring your gateway can quickly process API requests
PATTERN ANTI-PATTERN
without adding additional latency. Then if a particular API method
Use remote token validation when you needs the additional assurance that a token hasn’t been revoked, it
Always using only one
need to guarantee correctness and local
token validation method can do the slower, more accurate remote token validation to double
token validation to optimize for speed.
check with the authorization server that the token is still valid and
hasn’t been revoked.
If you’re using an OAuth server that uses JWT access tokens, then
your resource servers have two ways to validate access tokens:
remote and local validation. REFERENCES AND RESOURCES
• RFC 6749: The OAuth 2.0 Authorization Framework. IETF, 2012.
Remote validation is the process through which the resource server oauth.net/2
makes a token introspection request back to the authorization • RFC 7662: OAuth 2.0 Token Introspection. IETF, 2015.
server. Essentially, this is an HTTPS call where the resource server • RFC 7519: JSON Web Token. IETF, 2015.
asks the authorization server whether the token is valid. The • OpenID Connect Core 1.0. OpenID Foundation, 2014. openid.net
resource server will be issued its own credentials that it can use in
ADDITIONAL PAID RESOURCES
the introspection request. The authorization server will respond
• Parecki, Aaron. OAuth 2.0 Simplified. Okta, 2020.
with a JSON document describing whether the token is valid and
oauth2simplified.com
information about the token, such as which user it was issued for
and the scopes granted to the token. • Parecki, Aaron. The Nuts and Bolts of OAuth 2.0. Udemy, 2020.
oauth2simplified.com/course
The main benefit of this approach is that it lets the authorization
server provide the most up-to-date information about the token,
including whether it has been revoked before its scheduled
expiration date. However, this comes at the cost of speed since it WRITTEN BY AARON PARECKI,
SENIOR SECURITY ARCHITECT, OKTA
requires a network request to perform this validation.
Aaron Parecki is a Senior Security Architect
Local validation is the process of the resource server checking at Okta with over two decades of experience
in the industry. He is the author of OAuth 2.0
the signature and claims of the JWT to determine whether the Simplified and maintains oauth.net. He has been invited to
token is valid, all without any network traffic. Once the resource speak at events around the world about OAuth, online security,
privacy, and data ownership. He is a regular contributor to
server has cached the public key of the authorization server, it
several specs at the IETF, including OAuth 2.1 and GNAP.
can use a JWT library to check the signature without any further
network traffic. This method can greatly speed up the token
validation process since it doesn’t require any network traffic.
However, local validation comes at the cost of accuracy because
if a token is revoked before it’s expired, the resource server
wouldn’t know that if it’s only looking at the token itself.
DZone, a Devada Media Property, is the resource software developers,
engineers, and architects turn to time and again to learn new skills, solve
REMOTE VALIDATION LOCAL VALIDATION software development problems, and share their expertise. Every day,
hundreds of thousands of developers come to DZone to read about the latest
• More accurate technologies, methodologies, and best practices. That makes DZone the ideal
PROS • Better performance place for developer marketers to build product and brand awareness and drive
• Simpler to implement sales. DZone clients include some of the most innovative technology and tech-
enabled companies in the world including Red Hat, Cloud Elements, Sensu,
and Sauce Labs.
• Less accurate
CONS • Slower • Requires JWT library Devada, Inc.
and key management 600 Park Offices Drive
Suite 150
Research Triangle Park, NC 27709
888.678.0399 919.678.0300
In practice, there isn’t a single token validation method that’s
Copyright © 2021 Devada, Inc. All rights reserved. No part of this publication
always better than the other. Ideally, you should use a hybrid may be reproduced, stored in a retrieval system, or transmitted, in any form or
by means of electronic, mechanical, photocopying, or otherwise, without prior
approach of local and remote token validation to achieve the best written permission of the publisher.
performance and security balance for your application.
6 BROUGHT TO YOU IN PARTNERSHIP WITH
