Securing your APIs with OAuth proves that you have adopted a mature security model for your service. However, setting up OAuth in front of your API is not a trivial task. There are usually many architectural questions to be answered, more than the usual “which authorization server to choose” or “how to validate a token.”

Developers often encounter a problem when their solution consists of a service mesh hidden behind an API Gateway. Should the API Gateway be involved in the process? If so, how can it help?

In this article, we’ll demonstrate the different approaches of integrating OAuth with an API gateway. We’ll also showcase examples of how these approaches can be used with different types of API gateways.

Two Strategies for Sharing Tokens

There are two main strategies for sharing access tokens with the outside world:

• You can share the JSON Web Token generated by the Authorization Server with any external client. In this scenario, the same token is used externally and internally by your APIs.
• You can share externally an opaque token, which is then exchanged for a JWT. This means that an opaque token is used externally, but internally, your APIs work with a JWT.

For the best security, the latter option is typically the recommended choice. In this scenario, you don’t share any data embedded in your access token with any external clients. The access token contents are meant for your API, but if you share a JWT with external clients, anyone can decode the token and use its content.

Problems With Externalizing a JWT

Exposing a JWT with external clients can lead to privacy and security issues. Moreover, it can complicate your implementation. When you share a JWT with the external clients, developers may be able to decode the tokens and start using its contents, even though the tokens are intended just for your APIs. This could lead to situations where making any changes in the contents of the token can break existing implementations. The contents of a JWT token become a contract between you and the external developers, and breaking change should be avoided.

In the first approach, the integration with the API Gateway is not that crucial. The Gateway just forwards the JWT to the API, which can then validate it. Though, you can let the Gateway do some of the validation tasks.

If you decide to implement the recommended approach, proper integration with a gateway becomes more critical. To validate the token and read its contents, a JSON representation must be obtained. The exchange for a JWT can be done by every microservice which uses the token, but it can unnecessarily increase the traffic load and complicate the architecture as each service should be capable of performing the exchange. That’s why it’s much better to let the API Gateway handle this exchange. Now, let’s explore different ways to integrate with API gateways.

Approaches for Integration With API Gateways

A few approaches can be used when integrating with an API gateway. They will depend on the token sharing strategy you choose.

JWT Validation

If you decide to share JWTs with the outside world, it is good to have your API Gateway perform a validation of the incoming token. The Gateway can check the signature and perform some initial validation of the contents of the token. For example, it could assess the validity of the time-based claims, the issuer, the audience, or some required scopes.

Using JWT Validation, an API Gateway can reject requests with invalid tokens, limiting unnecessary traffic that would otherwise reach your internal network.

Phantom Token Approach

The Phantom Token Approach is one of the options you can implement if you want to share opaque tokens externally, but use JWTs between your internal services. The opaque token is exchanged for a JWT using the introspection pattern. The API gateway handles this exchange.

With this approach, all the services behind the Gateway don’t have to perform the exchange themselves, limiting network traffic. A Phantom Token strategy is easier to maintain than having all services handle introspection on their own, as there is only one point from which the Authorization Server is queried.

Split Token Approach

The Split Token Approach is another option in which an opaque token is exchanged at the API Gateway for a JWT. In this pattern the Authorization Server splits the generated token into two parts:

• The signature of the JWT
• Head and body of the JWT

The signature is used as the opaque token by any external clients. The other part is sent to the API Gateway together with a hashed signature, where it is cached. Upon a request, the API Gateway uses the incoming part of the token to look up the rest of it in its cache and then glues them back together to create a complete JWT. The resulting JWT is added to the request forwarded to any services behind the Gateway.

This approach helps you further limit the network traffic needed to exchange the opaque token for a JWT, as no additional requests to the Authorization Server are required.

Example API Gateway Integrations

Should you decide to integrate your OAuth solution with an API Gateway, the approach you choose depends on the type of the API Gateway that you use. There are many different solutions available on the market, and many companies are even using their own proprietary gateways. Below, we’ll examine three commercial API Gateway implementations.

Cloudflare: CDNs as Gateways

Cloudflare CDN provides enough functionality to be used as a distributed API Gateway. It is a Gateway spread across multiple data centers and regions with access to a shared key-value store and capable of making modifications to requests and responses through lambda functions.

If you use Cloudflare or your Gateway shares similar traits, the best approach would be to use the Split Token Approach, especially if the Authorization Server is deployed in a substantially lower number of locations. Thanks to the Split Token Approach, the Gateway does not have to query the Authorization Server on every request, which would otherwise considerably slow down the requests, given the servers are in different centers across the world.

When choosing the Split Token Approach, one thing to consider is that the Gateway needs access to a shared cache, one that can be easily populated by the Authorization Server, and accessed by all the distributed Gateway instances.

Nginx: On-Premise Gateways

Nginx is an example of an API Gateway that is installed on-premise. If this is the case for your Gateway solution, you should consider implementing the Phantom Token Approach, especially if the Authorization Server that you use is installed in the same data centers as the Gateway.

In such a situation, the additional request needed to introspect the token won’t give much of an overhead to the request. What is more, in this scenario, you will not necessarily need a shared cache. Even if you want to cache responses from the Authorization Server, this can be done by each of the Gateway instances on its own.

Google Apigee: A Diverse Solution

The answer to the question of which integration pattern is best in a particular scenario depends on the Gateway features rather than the concrete product or vendor. For example, in the case of Google Apigee, you could either use the cloud version or install your instance on-premise. Thus, choosing the OAuth integration approach will depend on the way Apigee is used. In the cloud environment, it will probably be better to use the Split Token Approach, whereas, with the on-premise installation, you would probably go with the Phantom Token Approach.

Conclusion

You can use a few different approaches to integrate OAuth with an API Gateway. The solution used should be chosen depending on the features of your API Gateway. When deciding between OAuth integration styles, two key points to consider are whether the Gateway is distributed or centralized and whether the Gateway has reasonable access to a shared cache.

Although sharing JWTs with external clients may seem straightforward to implement, remember that it is not a good practice from a security perspective. You should avoid it, as it lowers your security and privacy, and may lead to problems with your integrators.