Category: Middleware

Integrating Tyk Open Source API Gateway with a Custom Identity Provider using JSON Web Tokens

That’s quite a mouthful. But hey, you know what a lot of users want to do? Use their own Identity Provider, and the new hotness is JSON Web Tokens. For those who don’t know what they are, they’re pretty friggin’ cool – find out all about ’em here. We’re going to use them to do some cool trickery/magicky API Gateway token gen without even having to generate a token


But seriously, it’s pretty cool – in short: you can have a custom Identity Provider (IDP) generate JSON Web Tokens for you, and then use those tokens directly with Tyk, instantly – better yet, the underlying identity of the token (it’s owner) is tracked across JWTs, that means they can log in elsewhere, or via a different app or portal and still get the same rate limits provided (or different ones, it’s all up to your IDP, not us!).

So how does Tyk Magically do this? Well, the process is pretty involved, so we thought we’d talk you through it:

Centralised secrets and virtual tokens

With centralised secrets, we do not create any tokens at all within Tyk, instead all tokens are generated externally. Centralised secrets involves storing a shared secret (HMAC or RSA) at the API Definition level, this secret is then used to validate all inbound requests, and applies access rules based on specific fields that can be added to the claims section of the JWT to manage the underlying identity’s access to managed APIs.

To use this option, we do not generate a token at all, instead we go to the API Designer, and under the JWT Shared secret section (when selecting the JWT security handler), we add the shared secret (recommended is a public key)

First, let’s set things up:

  1. In the API Designer, we select “JSON web Token” as the authentication mode
  2. Select RSA as the signing method
  3. Add a secret (public key)
  4. Set identity source to be “sub” – this tells tyk which claim in the JWT to use as the base “identity” of the JWT, i.e. the bearer (this might be a username, or an email address, or even a user ID), a common JWT claim is “email”, we could use that too
  5. Set the policy field name to be “policy” – this tells tyk which claim in the JWT to use to identify the policy to apply to this identity, as in: the access control, quota and rate limiting settings to apply to this identity
  6. Save this thing, it will now go live onto your gateway

Now lets create an actual policy:

  1. In our Policies section, we create a new policy called “JWT Test”
  2. Set the quota and rate limit rules, most importantly, we grant access to the API we just created

Let’s say when we save this policy, the ID returned is 1234567

So, let’s walk through a user flow:

  1. A user goes to a third-party login portal and authenticates themselves
  2. This third-party system generates a JWT using it’s private key, and in this JWT adds the following claims:
    • policy: 1234567
    • sub: the user’s email address
  3. The user is then granted this JWT (maybe as a fragment in the URL) and uses it to access the API we created earlier
  4. Access is magically granted!

Tyk will now validate this request as follows:

  1. It extracts the JWT from the request and validates it against the stored JWT that we added at the API level in step 1.2
  2. If the token is valid, it looks for the identity source field, since this is configured as “sub”, it finds the user’s email address
  3. It uses the email address to generate a hash of the address, and then creates a new value of {org-id}{hash(sub)} – basically it generates an internal token that is bound to the identity (it will be regenerated each time this sub shows up)
  4. Tyk extracts the policy ID from the claims and retrieves this from memory (if it exists)
  5. Tyk now tries to find this internal token hash in it’s key store – if it exists, it applies the policy to the key (this does not override existing values, it just sets the maximums so that they have an immediate effect if changed), access control rules are overridden too, so they can be changed depending on the access source or IDP doing the logging in
  6. If the internal token does not exist, Tyk creates the token based on the policy data – same as earlier but with a new identity-based token
  7. When the token is created, the internal token ID is added to the metadata of the session as a new field: TykJWTSessionID (This is important, because now you can reference this meta data object in the transforms middleware, for example, you could inject it as a custom header into the outbound request, so your upstream application has access to the original JWT and the internal Tyk Session token in case it needs to invalidate or track a specific user’s behaviour – aren’t we gosh darn helpful). Now since these session IDs do not change, they exist across JWT’s for this identity
  8. This internal token is now used to represent the request throughout the Tyk request chain – so now the access control, rate limiting and quota middleware will act on this token as if it were a real key – but it leaves the actual JWT intact in the request so it can be processed upstream
  9. If the access rules set by the policy referenced in the JWT’s policy field are all valid, the request is allowed to pass through upstream

Phew! That’s a lot of steps, but it means that you can handle access control in your IDP with a single added claim.

Anyway, we thought it was interesting – we hope you did too!

Creating an IP-based rate-limiter with Tyk and JavaScript middleware

We’ve recently had a user ask if it was possible to have Tyk act as a rate limiter based on IP address instead of by token, this isn’t possible out of the box, but it is with our Middleware API and some simple JS So, you may ask yourself how we achieve this feat?

