Auth – the informal term for authentication and authorization practices – has evolved significantly in the last ten years. Unfortunately, many APIs lag behind on security measures, relying on API keys and client secrets that travel directly between users and resources or improper implementations of newer tools.
It’s past time for the API industry to catch up. Chief Information Security Officers and incident responders know how important it is to have solid security practices in place to handle the unknown threats your API will face. It’s not possible to plan for all risks, but smart proactive measures can prevent risks from causing a serious crisis.
This article is the first of three in a series on API auth best practices. API security encompasses a lot more than auth practices, but authentication and authorization are essential components to get right. This series will give you principles and practices to help you design your API security strategy.
In our next post, we’ll dive into questions about use cases – how can you figure out the best approach for your organization? Then, we’ll talk with a Stoplight engineering leader about his experiences building and maintaining secure APIs. For now, we’ll start by getting everyone on the same page with terminology and concepts; check out these API authorization best practices.
API Auth Glossary
It’s not uncommon for developers to have some confusion about basic auth terminology, especially when teams have varied backgrounds and education. Getting alignment on your auth practices requires everyone to be speaking the same language.
An auth glossary is a good place to start the conversation. Here we’ve organized key terms and their categories, along with links to high-quality, in-depth info if you want to learn more.
- Authentication: Who is allowed to log in? Authentication means verifying the identity of a user or device before allowing access to a resource.
- Authorization: What can a specific authenticated user do? Authorization refers to the set of permission rules that check for levels of access and allow actions for authenticated users.
- Stateful Auth: The server maintains a record of the current authentication status of a user. The server ‘state’ reflects exactly who is logged in to a resource at any given time and only provides access to those users. Stateful auth uses sessions and cookies to keep track of the user state.
- Session: A defined period of time when a user is logged in to a resource. Generally short, measured in hours. Begins when a user is authenticated and ends either based on a pre-set timeout or when the user logs out.
- Cookie: An HTTP header containing data about the user and session. Cookies can be used for data collection and personalization – in those cases, users must be notified and allowed to opt out. Cookies used for auth purposes do NOT require separate notification, as user permission is implied by the authentication process. However, session cookies also contain very little information about who the user is and should be deleted immediately at the end of a session, so there is less potential for abuse than with other cookie types.
- Session-based Auth: In session-based authentication with a cookie, once a user is authenticated, a `Set-Cookie` HTTP header is used to assign a session cookie. That cookie is stored on the server side. Each action the user takes with the resource, in the form of an HTTP request, includes a `Cookie` header. So long as the cookie value is active on the resource server, the user may continue to access the resource. When the user logs out or time expires, the cookie is deleted from the resource server and the session ends. When the user logs in again, a new cookie will be generated and a brand-new session will be initiated. This approach places more demands on the resource server and storage but makes it more difficult for credentials to be stolen or misused.
- A note for APIs: HTTP requests are the meat and potatoes of APIs, so session-based auth can work quite well for APIs. However, the cookie format was developed for browsers, and if the ‘client’ that’s consuming your API isn’t a browser, it can be harder to use cookies. Cookies are plain text, though, so any client can handle them with a little help. Tools like this JS library or even cURL requests can do the job.
- Stateless Auth: In stateless auth, the server does not maintain a record of authentication status. Instead, the responsibility rests with the user or a third-party auth service. Since the resource server does not maintain any record of who is currently using the resource, stateless auth relies on headers and tokens.
- Basic Authorization Header: An HTTP header used to pass a string value (e.g., an encrypted password or API key) to a resource.
- Token: A small data object provided to a client/user by an authorization server. The basic structure of an authorization token is a Header, which defines the token type and encryption algorithm, a Payload, which includes JSON-format data about the user and token expiry, and a Signature, which is an encrypted value that ensures the token hasn’t been modified.
- Token Exchange: Two round-trip data transactions:
- First, a client application sends credentials (e.g. username/password, biometrics, or a device ID and secret) to an authentication server. If credentials are valid, the auth server returns a token to the client.
- Second, the client application sends the token to the application server. If the token is valid, the application returns the resources that the token is allowed to access.
- JSON Web Token/JWT: (pronounced ‘jot’) An open standard format for authentication tokens. Allows more data to be contained than a simple authorization header, including encoded expiration and customizable encryption algorithms.
- Token-based Auth: Unlike session-based stateful auth, token-based auth separates resources from the auth process. The user retains control over the token, and the resource simply verifies that the token is valid. The resource has rules for validating tokens, which can include a blacklist of expired or blocked tokens. Tokens can remain valid for long periods of time and are often sent to users along with a renewal token, so they can be reused many times. This reduces the storage burden on the resource but has more vulnerabilities from misused tokens.
- A note for APIs: We’ll talk about this at length in our next post in this series, but in many cases, APIs are being consumed as microservices or as one of many developer tools. In these scenarios, your users are likely to demand a streamlined auth process that doesn’t require separate passwords and multiple log-ins per day. This is where token-based auth shines. Token reuse has potential security risks, but it also can help streamline your auth processes.
- Single Sign-On/SSO: Authorization servers that take a single set of user credentials to provide tokens for multiple applications and resources. In general, SSO works with stateless auth, because a third party coordinates credentials and authentication, not the resource itself. SSO – and stateless auth practices as a whole – are best used in high-trust environments.
- OpenID Connect/OIDC: An identity management layer widely used with OAuth2. Allows certain customizable user and session data to be passed to the application servers with a REST-like interface.
- Security Assertion Markup Language/SAML: An XML-based markup language. An older but still widely-used authentication protocol and token format. We’ll talk more about SAML in the next post in this series!
- OAuth2: An open standard for authorization that uses a centralized authentication mechanism to coordinate tokens between different applications. NOT an authentication protocol. We’ll talk about OAuth more in our next post, as well.
Three Takeaways For API Auth Decisions
- The purpose of robust authentication and authorization protocols is to keep careful divisions between sensitive user data, authentication credentials, and resources. For API developers, that means getting rid of the basic API key, which is usually passed directly to the API resource server. The intermediate server that handles token exchanges in modern protocols protects both the user and the resource provider in the case of a security exploit. In session-based authentication, the auth cookie contains no more data than absolutely necessary for auth purposes and is deleted automatically and immediately when the session ends. Proper compliance with any of the standards we’ve discussed gets you a long way toward this goal.
- Be clear about who has responsibility for decisions around SSO. SSO is the best way to combat password fatigue and can be a meaningful contributor to employee productivity. It’s a very valuable practice, but it’s really a question for API consumers, rather than API developers. It also comes with significant security drawbacks if it’s implemented poorly or in low-trust scenarios. If you are building a public-facing API, so long as you provide an SSO-compliant authentication option, your users can choose whether or not to use SSO. If you’re an API consumer, think carefully about how and where to implement SSO.
- Remember that good authorization and authentication practices don’t happen by accident. Compliance requires planning and follow-through. The multitude of standards and implementations means it’s quite easy to wind up with incompatible practices, leading you to compromise your data segregation. We’ll talk more about how a design-first approach to API design helps your security strategy in the third post in this series.
We encourage you to spend some time learning about the various auth options that are available. Ask your API stakeholders to do the same. Then, think carefully about your approach to authentication and authorization – your API development process should include planning for these needs from the start. You can’t make informed decisions if you don’t understand your options! Refer back to this guide when you need to refresh yourself or your team on the basics.
You can also check out these other Auth resources to learn more:
