Integrating the Curity Identity Server with API Gateways using the Phantom Token Pattern

There are several articles in API gateway guides that describe how to implement the phantom token pattern, to ensure the confidentiality of tokens returned to internet clients. It should also be possible to leverage the pattern in any other API gateway, as long as it is capable of performing a few common tasks.

Configuring the Curity Identity Server

The configuration needed on the Curity Identity Server side is fairly minimal and is typically set up by default. If the first config has been completed with the defaults the system is set up to handle introspection. I.e., there is an introspection endpoint configured. Outside of that, a client with the Introspection capability is needed.

How to configure this as well as configuration examples are outlined in the OAuth Introspection and Phantom Tokens article.

The API Gateway

The API Gateway needs to be able to capture the opaque token from the incoming request and send that to the Curity Identity Server for introspection in order to get a JWT back. The JWT could then be cached by the gateway depending on its capabilities and then added to the Authorization header in the upstream request to the API.

Most gateways have some type of introspection capability that can be used. It would probably require the introspection endpoint to be set as well as client_id and client_secret so that the gateway can authenticate itself against the Curity Identity Server. The client_id and client_secret can be obtained from the Curity Identity Server configuration and should be of the client configured with the Introspection capability mentioned above.

If the gateway has the ability to customize the header information sent in the introspection request to the Curity Identity Server, the Accept header with the value application/jwt can be used. This will make the gateway obtain a JWT directly in the introspection response. If it is not possible to modify the header information, the Curity Identity Server can be customized to respond with a JWT by modifying the token procedure. Details on how to configure this is outlined in the OAuth Introspection and Phantom Tokens article.

Plugin Example

The Lua Phantom Token plugin repo shows how to implement the pattern using the high-level LUA programming language. This example is used with the Kong and NGINX gateways and the code could be adapted to other programming languages.

Conclusion

In general, any API gateway should be possible to integrate with the Curity Identity Server using the Phantom Token Pattern. Some will have introspection capabilities out of the box, and some might require some kind of plugin or extension.

The details of the OAuth Introspection and Phantom Tokens is a useful read before trying to integrate the Phantom Token Pattern with any API gateway.