It’s actually really straightforward. First off, we’ll need to set up our API in a very specific way, we’ll use a file-based definition here as we’re assuming this is a simple deployment of Tyk. The way we will do this is by creating a custom JS middleware function that will run before any other Tyk processing takes place, this includes all rate limiting. The middleware will:

  1. Catch the request
  2. Extract the IP address from the header
  3. Create a key based on the IP address with a specific rate limit
  4. Inject the IP address as the authorization header for Tyk to use

This means that rate limits are on a per-IP basis, which is great, and also means that Tyk can just work through the request normally once the middleware processing is done.

We will start off by defining our API appropriately, we basically want an API that will invoke the middleware as a pre-processor, and then also ensure that any keys that are created do not last forever. The Tyk API Definition will look something like this:

    "name": "Tyk Test API",
    "slug": "test-name",
    "api_id": "ip-ratelimit-api",
    "org_id": "1",
    "use_keyless": false,
    "use_oauth2": false,
    "auth": {
        "auth_header_name": "x-tyk-authorization"
    "definition": {
        "location": "header",
        "key": "version"
    "version_data": {
        not_versioned: true,
        versions: {
            "Default": {
                "name": "Default",
                "expires": "3011-02-02 00:00",
                "use_extended_paths": true,
                "extended_paths": {}
    "proxy": {
        "listen_path": "/b605a6f03cc14f8b74665452c263bf19/",
        "target_url": "",
        "strip_listen_path": true
    "custom_middleware": {
        "pre": [
                "name": "ipRateLimiter",
                "path": "middleware/ipRateLimiter.js",
                "require_session": false
    "session_lifetime": 172800,
    "active": true

The key things of note here are the `custom_middleware` section, here we’ve defined where to find our files and what the objects are called. Next up is the `session_lifetime` value, this sets a default key lifetime for every key created on this API, in this case we’ve set it to 48 hours. Now that we are ready with the actual API, we can set up the middleware, it’s actually quite short – this is the entire IP rate limiter:

    // ---- A Middleware based IP Rate limiter -----
var ipRateLimiter = new TykJS.TykMiddleware.NewMiddleware({});

ipRateLimiter.NewProcessRequest(function(request) {
    // Get the IP address
    var thisIP = request.Headers["X-Real-Ip"][0];

    // Set auth header
    request.SetHeaders["x-tyk-authorization"] = thisIP;

    var keyDetails = {
        "allowance": 100,
        "rate": 100,
        "per": 1,
        "expires": 0,
        "quota_max": 100,
        "quota_renews": 1406121006,
        "quota_remaining": 100,
        "quota_renewal_rate": 60,
        "access_rights": {
            "ip-ratelimit-api": {
                "api_name": "Test API",
                "api_id": "ip-ratelimit-api",
                "versions": [
        "org_id": "53ac07777cbb8c2d53000002"

    TykSetKeyData(thisIP, JSON.stringify(keyDetails), 1)

    return ipRateLimiter.ReturnData(request);

// Ensure init with a post-declaration log message
log("IP rate limiter JS initialised");

The above code should go into a file called `ipRateLimiter.js` in the `middleware/` folder of your Tyk installation. If you start Tyk now, the IP rate limiter will be in place.

What is actually going on here? It’s exactly as we said above, we extract the IP address, here we are assuming that `”X-Real-Ip”` is a real header, since we are using NGinX to manage our domain, we have set a rule in the server block to make sure that the IP address is included as a header on each request:

location / {
    rewrite /(.*) /b605a6f03cc14f8b74665452c263bf19/$1 break;

    proxy_pass_header Server;
    proxy_set_header Host $http_host;
    proxy_redirect off;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Scheme $scheme;
    proxy_pass http://tyk;

The thing of note here is `proxy_set_header X-Real-IP $remote_addr;`, this is important, as otherwise you won’t have access tot he IP address from the header. Once we have the IP address, we set this as the authorisation header for the request.

In the next section we have a template for a session object, here we are setting the rate limits manually, we could also use a policy file to do this and just attach the policy ID.

In this case we have set the rate limit to 100 requests per second with an overall quota of 100 per minute. We now use the built-in method `TykSetKeyData` to create the key, notice the last input to this function is `1`, this forces Tyk to not reset the quota for this transaction, which is the default behaviour – we don’t want Tyk re-setting the quotas and rate limiters every time the IP shows up, we just want to ensure the key is present.

When the middleware completes, Tyk processes the now-modified request as if it had an authorisation token (in this case the IP address) and the rate limits are enforced. And that’s it, this key will last for 48 hours, at which point it will be re-created. This means that your Redis instance won’t get flooded with infinite IP addresses as traffic grows. Enjoy!

Scroll to top