OAuth Application Guides for Solution Design

When I first started working with OAuth technologies, I found many online tutorials quite limited. They typically only focused on the basics, such as performing an OpenID Connect redirect in a web application or validating a JWT in an API. The same basics were then repeatedly explained with many technologies. As a result, I often struggled to design solutions. What I needed was a guide that would lead me to a solution for each unique problem.

This was part of our motivation behind developing the Curity Guides, an entry point to our resource articles. They explain the "getting started" basics per technology but also link to articles that explain the deeper aspects of OAuth to help you find solutions to larger problems. These solutions are all based on standards that will work for any Identity and Access Management (IAM) system that supports them.

Guides Usage

We first ask, What are you building?:

We then ask, What technology are you using?:

Results then consist of one or more code examples in that technology, along with how-to articles on getting an end-to-end setup working. We also include some related articles, such as best practices that we think will be relevant further down the line:

Designing Your Architecture

Curity resources also include detailed design patterns for managing OAuth flows in clients, securing access to data, and dealing with deployment and migration. They also enable you to scale the architecture across many components, including mature business systems.

When people first think of OAuth technologies, they typically focus on the visual aspects, such as login redirects or multi-factor authentication. However, OAuth is primarily about protecting data. As such, I find that a better approach is to start with the data and work backward. The following sections describe Curity Guides in this manner.

APIs

Curity's API Guides explain how to work with JWT access tokens in various technologies and recommend libraries to implement our JWT Security Best Practices. JWT validation should be done for every request across all of your APIs.

The result of validating a JWT in an API request is to provide a 'Claims Principal' that is then used for your business authorization. This is explained further in the scopes and claims articles and can involve domain-specific data and identity data.

API Gateway

It is also best to use an API Gateway rather than directly exposing API servers to the internet. In addition to securely coding and hosting your APIs, companies must also deal with privacy and legal requirements, which are a major concern these days.

Although JWTs enable modern security for APIs, these tokens are also readable by clients and could reveal sensitive data such as Personally Identifiable Information (PII). To avoid this type of disclosure, it is recommended to instead return opaque tokens to clients, then use an API gateway to perform a swap before forwarding the JWT to APIs:

API Gateway Guides provides examples for all popular gateways and reverse proxies. These show how to route API requests while translating from opaque tokens or secure cookies to JWTs. There are other use cases where the gateway can be used, including advanced routing of users across legal boundaries with data sovereignty restrictions.

Web Apps

The Website Guides describe how to implement the standard OpenID Connect code flow using both Proof Key for Code Exchange (PKCE) and a client secret. The current OAuth best practices for browser-based apps recommend keeping tokens out of the browser and using only the latest SameSite secure cookies.

Many companies prefer to develop Single Page Applications (SPA) rather than using website technology stacks. Technologies such as React or Angular can result in a modern interactive user experience and more productive development. However, the problem with SPAs is that they do not have a backend. So, how do you issue secure cookies?

The SPA Guides demonstrate how to solve this problem by implementing OpenID Connect in an API-driven manner using the Token Handler Pattern, then only using secure cookies in API requests. This maintains the benefits of an SPA architecture, including the ability to deploy static content to many locations via a Content Delivery Network (CDN) for good global performance.

Mobile Apps

The OpenID Connect flow for mobile apps has traditionally used the AppAuth pattern described in RFC8252 to open an integrated instance of the system browser. The login is then performed in an ASWebAuthenticationSession window on iOS or a Chrome Custom Tab on Android. Though it can be tricky to implement a reliable user experience, Mobile Guides explain how to design these flows.

An alternative approach that provides more robust security is the Hypermedia Authentication API (HAAPI), a proposed standard. HAAPI authenticates the mobile client before allowing authentication to be attempted, using client attestation techniques. It also avoids using the browser in most cases to reduce threats. An API-driven OpenID Connect flow is then used to sign the user in, offering the best control over the user experience:

Additional Topics

OAuth is a framework rather than an out-of-the-box solution, and this is reflected in the Resource Articles found in the guide's results. Once you get past the basics, you can also use our resources to understand how to extend the Identity Server and operate it in complex clustered deployments, which are often multi-cloud these days.

Future Guides

Additional guides and resources further explain the ever-growing OAuth canon of specifications and map them to specific use cases. A recent example is CIBA, which enables call center employees to securely operate on behalf of end-users.

Many of our resources demonstrate advanced patterns such as those used in Financial Grade APIs (FAPI) or Open Banking. Some of the techniques involved, such as Mutual TLS, are also commonly used by other software companies, such as those that provide B2B APIs to partners.

Conclusion

OAuth flows are often highly architectural, and being aware of the best security design patterns will reduce costs. The Curity Guides aim to start you on the right path so that your apps are secure, code remains simple, and security is easy to extend over time. Even if you don't use the Curity Identity Server, we hope you will find our guides helpful when building new security solutions.