Blog

OAuth 2.0

Create, Issue, and Validate OAuth 2.0 Tokens with API Gateway

October 10, 2018 · by Marwan Sabbouh and Jeff Costa ·

Akamai has been serving content from the edge for 20 years. Today’s Internet is much more than HTML, images, CSS, and JavaScript - its APIs. The data that APIs carry is extremely valuable, and APIs have become the “connective tissue” between companies. They power multiple user experiences, sometimes called “omnichannel endpoints.” Think of how many ways you can order a pizza today: Slack, SMS, mobile app, website, Alexa, smart watch. Organizations need thousands of APIs, and each one is a potential point of failure in terms of security, stability, and scalability.

The OAuth 2.0 protocol and supporting standards have emerged as the de-facto means for securing RESTful APIs. Akamai has added OAuth provider capability to its API Gateway, which enables API publishers to secure their APIs by federating with identity providers (IdPs). This blog post summarizes the new features in our OAuth 2.0 provider implementation.

To provide some context. let’s take a quick review of how OAuth works in the real world.

Everyday OAuth

Picture this: you just downloaded that app you’ve been wanting. Now that it's on your phone, you tap the icon to launch it. But before you can use it, a login dialog box appears asking you to sign in:

hootsuite

You have  two choices: a social media login or signing up directly with Hootsuite with your email address. If you choose the latter, Hootsuite gets your email address and a password of your choosing. A password that, in all likelihood, you are already using for another app or website. You must then hope that Hootsuite can protect your password from an adversary; that they properly store it (salted and hashed) on their systems so that it can’t be hacked.

Or you can simply use one of the three social logins that already know your username and password - and that you already trust - to authenticate you. If you tap the “Sign in with Facebook” button, you get taken to a screen where you enter your Facebook login credentials:

facebook

Once you enter your credentials, you are prompted to consent to the privileges you want the app to have, which can either be the default values or your something you customize:

facebook

You are then taken directly to Hootsuite, logged in with your Facebook credentials. As an astute user, you realize that you didn’t enter your credentials (username/password) directly into the Hootsuite app, but Facebook (authorization server) actually logged you in. If you’ve experienced this, you’ve used OAuth, likely without even knowing it.

The Gory Details

OAuth is an open protocol that exchanges credentials ( username and password) for access tokens. Access tokens are long, random strings that carry data and can be passed around without compromising a user’s original credentials. It allows users to share private resources without having to share their credentials everywhere.

Let's revisit the experience above from a technical perspective. First we must agree on some commonly-used OAuth terms for each of the actors that makes OAuth work:

  • The user is called the resource owner.

  • Facebook is the user’s Identity Provider (IdP). An IdP is a system that creates, maintains, and manages identity information. An identity provider offers user authentication as a service.

  • The Hootsuite app is the client app.

  • The API that provides data to the Hootsuite app is a resource server.

  • The Facebook authorization server is the authorization server.

Now that we have defined our actors, lets see how they all work together. OAuth allows a resource owner to grant client applications access to the data they own at a resource server. OAuth defines the flows that occur between the client app and the authorization server, resulting in an “authorization grant” by the resource owner to the client app.

A client app wishing to retrieve a resource from a resource server, obtains a token from the authorization server as shown in figure 1 below.

oauth

Figure 1: OAuth overview

Figure 1 shows a client app requesting an access token from an authorization server at Akamai. It starts with an outer flow - a second flow in the context of the outer flow.  These are the steps:

  1. The resource owner requests a resource by URL

  2. The resource server returns a 401 Unauthorized message to the app

  3. The app initiates an OAuth 2 flow with the authorization server

  4. Authorization server Initiates an OAuth flow with the IdP to authenticate the user

  5. IdP redirects to the IdP authorization endpoint

  6. The user submits credentials to the IdP

  7. The user consents to the request

  8. The IdP redirects back to the authorization server via a “callback URL” that contains a newly-minted IdP token

  9. The authorization server receives IdP token prompts the user to consent to the app accessing the resource URL

  10. The user consents to this request from the authorization server

  11. The authorization server returns the access token to the client app

