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.orgstripEndpoint: true
Sending a request to FLAT running on localhost port 8080 results in:
$ curl -i http://localhost:8080/httpbin/anythingHTTP/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?
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: apiKeyin: headername: Cookiepaths:/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: apiKeyin: headername: Cookiex-flat-cookiename: authtoken # ⬅ specify the cookie name…
Then we specify the configuration for decoding the JWT token:
…JWTCookie:type: apiKeyin: headername: Cookiex-flat-cookiename: authtokenx-flat-jwt: # ⬅ our JWT configuration:key: # ⬅ the key to decode the JWT …file: pubkey.pem # ⬅ … is read from the file pubkey.pemalg: 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+sSTss2uOuVJKpumpFAamlt1CWLMTAZNAabF71Ur0P6u833RhAIjXDSA/QeVitzvqvCZpNtbOJVegaREqLMJqvFOUkFdLNRP3f9XjYFFvubo09tcjX6oGEREKDqLG2MfZ2Z8LVzuJc6SwZMgVFk/63rdAOci3W9u3zOSGj4QIDAQAB-----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/anythingHTTP/1.1 403 Forbidden…Content-Type: application/json{"error": {"message": "Security violation","status": 403,"requestID": "[email protected]","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/anythingHTTP/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/anythingHTTP/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: apiKeyin: headername: Authorization # ⬅x-flat-jwt:key:file: pubkey.pemalg: RS256paths:/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
.
With out-header
you can send the whole set of claims from the JWT upstream:
…x-flat-jwt:key:file: pubkey.pemalg: RS256out-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/anythingHTTP/1.1 200 OK…Content-Type: application/json{…"headers": {…"Jwt": "{\"sub\":\"some_user\",\"iss\":\"some_provider\"}",…},…}
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.pemalg: RS256out-header: JWTout-var: $the_claims # ⬅…
We can log the claims by adding a log
action to an init flow:
swagger: "2.0"…x-flat-init: init.xmlpaths:…
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.
swagger.yaml:
swagger: "2.0"basePath: /securityDefinitions:JWTCookie:type: apiKeyin: headername: Cookiex-flat-cookiename: authtokenx-flat-jwt:key:file: pubkey.pemalg: RS256out-var: $the_claimsout-header: JWTx-flat-init: init.xmlpaths:/httpbin/**:security:- JWTCookie: []x-flat-proxy:origin: https://httpbin.orgstripEndpoint: true
pubkey.pem:
-----BEGIN PUBLIC KEY-----MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDGSd+sSTss2uOuVJKpumpFAamlt1CWLMTAZNAabF71Ur0P6u833RhAIjXDSA/QeVitzvqvCZpNtbOJVegaREqLMJqvFOUkFdLNRP3f9XjYFFvubo09tcjX6oGEREKDqLG2MfZ2Z8LVzuJc6SwZMgVFk/63rdAOci3W9u3zOSGj4QIDAQAB-----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.
FLAT Security (reference)
Routing: Init Flow and FLAT Proxies (reference)
Encoding and Decoding JWT (cookbook)