Access Management Isn’t Just for Web Applications — It’s for APIs, Too!

As more businesses enrich their user experiences for mobile devices and client-side browser technologies, they are forced to create publicly accessible APIs. So often, those APIs read and modify sensitive customer data, making them just one wrong API call away from leaking or corrupting important user data. Therefore, we need to make sure that APIs are secured so that only the right users of the right client applications can call them. This is where OAuth 2.0 comes in handy.

The OAuth 2.0 Framework

The OAuth 2.0 framework is a light-weight RESTful framework for protecting APIs that use system resources and user data. In a similar way to how cookies are used to authorize access to protected web resources, access tokens are used in OAuth to authorize use of API resources. Each access token has a specific scope, requested by the API client and consented to by the end user, that defines the API calls it can make. The high-level process is shown in the diagram below. It involves the client application, the application end user (called the Resource Owner), the API (called the Resource Server), and a centralized Authorization Server that provides and validates tokens.

When resource owners (1) trigger a call of a protected API, the client application (2) requests an access token from the Authorization Server (AS) with the appropriate scope(s). The AS (3) interacts with the resource owners to log them in, display the scope(s) requested by the client, and obtain their consent. In fact, if you’ve logged into an application with a Google or Facebook account before, you should already have seen these sorts of consent screens.

The AS stores the user’s consent and (4) returns the access token to the client, which then (5) invokes the resource server (RS) with that access token. The RS (6) validates the token with the AS. If the token is valid and has appropriate scope, the RS (7) fulfills the service, letting the client finally (8) render the result to the user.

The same access token can be reused until it expires, at which time the client must obtain a new token. Otherwise, the AS could also provide a refresh token that would allow the client to obtain similarly-scoped access tokens without user interaction.

API Security with OAuth

We’ve purposely left out some specifics of the interactions, like endpoints and message exchanges, because they can be a bit overwhelming at first, but the overall concept is relatively simple: users authorize application access to their personal resources, and those authorizations take the form of access tokens. Despite this simplicity of concept, however, it can seem daunting to implement OAuth, depending on your maturity. There are a lot of moving pieces to consider and impacts to several key business processes. To make sure you’re aware of these impacts and streamline things a bit, we’ve provide a few helpful steps.

1. Inventory your Applications and APIs

First, start by taking stock of your business applications and services (those you currently have and those in the pipeline), focusing on the most critical and highest risk ones. Identify what APIs they consume, who controls those APIs (i.e. whether they are hosted internally or externally) and what parts of the applications make the API calls. The components consuming the APIs will become your OAuth clients, and the APIs consume will become Resource Servers. Communicate with providers of external APIs to determine their level of OAuth support.

2. Identify Protected Resources and Scopes

Next, identify the system resource and user data operations processed by the applications and APIs. These will determine the set of scopes that will protect APIs and that clients will request. For externally hosted APIs, you’re limited to the scopes the provider offers, but for internal APIs, you’ll be creating your own scopes.

When determining scopes, don’t think about database tables or low-level system objects, but instead focus on activities and data operations that impact end users or your internal systems. For end users, this could be reading or writing profile data, syncing calendar entries or contacts, sending a notification, etc. For system resources, this could be creating a scheduled job, triggering an event, or using some other system service.

For any scope that needs consent from the end user, you’ll need to create a meaningful description to show. The description should be concise yet informative of the consequences of data or services being accessed. For example, [this app wants to…] read information about you, including your name, email address, and phone number is much more informative than [this app wants to…] read profile data.

Once you’ve catalogued your scopes and descriptions, map them back to the APIs that will be protected by them and the clients that will be requesting them.

3. Select Client Types and Authorization Flows

The actual interaction that clients use to obtain access tokens are called authorization flows or grant types in OAuth. There are several available, but only a few that should really be used for a given type of client. We don’t have room for a full treatment of all the grant types and flows (several good resources do already exist), but we will offer a few quick tips.

• Server-side web applications should use the Authorization Code grant, though they could also use the SAML 2.0 Profile or JWT Profile extension grants if the identity store is federated.
• Server-side batch processes should use Client Credentials grant.
• Client-side web applications and native applications should also use Authorization Code grant, but they should incorporate the PKCE extension for added security if they have cryptographic capabilities.
• Other applications that may not have access to a browser, such as smart appliances or IoT devices should use the Device Code extension grant, also with the PKCE extension.

NOTE: There are some commonly supported grants, e.g. Resource Owner Password, that have been deprecated for security purposes that we did not include in this list.

