As APIs and microservices evolve, the architecture used to secure these resources must also mature. Utilizing a token-based architecture to protect APIs is a robust, secure and scalable approach, and it is also much safer than API keys or basic authentication. However, token-based architecture comes in varying maturity levels, as outlined by the API Security Maturity Model.
In this article, we'll implement the Phantom Token Approach to achieve Level 3 of the API Security Maturity Model; Centralized Trust Using Claims. This approach externally uses opaque (reference) access tokens, exchanging them for a signed JSON Web Token (JWT) with scopes and claims in Kong Gateway. The system then passes that information onward to the upstream API.
Introspection is a way for a service to determine the state of a token and retrieve additional metadata about an active token.
When Kong Gateway is involved in the architecture, it typically performs the introspection. Kong Gateway receives an access token from a client requesting access to an API.
In an ideal scenario, we would use an opaque token if it's coming from a public client. An opaque token is not required, but we strongly recommend not using JWTs as public tokens, as they are much more likely to contain Personal Identifiable Information (PII).
Even if JWTs don't contain PII, developers will likely come to rely on the information within JWTs, and their applications will be at risk of breakage if the information issued in the JWT changes. Thus, it's a much better practice to issue opaque tokens to public clients.
When implementing the Phantom Token Approach, Kong Gateway will receive an opaque token and perform introspection. In the introspection process, Kong Gateway can send the application/JWT accept header. This header will make the introspection response from the Curity Identity Server be in the format of a JWT instead of the token data. This setting will allow Kong Gateway to perform a coarse-grained authorization by checking the JWT for scopes based on the configuration. If the required scopes are available, Kong Gateway will add the JWT to the Authorization header and forward the call to the upstream API. Then, the upstream API can consume the JWT as needed.
This approach allows for a more secure approach where an opaque token that does not contain any PII information to be issued to the client. When the client requests information from an API that potentially needs additional data, Kong Gateway can use the opaque token received and in turn, obtain a JWT that it can forward to the upstream API. The API will very likely need that additional information within the JWT to determine what data to return.
Curity has developed a specific plugin to handle introspection, especially related to the Phantom Token Approach. The Kong plugin is publicly available in the kong-phantom-token-plugin GitHub repository. This article describes how to set up an Integration with Kong Open Source and the configurations needed.
As mentioned earlier, this approach can also handle coarse-grained authorization using the JWT scope claim. This will allow Kong Gateway to quickly reject the call to the API if the correct scopes are not present in the token and prevent the call to the API.
Coarse-grained access control would probably be sufficient in many scenarios. Still, there will certainly be use cases where we need to consider additional parameters for authorizing access to data. These are scenarios where we can leverage Open Policy Agent (OPA) to implement a fine-grained access control policy.
Instead of calling the API, we can chain the Phantom Token Plugin to pass the JWT to the OPA Plugin. The OPA Plugin is responsible for making a callout to an instance of OPA that holds an access policy.
One example could be checking that the requesting user is the owner of the record requested. Or a separation of duty scenario where a user cannot approve a transaction that they also created. OPA with the Rego policy language is extremely powerful and can handle very complex policy expressions.
If the evaluation of the policy is successful, the flow will continue. Just like before, we added the JWT to the authorization header, which called the API.
This flow and its configuration are outlined in our API Authorization using Open Policy Agent and Kong article. It includes a dockerized example environment using open source or community edition software.
Kong Gateway and OPA are both open source software and readily available. Curity provides a Community Edition of the Curity Identity Server that is free for anyone to use.
Check out the articles mentioned above to get an environment running. Obtain an access token from the Curity Identity Server and use a tool like Insomnia or OAuth Tools to make a request to the service exposed by Kong Gateway (httpbin.org in the below example).
Suppose the Phantom Token Plugin authorizes the call after checking that the JWT received contains the configured scopes. In that case, the system adds JWT to the authorization header and forwards the call to the API.
httpbin.org is an HTTP request and response test service that can simply echo back what it received in the request. The below sample response shows that the authorization header received is a JWT and not the opaque token that was sent in the original request to Kong Gateway.
Issuing JWTs for public clients is a bad practice, and doing so could leak PII or cause instability if the structure of the JWT changes. It is better to issue opaque (by reference) tokens and have Kong Gateway introspect the opaque token and exchange it for a JWT that you can use internally (i.e., passed to the upstream API).
Or, for a more fine-grained access control approach, include OPA to evaluate an access control policy to determine if access should be allowed or not.
Here are some additional articles that cover these topics and other integration approaches for the Curity Identity Server, Kong Gateway and OPA:
Meet Emily. She’s an API product manager at ACME, Inc., an ecommerce company that runs on dozens of APIs. One morning, her team lead asks a simple question: “Who’s our top API consumer, and which of your APIs are causing the most issues right now?”
In the last two parts of this series, we discussed How to Strengthen a ReAct AI Agent with Kong AI Gateway and How to Build a Single-LLM AI Agent with Kong AI Gateway and LangGraph . In this third and final part, we're going to evolve the AI Agen
In my previous post, we discussed how we can implement a basic AI Agent with Kong AI Gateway. In part two of this series, we're going to review LangGraph fundamentals, rewrite the AI Agent and explore how Kong AI Gateway can be used to protect an LLM
This is part one of a series exploring how Kong AI Gateway can be used in an AI Agent development with LangGraph. The series comprises three parts: Basic ReAct AI Agent with Kong AI Gateway Single LLM ReAct AI Agent with Kong AI Gateway and LangGr
What Is RAG, and Why Should You Use It? RAG (Retrieval-Augmented Generation) is not a new concept in AI, and unsurprisingly, when talking to companies, everyone seems to have their own interpretation of how to implement it. So, let’s start with a r
In February 2024, Kong became the first API platform to launch a dedicated AI gateway, designed to bring production-grade performance, observability, and policy enforcement to GenAI workloads. At its core, Kong’s AI Gateway provides a universal API
In this article, which is based on my talk at VueConf Toronto 2023, we'll explore how to harness the power of Vue.js and micro frontends to create scalable, modular architectures that prioritize the developer experience. We'll unveil practical strate