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

meme

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

Magic!

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!