Regardless of the grant type, there are a few common security matters to be aware of. First, the transmission of credentials and tokens needs to be over a secure channel. Second, resource owners interact with the Authorization Server directly whenever possible to keep their credentials away from client applications. This is usually done via browser. Third, tokens should be kept out of the browser whenever possible to avoid unnecessary exposure to malicious browser agents. If this cannot be avoided, token lifetimes should be relatively short. Finally, clients should authenticate to the Authorization Server whenever possible to prove their legitimacy. (Server-side clients are generally considered confidential clients that can securely store credentials and long-lived tokens. Browser and native clients are considered public clients that are not as controlled and cannot provide the same level of security. Therefore, use confidential clients whenever possible.) These last two points may require you to redesign a client application to improve security. Again, for external APIs, determine which grant types are supported by your provider.

4. Review Access Management Processes

The OAuth framework doesn’t specify how authentication and user consent must happen. It is just assumed that you have processes in place to securely authenticate users and store/manage consent. Here are the most important touch points to these IAM processes.

• MFA for sign-on and profile management. If you haven’t already implemented MFA or risk-based authentication for sign-on and user profile management, it’s time to do so. The whole OAuth process is based on the premise that resource owners are accurately authenticated. MFA provides the best means to do that.
• Implicit consent at onboarding. Consent can be obtained from users in many ways. Many companies already have some sort of terms and conditions that users must agree to when they register or activate their accounts. If these are worded correctly, they could also be considered as applying to appropriate OAuth scopes as well. Using this form of implicit consent would allow for decreasing the number of consent interactions and streamlining the application experience.
• Explicit consent at sign on. Consent that cannot or should not be implicitly provided at onboarding time will need to be gathered later during application usage. This could occur right after the user logs in to the application or as a particular application feature is used, and it will require retrieving and displaying scope descriptions and storing the user decisions. Your sign-on process will need to be modified to support these abilities, both when the user already has an active session and when the user needs to authenticate to establish one.
• Ongoing consent in profile management. Lastly, in some cases, resource owners may want to remove a consent previously given to a client. Alongside other user profile management options like changing passwords and MFA channel details, you will also want to provide the ability to list, view, and selectively revoke consents by client. If a user does revoke consent, there should be a process to revoke any related outstanding tokens, especially refresh tokens, to stop related application activities.

5. Architect OAuth Services

When planning to implement OAuth services, it’s best to start by looking at your existing investments to see what capabilities they offer. Plenty of products come with some level of support for producing or consuming OAuth.

• Access Management platforms, like Oracle Access Manager and Okta, provide the means to create and configure Authorization Servers and protect API web resources with polices requiring OAuth tokens. These systems also have consent management capabilities that will tie into their hosted sign-one processes. If the default hosted experience is not satisfactory, plugin points and APIs will be provided for more highly customized UI experiences. The primary advantage of these systems is that sign on, MFA, and consent management will be in one place and highly flexible, though some are more cloud-friendly than others.
• API gateways and development platforms, like MuleSoft, provide easy ways to wrap OAuth validation around existing APIs, making these products ideal for quickly creating Resource Servers. They can also provide load balancing and deployment pipelines for quick and continuous development.
• Cloud providers, such as Microsoft and AWS, often have both IAM and API management capabilities as well, allowing you to configure simple Authorization Servers and Resource Servers fairly quickly. This makes them similar to AM systems and API gateways, but they support fewer options and have more limited flexibility for customization.

However you assemble your OAuth architecture, be sure to pay attention to licensing models as OAuth services may need special activation, require additional licensing or accrue additional operational costs.

If COTS products are not applicable or are cost prohibitive, many free and open source libraries exist to create your own OAuth services. If you choose this route, be sure to consult established best practices for securely and efficiently managing credentials and tokens. Client application developers will especially need to be made aware of several of these practices as they may not have security expertise/experience. In fact, we recommend you consider creating an OAuth Client library to standardize best practices and shield application developers from security and performance considerations so they can focus on business logic.

Conclusion

API Security is a strategic part of Access Management, and OAuth is a critical security component for protecting APIs and their resources. Even though it may seem simple at first, there is a lot required to plan and implement OAuth, including identifying scopes, enhancing IAM processes, and refactoring client applications. Just remember, don’t boil the ocean! Start with the most critical applications and APIs to get a solid groundwork in place with those. Then, you can expand from there as needed. It’s better to secure something now than nothing later.

---

Zirous is an experienced strategic partner who understands how company needs and processes affect governance and access management strategies, including API security. Reach out to learn how our partnerships like Oracle, SailPoint, Okta, and MuleSoft can provide value to your organization.