Configuring Plugins for Tyk OAS APIs

An API can be configured so that one or more of its associated plugins can execute at different phases of the request / response life cycle. Each plugin configuration serves to identify the plugin source file path and the name of the corresponding function, triggered at each request / response lifecycle stage.

This guide explains how to configure plugins for Tyk OAS APIs within the Tyk OAS API definition or via the API designer in Tyk Dashboard.

If you’re using the legacy Tyk Classic APIs, then check out the Tyk Classic page.

Configuring plugins in the Tyk OAS API Definition

The x-tyk-api-gateway.middleware.global section is used to configure plugins in a Tyk OAS API. It contains a pluginConfig section and a list of plugins for each phase of the API request / response lifecycle.

The pluginConfig section contains the driver parameter that is used to configure the plugin implementation language:

"pluginConfig": {
  "driver": "goplugin"
}

Within the x-tyk-api-gateway.middleware.global section, keyed lists of plugins can be configured for each phase of the API request / response lifecycle described in the table below:

Each plugin configuration can have the following fields configured:

• enabled: When true, enables the plugin.
• functionName: The name of the function that implements the plugin within the source file.
• path: The path to the plugin source file.
• rawBodyOnly: When true, indicates that only the raw body should be processed.
• requireSession: When true, indicates that session metadata will be available to the plugin. This is applicable only for post, post authentication and response plugins.

For example a Post Authentication plugin would be configured within a postAuthenticationPlugins list as shown below:

"postAuthenticationPlugins": [
  {
    "enabled": true,
    "functionName": "post_authentication_func",
    "path": "/path/to/plugin1.so",
    "rawBodyOnly": true,
    "requireSession": true
  }
]

An full example is given below to illustrate how to set up plugins for different phases of the request / response lifecycle:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55

{
  "x-tyk-api-gateway": {
    "info": {
      "dbId": "667962397f6de50001508ac4",
      "id": "b4d8ac6e5a274d7c7959d069b47dc206",
      "orgId": "6672f4377f6de50001508abf",
      "name": "OAS APIs Plugins",
      "state": {
        "active": true,
        "internal": false
      }
    },
    "middleware": {
      "global": {
        "pluginConfig": {
          "driver": "goplugin"
        },
        "postAuthenticationPlugins": [
          {
            "enabled": true,
            "functionName": "post_authentication_func",
            "path": "/path/to/plugin1.so",
            "rawBodyOnly": true,
            "requireSession": true
          }
        ],
        "postPlugins": [
          {
            "enabled": true,
            "functionName": "postplugin",
            "path": "/path/to/plugin1.so",
            "rawBodyOnly": true,
            "requireSession": true
          }
        ],
        "prePlugins": [
          {
            "enabled": true,
            "functionName": "pre-plugin",
            "path": "/path/to/plugin1.so"
          }
        ],
        "responsePlugins": [
          {
            "enabled": true,
            "functionName": "Response",
            "path": "/path/to/plugin1.so",
            "rawBodyOnly": true,
            "requireSession": true
          }
        ]
      }
    }
  }
}

In this example we can see that the plugin driver has been configured by setting the driver field to goplugin within the pluginConfig object. This configuration instructs Tyk Gateway that our plugins are implemented using Golang.

We can also see that the following type of plugins are configured:

• Pre: A plugin is configured within the prePlugins list. The plugin is enabled and implemented by function pre-plugin within the source file located at path /path/to/plugin1.so.
• Post Authentication: A plugin is configured within the postAuthenticationPlugins list. The plugin is enabled and implemented by function post_authentication_func within the source file located at path /path/to/plugin1.so. The raw request body and session metadata is available to the plugin.
• Post: A plugin is configured within the responsePlugins list. The plugin is enabled and implemented by function postplugin within the source file located at path /path/to/plugin1.so. The raw request body and session metadata is available to the plugin.
• Response: A plugin is configured within the postPlugins list. The plugin is enabled and implemented by function Response within the source file located at path /path/to/plugin1.so. The raw request body and session metadata is available to the plugin.

The configuration above is a complete and valid Tyk OAS API Definition that you can use as a basis for trying out custom plugins. You will need to update the driver parameter to reflect the target language type of your plugins. You will also need to update the path and functionName parameters for each plugin to reflect the source code.

Configuring plugins in the API Designer

Select your API from the list of Created APIs to reach the API designer and then follow these steps:

Step 1: Configure plugin type and custom data

In the Plugins Configuration section, select the Plugin Driver, which tells Tyk which type of plugin to expect: Go, gRPC, JavaScript (OTTO), Lua or Python.

You can configure custom data that will be made available to your plugin function as a JSON formatted object in the Config Data option.

Step 2: Configure the custom plugins

For each plugin that you wish to register with the API, click on the Add Plugin button to display a plugin configuration section:

Complete the following fields:

• Function Name: Enter the name of the function within your plugin code that Tyk should invoke.
• Path: Enter the path to the source file that contains the function that implements your plugin.
• Raw Body Only: Optionally, toggle the Raw Body Only switch to true when you do not wish to fill body in request or response object for your plugins.

Step 3: Save the API

Select Save API to apply the changes to your API.