The client app includes the access token in its request to the resource server to fetch the content. It includes this token on every subsequent request until the token expires.

The Akamai authorization server is Akamai’s implementation of an OAuth 2.0 provider.

Why OAuth at the Edge?

Serving content from the edge has undisputable advantages. Authentication at the edge has similar advantages: it’s faster, more available, more secure, and offloads origin traffic. Read on for more details.

IdP Agnostic

Any user of an IdP can become a user of your API. Akamai is agnostic to what identity provider you select. It can be an on-premise provider such as PingFederate or a social login such as Facebook or Github. Our sole requirement is the IdP support for OAuth 2.0.  To enable the use of your APIs by users of social networks, simply register the IdPs of the social networks into the Akamai authorization server for use by your API.  

Highly Available with DDoS Protection

Akamai’s authorization server runs in Akamai data centers that are geographically distributed across the world, making our OAuth implementation highly available. Requests to the authorization server are proxied through Akamai’s edge servers, which are configured with Akamai’s own Kona Site Defender solution. This provides protection against DDoS attacks by implementing request quotas and rate limiting. Quota enforcement ensures fair access to the authorization server by authenticated client apps, while rate limiting protects the authorization server against bursts of activity from a single client.

Token Confidentiality, Integrity, and Privacy

In some cases, IdP’s may include Personal Identifiable Information (PII) or some private data in their tokens. In order to ensure confidentiality of the token, the Akamai authorization server uses public key authenticated encryption to encrypt and authenticate the token prior to providing it to a client app. To ensure the integrity of the token, the Akamai authorization server signs the token using asymmetric cryptology prior to encrypting it. This double-signing of the tokens guarantees token integrity.

Origin Offload

By performing token validation at the edge, API publishers reap the benefits of Akamai’s edge server network verifying Akamai-issued tokens near the client. Only valid requests make it to origin, protecting it from any traffic that cannot be authenticated by our edge servers.

Granular Access Control with Scopes

When a client application like Hootsuite requests an access token from the Edge, it can optionally specify which scopes it would like to have associated with that token. OAuth 2.0 scopes provide a way to limit the amount of access granted to an access token - what the token can do and what it can access. In Hootsuite this manifests as a selectable list of what the token has access to - events, photos, videos, etc.

facebook

By defining and binding scopes to API resources at Akamai, you can ensure that only allowed resources may be accessed by apps such as Hootsuite. Below is an example of the new UI to set token scope. Note the ability to define and set scope names for each HTTP verb for a given resource.

oauth

Client App Authentication

The Akamai authorization server enforces access to authenticated client apps only.  Before granting credentials, an app like Hootsuite would have to register basic information with Akamai, including its name, description, the APIs that it wishes to access, and most importantly, a redirect URL.

The API Gateway now provides a user interface so that  API publishers can register client apps with the authorization server. Registration allows the Edge to uniquely identify an application, while rejecting those client apps that can’t be identified.

register client

Token Revocation

There are instances where a token must be revoked or invalidated before it expires, including:

  • The client app developer needs to include logout functionality in their client app.

  • The resource owner may need to revoke an authorization grant to a client app after it has been granted.

  • An API publisher has observed malicious activities by a certain resource owner.

The API Gateway supports token revocation on demand for all of these use cases.

Conclusion

API Gateway allows you to implement the most commonly-used authentication system to secure API traffic: OAuth 2.0. API Gateway now includes an authorization server that can issue tokens to client applications for use in authenticating API calls and validating the token signature at the edge.

Akamai’s implementation leverages the edge servers network for unlimited scale of token verification, unmatched security with protection against DDOS attacks, and high availability. This work is done at the edge, close to the application that is using the token. This reduces the latency for token validation calls, offloads the work from origin or a third party, and ensures that invalid tokens don’t reach resource servers.

Additional Resources

To find out more about API Gateway, see the following, check out our page here.