Security
Last updated
Was this helpful?
master
Last updated
Was this helpful?
Security-related documentation in Swagger is described in and
Standard Swagger features in combination with some extensions can be used to configure security checks about JWT tokens which are expected to be sent with a client request. If the JWT token is valid, it is stored in a , which can then be used in the .
x-flat-jwt fieldThe x-flat-jwt field references an object with fields describing the expected JWT token:
key - REQUIRED. The key to decode the JSON Web Signature (JWS). This can either be specified with a value, or by referencing a file (file) or an environment variable (env).
alg - The signing algorithm the JWS is expected to be created with. This can either be specified with a value, or by referencing a file (file) or an environment variable (env). See the for more information.
out-var - The name of the variable in which the JWT is stored (must be a proper variable name, starting with $; default: "$jwt").
out-header - The name of an HTTP request header that shall carry the JWT in upstream requests.
claims - An object with claims the JWT payload is expected to contain. The field names are the claim names, the expected claim value is specified either with a value, or by referencing a file (file) or an environment variable (env).
scope-claim - The name of the claim, storing the scope of the token (string; default: scope). The claim value must either be
a string containing a whitespace-separated list of scopes ("scope1 scope2 scope3") or
an array with a string entry for each scope (["scope1", "scope2", "scope3"]).
post-check-flow - The path to a flow executed after the JWT is checked and found valid. In this flow, e.g. additional checks can be implemented (use the to throw errors).
The token is considered valid if all of the following are true:
the JWS can be decoded,
the JWS has a proper JWT,
the JWT is not expired,
the JWT contains the expected claims, if any are configured,
the scope of the token contains all required scopes as specified in the security requirement,
the JWT can be stored in a variable.
$jwt or the alternative variable specified in out-var and the header specified in out-header will be unset if the token is not valid.
Authorization HeaderThe code in this example defines a security scheme named JWTHeaderAuth. The token is expected to be a bearer token in the Authorization header. The key is read from a file named secret.pem relative to the swagger.yaml. The signing algorithm is read from the FLAT_JWT_ALG environment variable. The JWT will be stored in the $header_token variable. The scope of the token is specified in a permission claim. The JWT payload is expected to contain an aud claim with a value read from the FLAT_JWT_AUDIENCE environment variable.
If the request does not contain an Authorization header with the proper bearer structure, or the token is invalid, this security scheme will fail.
In this example the key is read from the FLAT_COOKIE_SECRET environment variable. The JWT signing algorithm is unspecified – it defaults to HS256. The JWT will be stored in $cookie_token. No claims are expected.
If the request does not contain a Cookie header with an authtoken cookie, or the token is invalid, this security scheme will fail.
Swagger allows for combinations of security schemes to be applied to API endpoints. If security schemes are specified as alternatives, at least one alternative must not fail. In the following example, a GET request to /foo must satisfy at least one of the security schemes named JWTHeaderAuth and JWTCookieAuth.
In Swagger, security schemes can be specified at the top level (default security) or for specific operations. With FLAT, you can also specify a security scheme for a specific path (default security for all operations on the path).
In the following example, a GET request to /foo must satisfy the security scheme named JWTHeaderAuth, a POST request to /foo must satisfy the security scheme named JWTHeaderAuth and the token must have both write:foo and read:bar scopes, while e.g. a DELETE or PUT request to /foo must satisfy the security scheme named JWTCookieAuth. All other requests must satisfy either the JWTHeaderAuth or JWTCookieAuth security schemes.
Note: While in Swagger 2.0, specifying scopes in security requirements is limited to OAuth2 security definitions, FLAT has no such limitation.
check-cookie-jwt.xml (checking whether the value of the pid JWT claim equals the p request path parameter):
If we assume the value of $jwt being {"id":42,"name":"John Doe"}, the resulting upstream request URL would be https://httpbin.org/get?id=42&name=John%20Doe and the request would include a Token header: Token: {"id":42,"name":"John Doe"}.
To just forward the received JWT token upstream as a header, you can also specify the desired header name with the out-header property of x-flat-jwt:
The headers section in proxy-request is then no longer needed:
Use a with type: apiKey, in: header and name: Authorization if the JWT is expected to be sent as a bearer token in an Authorization header; e.g.:
Use a with type: apiKey, in: header, name: Cookie and x-flat-cookiename: <name> if the JWT is expected to be sent as a cookie value; e.g.:
If a request does not pass the security check, it is rejected with status code 403 and error code 3206, and the is run, if configured.
The security check is performed after .
The claims of an incoming JWT are stored in $jwt – or in the global that you specify in the out-var property of x-flat-jwt. In a or action you can send these claims upstream, for example using a query parameter or a header:
Moreover, if you just want to proxy requests, there's no need to define a and you can simply set up your requests using :
(cookbook)