CouperSevenval TechnologiesDocker ImageGithub

Protecting Access using JWT Tokens

Imagine you had a proxy to an API, e.g. httpbin.org.

swagger.yml:

swagger: "2.0"
basePath: /
paths:
  /httpbin/**:
    x-flat-proxy:
      origin: https://httpbin.org
      stripEndpoint: true

Sending a request to FLAT running on localhost port 8080 results in:

$ curl -i http://localhost:8080/httpbin/anything
HTTP/1.1 200 OK
…
Content-Type: application/json

{
  "args": {},
  "data": "",
  "files": {},
  "form": {},
  "headers": {
    "Accept": "*/*",
    "Accept-Encoding": "deflate, gzip",
    "Host": "httpbin.org",
    "User-Agent": "curl/7.29.0",
    "X-Amzn-Trace-Id": "…"
  },
  "json": null,
  "method": "GET",
  "origin": "…",
  "url": "https://httpbin.org/anything"
}

That's what you would expect from httpbin.org, right?

Restricting access: Swagger Security and x-flat-jwt

Now, you don't want anyone except authorized users to use this proxy. This is typically achieved with access tokens. Some tokens are JSON Web Tokens (JWT), while others are opaque.

Swagger has a two-part feature to describe protected access to routes: securityDefinitions (what sort of protection is applied …) and security (… to which routes), e.g.:

This defines a security scheme object (named JWTCookie), meaning that some sort of cookie is needed to access certain routes. This is applied to the wildcard path /httpbin/**.

This documentation feature, with some extensions, is used to make FLAT actually permit access to the route only if a valid JWT token is presented.

First, we define the name of the cookie expected to accompany the API request:

Then we specify the configuration for decoding the JWT token:

The specified key is a public key, read from the file pubkey.pem, e.g.:

That's all. Now FLAT will only permit requests if they supply a token that bear an RS256 signature that was created with the private key that matches the given public key.

Usually, you would get the key and algorithm from your identity provider (e.g. an OAuth2 authorization server). That service would be responsible for issuing JWT tokens for your users.

For this tutorial we have prepared a couple of JWT tokens for you to try out different situations:

Let's give it a try:

Ah, yes, we forgot to present a token in the authtoken cookie. But we see, that the protection works.

Let's try again with the first token:

Hmm, expired. So this one is too old. (Access tokens typically have a restricted period of use.)

OK, let's use the other token:

Tada!

By the way, apart from cookies, this also works similarly with the Authorization: Bearer … header:

You can try that with

But there are two additional features that can be quite handy: out-header and out-var.

Sending JWT claims upstream: out-header

With out-header you can send the whole set of claims from the JWT upstream:

Accessing JWT claims: out-var

With out-var you can specify the name of a variable where FLAT will store the JSON claims encoded in the JWT, in order to make them available for further processing. E.g.

We can log the claims by adding a log action to an init flow:

with init.xml:

If you look at the FLAT logs and try again with a valid token, you'll notice:

Here you see the two claims from the JWT token.

All files together

swagger.yaml:

pubkey.pem:

init.xml:

If you want to know, how to perform some additional checks on the JWT, visit the cookbook Performing Additional Checks on JWT Access Tokens.

See also

PreviousProcessing Upstream ResponsesNextReference

Last updated

Was this helpful?