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.:

swagger: "2.0"
basePath: /
securityDefinitions:
  JWTCookie:
    type: apiKey
    in: header
    name: Cookie
paths:
  /httpbin/**:
    security:
      - JWTCookie: []

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:

…
securityDefinitions:
  JWTCookie:
    type: apiKey
    in: header
    name: Cookie
    x-flat-cookiename: authtoken    # ⬅ specify the cookie name
…

Then we specify the configuration for decoding the JWT token:

…
  JWTCookie:
    type: apiKey
    in: header
    name: Cookie
    x-flat-cookiename: authtoken
    x-flat-jwt:                     # ⬅ our JWT configuration:
      key:                          # ⬅ the key to decode the JWT …
        file: pubkey.pem            # ⬅ … is read from the file pubkey.pem
      alg: RS256                    # ⬅ the signing algorithm is RS256
…

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

-----BEGIN PUBLIC KEY-----
MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDGSd+sSTss2uOuVJKpumpFAaml
t1CWLMTAZNAabF71Ur0P6u833RhAIjXDSA/QeVitzvqvCZpNtbOJVegaREqLMJqv
FOUkFdLNRP3f9XjYFFvubo09tcjX6oGEREKDqLG2MfZ2Z8LVzuJc6SwZMgVFk/63
rdAOci3W9u3zOSGj4QIDAQAB
-----END PUBLIC KEY-----

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:

eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJzb21lX3VzZXIiLCJpc3MiOiJzb21lX3Byb3ZpZGVyIiwiZXhwIjoxNTkwNDkxNTI4fQ.lJnUpBzMx84_5yigeHeLw4f8sbdSdu_7fWr1--t7EAp8v8K-kSmVYUGnR0Jx4o_ZE84N2M72Kn1pKssrzgTHsFi7txcZHHz_JqgnPgKqsZwjrmWDC-XVvdrSXjAsPO6wn0qy3KEMT1y6Z8YQA4ZyzA1dDsRRIUFiNrgF6_b5pC4

eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJzb21lX3VzZXIiLCJpc3MiOiJzb21lX3Byb3ZpZGVyIn0.bNXv28XmnFBjirPbCzBqyfpqHKo6PpoFORHsQ-80IJLi3IhBh1y0pFR0wm-2hiz_F7PkGQLTsnFiSXxCt1DZvMstbQeklZIh7O3tQGJyCAi-HRVASHKKYqZ_-eqQQhNr8Ex00qqJWD9BsWVJr7Q526Gua7ghcttmVgTYrfSNDzU

Let's give it a try:

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

{
  "error": {
    "message": "Security violation",
    "status": 403,
    "requestID": "Xsz@QAv8CEBZfWbmQhKLIQAAAII",
    "info": [
      "JWT Security (JWTCookie): No Cookie header sent"
    ],
    "code": 3206
  }
}

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:

$ curl -i -H "Cookie: authtoken=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJzb21lX3VzZXIiLCJpc3MiOiJzb21lX3Byb3ZpZGVyIiwiZXhwIjoxNTkwNDkxNTI4fQ.lJnUpBzMx84_5yigeHeLw4f8sbdSdu_7fWr1--t7EAp8v8K-kSmVYUGnR0Jx4o_ZE84N2M72Kn1pKssrzgTHsFi7txcZHHz_JqgnPgKqsZwjrmWDC-XVvdrSXjAsPO6wn0qy3KEMT1y6Z8YQA4ZyzA1dDsRRIUFiNrgF6_b5pC4" http://localhost:8080/httpbin/anything
HTTP/1.1 403 Forbidden
…
Content-Type: application/json

{
  "error": {
    "message": "Security violation",
    "status": 403,
    "requestID": "Xsz80Av8CEBZfWbmQhKLIAAAAIE",
    "info": [
      "JWT Security (JWTCookie): Invalid JWT: Token has expired."
    ],
    "code": 3206
  }
}

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

OK, let's use the other token:

$ curl -i -H "Cookie: authtoken=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJzb21lX3VzZXIiLCJpc3MiOiJzb21lX3Byb3ZpZGVyIn0.bNXv28XmnFBjirPbCzBqyfpqHKo6PpoFORHsQ-80IJLi3IhBh1y0pFR0wm-2hiz_F7PkGQLTsnFiSXxCt1DZvMstbQeklZIh7O3tQGJyCAi-HRVASHKKYqZ_-eqQQhNr8Ex00qqJWD9BsWVJr7Q526Gua7ghcttmVgTYrfSNDzU" 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"
}

Tada!

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

…
securityDefinitions:
  JWTBearer:
    type: apiKey
    in: header
    name: Authorization             # ⬅
    x-flat-jwt:
      key:
        file: pubkey.pem
      alg: RS256
paths:
  /httpbin/**:
    security:
      - JWTBearer: []

You can try that with

$ curl -i -H "Authorization: Bearer eybGciOiJSUzI1NiJ9.eyJzdWIiOiJzb21lX3VzZXIiLCJpc3MiOiJzb21lX3Byb3ZpZGVyIn0.bNXv28XmnFBjirPbCzBqyfpqHKo6PpoFORHsQ-80IJLi3IhBh1y0pFR0wm-2hiz_F7PkGQLTsnFiSXxCt1DZvMstbQeklZIh7O3tQGJyCAi-HRVASHKKYqZ_-eqQQhNr8Ex00qqJWD9BsWVJr7Q526Gua7ghcttmVgTYrfSNDzU" http://localhost:8080/httpbin/anything

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:

…
    x-flat-jwt:
      key:
        file: pubkey.pem
      alg: RS256
      out-header: JWT               # ⬅ the name of the request header with the JWT claims
…

$ curl -i -H "Cookie: authtoken=eybGciOiJSUzI1NiJ9.eyJzdWIiOiJzb21lX3VzZXIiLCJpc3MiOiJzb21lX3Byb3ZpZGVyIn0.bNXv28XmnFBjirPbCzBqyfpqHKo6PpoFORHsQ-80IJLi3IhBh1y0pFR0wm-2hiz_F7PkGQLTsnFiSXxCt1DZvMstbQeklZIh7O3tQGJyCAi-HRVASHKKYqZ_-eqQQhNr8Ex00qqJWD9BsWVJr7Q526Gua7ghcttmVgTYrfSNDzU" http://localhost:8080/httpbin/anything
HTTP/1.1 200 OK
…
Content-Type: application/json

{
…
  "headers": {
…
    "Jwt": "{\"sub\":\"some_user\",\"iss\":\"some_provider\"}",
…
  },
…
}

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.

…
    x-flat-jwt:
      key:
        file: pubkey.pem
      alg: RS256
      out-header: JWT
      out-var: $the_claims          # ⬅
…

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

swagger: "2.0"
…
x-flat-init: init.xml
paths:
…

with init.xml:

<flow>
  <log>
  {
    "JWT-Claims": {{ $the_claims }}
  }
  </log>
</flow>

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

{…,"type":"flat_access",…,"JWT-Claims":{"sub":"some_user","iss":"some_provider"}}

Here you see the two claims from the JWT token.

All files together

swagger.yaml:

swagger: "2.0"
basePath: /
securityDefinitions:
  JWTCookie:
    type: apiKey
    in: header
    name: Cookie
    x-flat-cookiename: authtoken
    x-flat-jwt:
      key:
        file: pubkey.pem
      alg: RS256
      out-var: $the_claims
      out-header: JWT
x-flat-init: init.xml
paths:
  /httpbin/**:
    security:
      - JWTCookie: []
    x-flat-proxy:
      origin: https://httpbin.org
      stripEndpoint: true

pubkey.pem:

-----BEGIN PUBLIC KEY-----
MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDGSd+sSTss2uOuVJKpumpFAaml
t1CWLMTAZNAabF71Ur0P6u833RhAIjXDSA/QeVitzvqvCZpNtbOJVegaREqLMJqv
FOUkFdLNRP3f9XjYFFvubo09tcjX6oGEREKDqLG2MfZ2Z8LVzuJc6SwZMgVFk/63
rdAOci3W9u3zOSGj4QIDAQAB
-----END PUBLIC KEY-----

init.xml:

<flow>
  <log>
  {
    "JWT-Claims": {{ $the_claims }}
  }
  </log>
</flow>

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

• FLAT Security (reference)
• Routing: Init Flow and FLAT Proxies (reference)
• Encoding and Decoding JWT (cookbook)