What is OAuth?
OAuth is an open standard authorization framework which uses tokens to delegate access.
There are two “auths” commonly used in digital security: authorization and authentication.
Simply put, authentication is the process of verifying users are who they claim to be, while authorization is the process of giving authenticated users permission to access resources. Both authentication and authorization are essential concepts in data security, but unfortunately, the name “OAuth” leaves that distinction up to the imagination.
OAuth is short for Open Authorization, so OAuth tokens are used to grant users permission to access resources. On the other side of the “auth” coin, OpenID is a protocol which allows APIs to grant access to users through another API. In other words, OAuth is useful for authorization, while OpenID is useful for authentication.
Similarly, SAML (Security Assertion Markup Language) is an authentication protocol allowing users to be authenticated to multiple client servers through a single identity provider. SAML tends to be specific to users, while OAuth is specific to applications.
OAuth Security
If your bank let strangers roam freely around their vault and flip through their documentation, would you continue to bank there?
Security is a top priority for financial institutions, but it isn’t enough to simply be secure. If security were the only consideration, banks would simply be sealed in concrete and steel capsules. But in addition to being secure, banks also have to be accessible.
Financial institutions must be accessible so their customers can talk to tellers in the lobby, access their funds, and receive legal documentation. They should also be secure so interlopers cannot access funds or information which belongs to legitimate users.
Regarding API access, this give-and-take between security and accessibility presents a whole new realm of challenges. But despite the difficulty of pursuing this balance, it must be a top priority for organizations.
This is why letting other APIs access your API through OAuth tokens is an important process so resource owners can access their resources through your API.
Why OAuth?
Consider the example of a hotel: guests need access to their hotel rooms, but not to each others. To coordinate this complex matrix of permissions, there has to be a uniform format allowing permissions to be granted or revoked to specific users and specific rooms over specific time periods.
Most modern hotels have moved away from physical keys in favour of digital keycards because they give managers more granular control over granting and revoking permissions, reducing the security risks of lost or stolen keys.
In API access, OAuth fills the role of a hotel’s magnetized key card: a unified standard to delegate access to other APIs (on behalf of users) to facilitate access and protect security for both the client and the user.
OAuth Versions and Their Differences
OAuth 2.0 was a ground-up rebuild of OAuth 1.0, which shared the same goals and functionality but introduced improvements like simplified signatures and short-lived tokens.
While OAuth 2.0 was a significant improvement over 1.0, it wasn’t perfect. In the decade since 2.0, several improvements have been made, culminating in the in-progress 2.1 protocol.
OAuth 2.1 consolidates post-2.0 features by integrating many RFCs that have added or removed functions from the original 2.0 protocol. There were only two years between OAuth 1.0 (2010) and OAuth 2.0 (2012), and in the intervening decade, new best practices and exploits have been unearthed, so OAuth 2.1 is an attempt to codify these best practices in an up-to-date protocol.
PKCE in OAuth 2.1
PKCE (Proof Key for Code Exchange) is an extension to the authorization code flow, which is more secure than the traditional implicit flow.
PKCE is an attempt to mitigate the security risks associated with stolen client secrets. It does this by using an improved authorization flow using code challenges and code verifiers to authenticate users rather than using static client secrets. This will be explained in greater detail in the section on OAuth code flow.
Client secrets are vulnerable to being intercepted, and many developers correctly realized the assumption that client secrets could be kept secret indefinitely was short-sighted and doomed to fail given enough time. This is why PKCE (pronounced “pixie”) is an essential component of OAuth 2.1.
4 Components of OAuth
To understand the OAuth flow, it’s vital to understand the parts of API-to-API access.
1. Tokens
The basic building blocks of OAuth are the tokens exchanged between servers. Tokens can have many different formats and can be generated in many different ways, but there are three types of tokens used in the OAuth flow.
Authorization Tokens
Authorization tokens are given by an authorization server in response to an authorization request by the client-server. Authorization tokens don’t give the client access to their desired data, but it allows them to use their verification to exchange the authorization token for an access token. Authorization and access are split between two separate tokens because these tokens are used with different servers and offer an additional level of security. The authorization token is used to create the verification that produces an access token.
Access Tokens
Once the authorization token is received by the client-server, it is used to request an access token. The client server sends a verification (generated using a client secret or code verifier with PKCE) to establish the validity of the client server. Once the authorization server receives the authorization token and verification, it sends back an access token the user server then uses directly with the resource server to access the resources.
Refresh Tokens
Unlike authorization and access tokens, refresh tokens aren’t created on their own, but are issued along with access tokens. Since access tokens in OAuth 2.0 are designed to expire (one of the major problems with OAuth 1.0 was the persistence of tokens), refresh tokens are designed to renew the access token when it expires so sessions can continue uninterrupted, but new sessions would require new authentication.
Thinking back to the example of a hotel room, the difference between an authorization and access token can be compared to the magnetized key card and the code to a safe. The authorization token gets the client the opportunity to authenticate themselves – it gets them into the room – but the access token is required to access the actual resources: the valuables in the safe.
2. Servers
Understanding the roles of authorization, access, and refresh tokens is difficult without also understanding the various servers they are passed between. Here, the nomenclature can be confusing because language such as “client” and “resource” is used differently in separate contexts. But in the world of OAuth, the terms “client” and “resource” are defined in the context of the authorization request, rather than in the context of a business relationship, in the same way words like “right” and “left” are defined in the context of what direction a person is facing.
Client Server
In the API access context, the client server is the server requesting access on behalf of the user. For example, when you visit a website that requests a Facebook login to create an account, the website API is the client server, while Facebook is the resource server.
Authorization Server
The authorization server plays a crucial role in the OAuth flow by serving as the “middleman” between the client and resource server. The authorization server receives the authorization request from the client-server, issues an authorization token, and when it receives authentication, it issues an access token the client then uses to access the resource server. Authorization servers are tied to the resource server but don’t have direct access to the resources themselves.
Resource Server
The resource server is the server that contains the resources the API would like to access. For example, if your API wants to include an integration from Google Maps, Google Maps is the Resource Server while your API is the client-server. The resource server receives the access token from the client-server and responds with the requested data.
3. Scope
Just like a bank wants customers in their lobby but not in their vault, APIs want other APIs to have access to authorized data but not free rein to access and edit unauthorized data. This is where API keys and OAuth tokens are especially useful – API keys grant API access to another API, but OAuth tokens grant specific resource owners access to their data in an API.
The scope of API-to-API access refers to what kinds of information the client-server can access. For example, a social network API may allow users to upload photos from a resource server such as Dropbox or Google Drive. The client server (the social network) needs access to the data on the resource server (Dropbox) but doesn’t need access to upload new photos, delete photos, or reset the user’s password.
Because of that, the scope of the API access is delegated by the client-server on behalf of the user. For example, an API with a “share” button may request access to a user’s contacts but wouldn’t need access to a user’s camera or location.
4. Timeline
One of the key improvements of OAuth 2.0 and 2.1 are short-lived tokens. In OAuth 1.0, tokens were persistent until revoked. For example, Twitter OAuth 1.0 tokens did not expire at all unless they were specifically revoked by the user.
There are two kinds of authentication: stateless and stateful.
- Stateful authentication tokens can be revoked at any time but are difficult to use with API to API access. Stateful authentication stores credentials on the backend side which gives the users the ability to revoke access at any time.
- Stateless authentication stores credentials on the client side (browser) so the token can’t be revoked until it expires but is easier to integrate with third-party APIs because the authentication is already stored on the user’s side.
Revoking API keys is a different process from revoking OAuth tokens and can be assisted with the help of API management like The Auth API. API key management is an important resource for APIs of every size. Whether your API has dozens of users or millions, keeping track of individual API keys is an impossible task without solutions like The Auth API.
Understanding OAuth Flow
With the addition of OAuth 2.1 and PKCE, the flow of code is different from previous iterations of OAuth.
First, a request is generated by the client-server. This authorization request is sent to the authorization server, which responds with an authorization token. A unique authorization token is generated with each request, and the authorization API can create tokens using any method or format that suits their needs. Many tokens are issued in the JWT (JSON Web Token, pronounced “jot”) format. Once the user server receives the authorization token, it exchanges the authorization token and verification for an access token.
This is where PKCE diverges from the authorization code flow. In the traditional authorization code flow, the client would have its own client secret that it would send along with the authorization token to the authorization server. The weakness of this approach is that the client’s secret could be intercepted, making it unnecessarily vulnerable to security attacks.
Using PKCE, the authentication server instead sends a hashed code to the client, using its client verifier code to create a code challenge. The code challenge is an encoded string that gets decrypted by the authentication server. The authentication server can match the actual code challenge to the code challenge they expected to receive based on the verification and client information, and if the results match, the authentication server can then provide the client with an access token.
Once the access token is received by the client-server, it is exchanged for the requested resources from the resource server.
PKCE is more secure than the client secret approach because the verification code is different every time based on the unique authorization token generated with each request.
Until the access token has been revoked (either actively through stateful authentication or passively through stateless authentication), the loop of requests and resources continues for the duration of the session.
API Keys vs OAuth Tokens
API keys and OAuth tokens accomplish similar results in slightly different contexts. API keys are used to identify the APIs that are requesting access, while OAuth tokens identify the users requesting resources.
API keys typically give an API full access to the permissions of another API but don’t give the API-specific data that belongs to users. For instance, a Google Maps API would use an API key to give access to another API to integrate an embedded Google Map onto their interface, but a specific user would use an OAuth token to access their saved locations within Google Maps.
OAuth tokens are used by resource owners who are using the client-server to access data on the resource server. API keys are used by one API to communicate with another API. Because of that relationship, OAuth tokens and API keys aren’t mutually exclusive options but rather are parts of the same process.
Manage API Keys with The Auth API
As integration and communication between APIs become more advanced, the authorization needs of your API are likely to continue growing. Managing API keys and access tokens can become overwhelming without the help of The Auth API, experts in API access and analytics.
Receive regular reports on your API users, revoke access at any time, and create new keys with the click of a button using The Auth API’s developer-friendly API. Start a free trial today to see what The Auth API can do for you.
