Integrating With Tyk Self-Managed Using the Phantom Token Pattern

Tyk Self-Managed offers a plethora of options when it comes to extending the capability of the API gateway. A powerful option is to use a so-called rich plugin. This approach allows the plugin to be written in any language that supports gRPC. The plugin is deployed as a separate service and can be invoked by Tyk during different phases of both the request and response flows.

Plugin Overview

The plugin is comprised of 2 separate services, a plugin bundle and the actual plugin service itself. The plugin bundle is a signed manifest exposed as phantom-bundle.zip that tells Tyk how to wire in the plugin service. It defines that the plugin driver is gRPC and which hooks should be executed, e.g. where in the request/response flow of Tyk the plugin should be invoked. The plugin service implements the actual logic of the plugin, in this case the phantom token pattern.

Configure the Curity Identity Server

The Curity Identity Server needs to be set up to handle introspection. This is the case by default but review the configuration of the system in use before continuing and make sure you have a Client configured for introspection.

This article assumes that the Curity Identity Server is set up to handle the application/jwt approach of introspection as outlined in the OAuth Introspection and Phantom Tokens article.

Build and Run the Plugin

The plugin is available as a Docker compose project and is easy to get running:

1. Clone the repository linked at the top of this tutorial
2. Set the .env variables needed (Introspection URL, client_id and client_secret)
3. Build and run the docker compose project by executing:

docker compose up -d --build

This starts the 2 services described above, bundle-server and phantom-plugin.

Configure Tyk Self-Managed

If you don't have an installation of Tyk Self-Managed up and running already, refer to the Tyk Quick Start Guide to get going.

Tyk Configuration

You need to configure the Tyk Gateway to allow the use of gRPC plugins and define the location of the plugin bundle. You configure this in the tyk.conf file. The configuration might look similar to this:

{
  "listen_port": 8080,
  "secret": "352d20ee67be67f6340b4c0605b044b7",

  "enable_coprocess": true,
  "coprocess_options": {
    "enable_coprocess": true,
    "coprocess_grpc_server": "tcp://phantom-plugin:50051"
  },

  "enable_bundle_downloader": true,
  "bundle_base_url": "http://bundle-server/",

  "use_db_app_configs": true,
  "db_app_conf_options": {
    "connection_string": "http://tyk-dashboard:3000",
    "node_is_segmented": false,
    "enable_app_key_hashing": false,
    "use_app_id_as_key": true
  },

  "storage": { "type": "redis", "host": "tyk-redis", "port": 6379 },
  "log_level": "debug"
}

Tyk Dashboard

Configure the API in Tyk to:

• Enable Authentication
• Set the type to Custom Plugin
• Set the Authentication token location to Authorization header
• Leave the Enable plugin Config Off.

Scroll down to the Plugin configuration section:

• Make sure Config data is Off
• Set the Plugin driver to gRPC
• Enable Plugin bundle
• Set the Bundle filename to phantom-bundle.zip. The is the file that the bundle service exposes to the Tyk gateway

Test Using OAuth Tools

1. In OAuth Tools, create a flow to obtain an Access Token. Review the Test using OAuth Tools article for more details.
2. Create a Call External API flow. Enter the URL of the API exposed by the Tyk Self Managed API gateway. Configure the method according to what’s possible with the API. Select the token retrieved in the previous step from the drop-down list and click Send.

The opaque access token is sent in the API request to Tyk. In the screenshot above the backend API is Httpbin which echoes back the request details it receives. So even though the opaque token was sent in the Authorization header, a JWT was echoed back showing that the backend API does get the JWT.

Access Token Expiry

When you use the phantom token plugin, access token expiry responses can originate either from upstream APIs or the plugin itself. In either case, clients receive an HTTP 401 response and can deal with that condition resiliently. Typically, the client runs a token refresh operation and retries the API request with a new access token. To ensure the correct expiry response, the plugin returns statusCode: 401 and the gateway configuration captures that and returns the same status code.

Resources

Useful resources that cover the topics of this article.

• An article on OAuth Introspection and Phantom Tokens
• Tyk Self Managed Overview
• Tyk Self Managed Quick Start Guide
• gRPC

Join our Newsletter

Get the latest on identity management, API Security and authentication straight to your inbox.

Email

Subscribe

I agree to Curity's Privacy Policy

Start Free Trial

Try the Curity Identity Server for Free. Get up and running in 10 minutes.

Start Free Trial