Last month, we kicked off a series on API authentication and authorization with a glossary and some key principles to get you thinking about your auth practices. In this post, we’re looking in more depth at how to shape your security strategy with some guiding questions to improve your authentication strategy.
Every approach to auth comes with tradeoffs, and considering all the possible pros and cons can be overwhelming. The best auth strategy is going to depend on many factors and will require in-depth conversations across your organization.
One problem we’ve seen with discussions of auth protocols is that they tend to pit one technology against another, focusing on which one is “better”. These conversations try to cover all angles but often draw conclusions that are isolated from real-world applications. While the in-depth analysis in these pieces is extremely valuable, this approach is not a decision-making framework and can’t address specific use cases. Asking “What is best?” will give you lots to think about, but you won’t get a clear answer for your unique real-world scenario. When it comes to who should be asking these types of questions, it will depend on the structure of your organization and your current design process.
Authentication and authorization are about as ‘real-world’ as application design questions can get. Decisions about your authentication and authorization need to be practical. Your choices will affect how real users interact with your API and how real attackers might compromise your systems.
Auth practices are centered around your API users – who they are and how they interact with your resources. That’s why we suggest starting with these user-centered questions. We hope the questions below can help shape those conversations so that you can arrive at a cohesive solution that meets your unique needs.
Where Are Your API Consumers?
API companies cover many industries and many users. Three well-known API companies illustrate some of the differences:
OAuth2 for Consumer-Facing APIs
- Spotify is a music streaming company (and user of Stoplight’s open-source tool, Elements) whose end-users are private individuals using personal devices.
- Users authenticate to the Spotify API through a Spotify-created client application, like the Android or iOS mobile apps.
- Users are likely to be using many other applications on the same device, and expect some level of coordination for authentication.
- Laws require that users be notified of how Spotify is collecting their data and can control how it accesses other applications.
- Twilio is a developer tools company for multi-modal communication.
- Twilio’s end-users are developers and machines using Twilio to send communications. Even though message and call recipients are a large, diverse group, Twilio only needs to worry about auth functionality for developers and communications teams using their apps.
- Developers and communications teams will be authenticating to Twilio along with many other tools, primarily from machines inside a secure corporate network.
- Humana is a health insurer with tens of thousands of employees using dozens of SaaS tools.
- Humana employees in every division of the company are authenticating to internal and external APIs using Azure Active Directory.
- A large organization needs to prioritize scalability and efficiency in its auth practices. Active Directory uses SAML to coordinate Single Sign-On (SSO).
- Users will only be authenticating to these APIs from inside a secure Humana network, and the company already has extensive knowledge and trust of their employee users.
Each of these companies needs to authenticate users in a different way and they’ve adopted different auth strategies accordingly. Let’s map out their strategies and why each makes sense for their use case.
OAuth2 for Consumer-Facing APIs
Spotify uses OAuth2 to manage permissions and access for user accounts across devices and between applications. OAuth2 isn’t actually an authentication protocol – it’s an authorization framework compatible with a variety of token-based authentication methods, including many of the methods used on mobile devices. Spotify accepts three of the four authentication flows allowed by OAuth2, allowing app developers a lot of flexibility in how users log in to their Spotify accounts.
It’s important to note that OAuth2 is “stateful”, which means it’s probably not appropriate for consumer applications with a lot of sensitive data, like financial or medical services. APIs serving sensitive data should likely use session-based authentication.
For Spotify, which handles financial transactions separate from its music API service, OAuth2 is a good choice for a couple of reasons.
First, “stateful” token-based auth protocols compatible with OAuth2 are lightweight and flexible. They’re a great choice for public-facing applications where speed and cross-platform compatibility are important. An OAuth2 implementation can be set up quickly and cheaply – the server load is small, and a variety of free and low-cost open-source tools are available to help developers get started. A new consumer-facing API can integrate OAuth2 with little overhead, bringing a high-quality auth experience to users from the start.
Second, OAuth2 is designed to make it easy to control how data is shared with an API and between applications. It’s the technology behind the familiar authorization flow where one application asks for permission to access data from another application or device:
|
|
|
This data flow puts the information-sharing functionality of different applications in a language that is plain and transparent. API developers can specify exactly what data is shared at a granular level (name, email address, language preference, and profile picture, e.g.). Consumers feel comfortable with the familiar format. For a consumer-facing API with no sensitive data, OAuth2 offers many advantages.
JWT Enables Flexibility and Control for Developers
While OAuth2 is a good fit for Spotify, its flexible authentication flows, and fine-grained authorization tools are not well-suited for Twilio. Twilio’s API consumers will be accessing the API from a secure corporate network as part of an integrated workflow. There is less need for Twilio to collect or coordinate user data compared to Spotify because developers using the Twilio API specify their own data flows when they create applications.
Twilio uses token-based authentication, an appropriate choice for high-trust environments. Unlike Spotify, they specify the use of HTTP Basic authentication headers and use the JWT standard for tokens. It’s more tightly defined than what Spotify accepts, reflecting the more controlled environment where the Twilio API is used. However, it’s still compatible with both OAuth2 and OIDC (OpenID Connect). The choice of whether to use OAuth2, OIDC or another SSO protocol is up to API consumers, who can determine how it fits into their workflow before deciding which option is appropriate. Twilio’s choice of JWT enables a range of choices while still exercising tighter control over allowed authentication flows.
JWT enables additional data to accompany an authentication claim, which can be useful for role-based authorization. In many cases, the ‘users’ connecting to Twilio are devices executing a routine function through Github Actions or another automated script. With JWT, a user can specify whether it is a person or a machine, and what role it has in the organization. Passing role details during authentication simplifies authorization for developers by making it easy to assign different levels of authorization for human vs. machine users and content creators vs. administrators.
SAML Offers Smooth SSO for High-Trust, Large-Scale Environments
Azure Active Directory, a Microsoft tool for employee identity management and SSO is popular among large organizations. Among its users is Humana, a health insurance company with over 45,000 employees. Those employees use different API-based tools. Authenticating each of them separately would be both time-consuming and a security risk – password exhaustion is a real concern! A smooth, secure workflow is essential to their productivity, which is why they’ve chosen to use SSO for auth. The authentication and authorization protocol behind Active Directory, which enables true SSO, is SAM.
SAML is XML-based, which makes it a universal standard. Azure Active Directory provides integration tutorials for hundreds of different SaaS tools, and SAML can be used with any application that can handle XML input. Humana employees authenticate to the Active Directory server, which coordinates authorization for APIs connected to that server, allowing users to log on once and remain connected throughout the day.
Efficiency is a key benefit of SAML. XML data is lightweight, reducing the load on servers and speeding up communications between applications. Humana knows who its employees are, reducing the need to collect the kind of user data shared in the OAuth/OIDC family of technologies. A single identifier is adequate for each authenticated user.
The SAML format is particularly good for complex authorization scenarios, where an employee may have different access needs for different APIs. We’ll discuss how microservices architecture influences auth planning below. For enterprise-scale organizations, where the setup costs of an SSO provider are a worthwhile tradeoff, SAML is an effective tool that allows smooth administration of complex auth needs.
The biggest downside to SAML is that it can be a heavier technical lift to implement compared to newer technologies in the OAuth/OIDC family. It requires working with a third-party identity provider, whether Active Directory or another provider like Okta or Cloudflare.
What Do You Need To Know About Your Users?
The second question you should ask yourself is what you need to know about your users. Most API developers will fall into one of two groups:
- “My API users are consumers, and I need to know how they’re behaving.”
- “My API users are performing business functions and I need to know what they should be allowed to do.”
Your answer may lead you to a different set of auth tools and practices.
Focus on User Data For External APIs
If your users are external consumers, you have three main areas of concern over user data:
- You need to provide users control over what data they share
- You need enough information to identify important patterns in user behavior
- Regulatory compliance requires collecting the minimum amount of data
The OAuth2 cluster of technologies, including JWT and OIDC, is a good choice for this type of API. OIDC allows users and API developers fine-grained control over data shared between applications so that apps can function smoothly with a minimum of data. Compared to SAML or session-based cookies, JWTs allows API developers more control over the length of user sessions, greater access to information about user location and credential type, and more. With OAuth2 or OIDC, data like email addresses and language preferences can be shared, allowing a customized experience for end-users.
Prioritize Efficiency in High-Trust Environments
Users in a business context have less expectation of privacy than consumers, as they have already shared personal data with their employer and are less protected by regulations. In a work setting, API consumers demand efficiency in exchange for less privacy – OAuth2’s confirmation dialog boxes are undesirable and unnecessary.
For most internal and B2B APIs, users will be authenticated through some kind of SSO protocol. They expect to be able to move between applications and APIs seamlessly. JWT or SAML will allow you to identify and encode users’ roles in the organization. Both offer options for setting different levels of authorization, and each works with SSO. Which of these two formats is appropriate for your organization will depend on other factors, including the patterns of authorization we’ll discuss in the next section.
Will Your Users Have Different Access Levels?
Authentication processes tell you who is ‘inside’ your secure data. Authorization answers a different question: “Who can do what?” It’s a crucial question to answer if you have any sensitive data available anywhere in your APIs. Spotify doesn’t need complex authorization because playlists aren’t protected data. App developers may want to enable editing permissions on a playlist, but it’s a straightforward relationship between the user and the playlist. Humana, by contrast, has to manage large volumes of health and financial data and ensure that each employee has access to only the data they need. Setting permissions incorrectly could be very costly.
Different Access Patterns Require Different Authorization Models
Discussions of authorization models usually look at two models, each of which creates a different pattern of relationships between users and API data. If you are familiar with relational databases, it can be helpful to think of the difference between authorization models as one focused on tables versus one focused on rows.
Role-Based Authorization
The first model is role-based authorization. An API user’s role – Resource Owner, Administrator, or general User – determines the HTTP methods they can perform on endpoints. An Owner may be able to perform the full range of CRUD functions on any endpoint, while an Administrator may be able to create and update, but not delete. An authenticated User could have read-only access to all endpoints, while only certain endpoints would be available to unauthenticated Users. In terms of a relational database, role-based authorization grants access at the data-table level. Users are permitted to make certain types of queries to specific tables, depending on their role. Role-based auth is simple to implement and can be done with JWT-based authentication systems or SAML.
Claims-based or policy-based authorization
The second major pattern is called claims-based or policy-based authorization. Claims-based auth is needed in situations where users can have multiple roles because endpoint access is assigned and controlled at the individual user level. Each user is granted permissions separately, either manually or according to a set of rules encoded in the authorization server. In terms of the relational database, a user might be able to read all rows of a data table but only delete rows included on a join table. A different policy could restrict access to certain columns based on a user whitelist.
Support for claims-based authorization varies widely across REST platforms. It can be difficult to structure in a scalable way because it requires access to both user and application data to set permissions properly. The scenarios that call for claims-based authorization are more limited than for role-based auth and generally require careful planning to ensure framework compatibility. SAML is often the best choice because it offers the ability to encode multiple security assertions in one payload.
Clarify Your Needs Around Microservices
The two authorization patterns described above are easiest to explain at the monolith or application level, which is why we used the example of a relational database. The trouble is, in the modern distributed web, with the increasing use of microservices and API-based tooling, most API developers no longer work on monolithic applications.
Microservices architectures create a situation where an individual user may have role-based authorization within each API they access, but where each employee has a unique subset of roles across different APIs. Most teams will want to be able to manage this situation with an SSO since logging into microservices separately would be impractical.
What’s best practice is claims-based authorization at the SSO level, enabling individualized sets of role-based authorizations. SAML is generally considered more effective and appropriate than OIDC because the XML format makes it easier to extend a single set of assertions over multiple APIs. In almost all cases, the best way to achieve the balance of control and adaptability you need is with an SSO provider.
Move Auth Practices Forward with Design-First APIs
The most important thing API providers can do is learn about their users’ needs and offer options that address typical use cases. There is no best answer, so focus on supporting a range of good, appropriate choices based on your users.
Learning about your users’ needs can help you design an API that will adapt to their practices. If you learn that many of your users will use claims-based authorization, plan with that in mind and support JWT or SAML. If you find that your users are setting up similar policies for their claims-based auth, changing your endpoint mapping could allow them all to use role-based auth instead. For API designers and developers, the most valuable way to support your users’ auth needs is to make a commitment to fully support a standard set of auth practices. Consistency and proper implementation are more important than choosing the best or newest practice.
For all API consumers and producers, clearly understanding the use cases for authorization is going to help you design the most scalable, secure approach. Design-first is a guiding principle here at Stoplight, and we think there’s no better place to see the advantages than when thinking about your API authentication and authorization needs
Look for our next post in this series in June, when we’ll dig deeper into how design-first benefits your API security.
