Merge pull request #110 from sevenval/develop

Release 2021-01-07

CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [20210107](https://hub.docker.com/r/sevenvaltechnologies/flatrunner/tags)
+
+### Added
+
+- The [`uuid3()` and `uuid4()` functions](/reference/functions/uuid.md)
+- The [`ldap-query()` function](/reference/functions/ldap-query.md)
+- [LDAP TLS configuration](/reference/configuration.md#ldap-tls-configuration) and [LDAP timeout](/reference/configuration.md#ldap-timeout)
+- The [`scope-claim`](/reference/OpenAPI/security.md#the-x-flat-jwt-field) and [`post-check-flow`](/reference/OpenAPI/security.md#the-x-flat-jwt-field) properties
+- Specifying the [required token scope](/reference/OpenAPI/security.md#applying-security-schemes)
+- [Merging directives into `php.ini`](/administration/configuration.md#php-ini) via environment variables
+
+### Fixed
+
+- [Path parameters](/reference/OpenAPI/routing.md#path-parameters) were not usable in [error flows](/reference/OpenAPI/routing.md#error-flow)
+
+
 ## [20200828](https://hub.docker.com/r/sevenvaltechnologies/flatrunner/tags)
 
 ### Added

administration/configuration.md

@@ -13,6 +13,7 @@ The chapter [Defining Env Vars](/cookbook/envvars.md#defining-env-vars) in the C
 * `FLAT_STATUS_AUTH`: Username and password, separated by a `:` for access to the `php-fpm` and `httpd` status pages. The pages are disabled entirely if `FLAT_STATUS_AUTH` is not set. If enabled, the `httpd` status can be requested via HTTP at `/ServerStatus`, and the php-fpm status at `/FPMStatus?full`.
 * `FLAT_DEBUG_ALLOW_HEADER`: enable [per request debugging](/reference/debugging.md#request-debugging), defaults to `false` unless `FLAT_DEBUG_AUTH` is set.
 * `FLAT_DEBUG_AUTH`: sets a password to protect [per request debugging](/reference/debugging.md#request-debugging).
+* `FIT_FLAT_UID_FORMAT`: use `uuid3` or `uuid4` to switch the format of the `requestID` generated in the logs and the `id` in the DC to UUID version 3 or 4 respectively instead of the Apache httpd unique_id used by default.
 
 ### Request Timeouts
 
@@ -26,6 +27,10 @@ Use the following environment variables to configure the timeouts used during re
 * `FLAT_MAX_TIMEOUT`: Maximum allowed time in seconds for outgoing HTTP requests.
 * `FLAT_MAX_TIMEOUT_PROCESSES`: Specifies how many PHP-FPM processes are allowed to wait for slow sources at any one time. The lower the threshold value, the earlier slow sources will be blocked.
 
+### php.ini
+
+Arbitrary directives can be merged into `php.ini` by setting environment variables starting with `PHP_INI_`. For example, to set `post_max_size = 100M`, just export `PHP_INI_post_max_size=50M` in your shell before starting `flat` CLI. Refer to the [PHP documentation](https://www.php.net/manual/en/ini.list.php) for a list of directives.
+
 ### PHP-FPM
 
 Some parameters used for PHP-FPM process management can be adjusted using environment variables. Refer to the [PHP-FPM documentation](https://www.php.net/manual/en/install.fpm.configuration.php) for more information.

cookbook/README.md

@@ -2,6 +2,8 @@
 
 ## [Protecting Access using JWT Tokens](x-flat-jwt.md)
 
+## [Performing Additional Checks on JWT Access Tokens](checking-jwt-tokens.md)
+
 ## [Proxying Requests to Upstream APIs (Swagger)](proxy-requests.md)
 
 ## [Testing Templates](test-templates.md)

cookbook/checking-jwt-tokens.md

@@ -0,0 +1,264 @@
+# Performing Additional Checks on JWT Access Tokens
+
+Before you start, make sure that you have read the cookbook chapter [Protecting Access using JWT Tokens](x-flat-jwt.md).
+
+Let's start with the following swagger definition:
+
+swagger.yaml:
+
+```yaml
+swagger: "2.0"
+host: my-api.com
+schemes:
+  - https
+basePath: /
+securityDefinitions:
+  JWTCookie:
+    type: apiKey
+    in: header
+    name: Cookie
+    x-flat-cookiename: authtoken
+    x-flat-jwt:
+      key:
+        file: pubkey.pem
+      alg: RS256
+      out-var: $jwt
+security:
+  - JWTCookie: []
+paths:
+  /projects/{p}:
+    x-flat-flow: …
+    get:
+      parameters:
+        - name: p
+          in: path
+          description: The project identifier
+          type: string
+          required: true
+    patch:
+      parameters:
+        - name: p
+          in: path
+          description: The project identifier
+          type: string
+          required: true
+```
+
+The API has one endpoint with a path parameter `p` indicating the project identifier and two operations (`GET` and `PATCH`). The whole API is secured with a security scheme labelled "JWTCookie".
+
+FLAT will make sure that every request to this endpoint
+* has a `Cookie` header
+* with a value for the `authtoken` cookie
+* that is a JWT
+* properly signed and
+* not expired.
+
+In addition to this, FLAT provides features for further checks:
+
+* [Claims](#checking-claims)
+* [Scopes](#checking-scopes)
+* [Post-check flow](#the-post-check-flow)
+
+## Checking Claims
+
+For example, you can ensure that the token was issued by a specific token provider (`iss` claim)
+
+```yaml
+…
+    x-flat-jwt:
+      key:
+        file: pubkey.pem
+      alg: RS256
+      out-var: $jwt
+      claims:
+        iss: "https://trustworthy-token-provider.com"  # ⬅ the mandatory value for the iss claim
+…
+```
+
+and that your API is (one of) the intended audience(s) for the token (`aud` claim)
+
+```yaml
+…
+    x-flat-jwt:
+      key:
+        file: pubkey.pem
+      alg: RS256
+      out-var: $jwt
+      claims:
+        iss: "https://trustworthy-token-provider.com"
+        aud: "https://my-api.com/"    # ⬅ a mandatory value for the aud claim
+…
+```
+
+A JWT with the following claims will pass the test:
+
+```json
+{
+  "iss": "https://trustworthy-token-provider.com",
+  "aud": [ "https://my-api.com/", "https://a-different-api.org/" ],
+  …
+}
+```
+
+while
+
+```json
+{
+  "iss": "https://the-reckless-token-provider.com",
+  "aud": [ "https://my-api.com/", "https://a-different-api.org/" ],
+  …
+}
+```
+or
+```json
+{
+  "iss": "https://trustworthy-token-provider.com",
+  "aud": [ "https://a-different-api.org/" ],
+  …
+}
+```
+will **not** pass.
+
+## Checking Scopes
+
+Let's restrict the use of the `PATCH` operation to specially authorized requests. We can use scopes to achieve this:
+
+```yaml
+…
+    patch:
+      security:
+        - JWTCookie: [ write ]
+      parameters:
+…
+```
+
+FLAT will now look for a scope claim (default claim name is `scope`) with a value of `write`. If the `write` scope is present (possibly along with further scopes, like in `"scope": "read write create"`), the request passes, otherwise it is rejected.
+
+BTW, you can specify another claim name for scopes using the `scope-claim` property of `x-flat-jwt`:
+
+```yaml
+…
+    x-flat-jwt:
+      key:
+        file: pubkey.pem
+      alg: RS256
+      scope-claim: sc    # ⬅ look for scopes in the sc JWT claim
+…
+```
+
+## The post-check flow
+
+Finally, we want to check that a certain non-standard JWT claim `pid` matches the path param `p` (the project identifier).
+
+We use the post-check-flow feature:
+
+```yaml
+…
+    x-flat-jwt:
+      key:
+        file: pubkey.pem
+      …
+      post-check-flow: check-jwt.xml
+…
+```
+with check-jwt.xml:
+```xml
+<flow>
+  <!-- $jwt contains the JWT claims, see the out-var property or x-flat-jwt -->
+  <log>
+  {
+    "token_id": {{ $jwt/pid }},
+    "path_id": {{ $request/params/p }}
+  }
+  </log>
+  <error if="not($jwt/pid) or $jwt/pid != $request/params/p">
+  {
+    "status": 401,
+    "message": "Token is not applicable for this project."
+  }
+  </error>
+</flow>
+```
+
+A JWT with the claim
+
+```json
+{
+  …
+  "pid": "ABC123",
+  …
+}
+```
+will permit access to `https://my-api.com/projects/ABC123`, but **not** to `https://my-api.com/projects/DEF456`.
+
+
+## All files together
+
+swagger.yaml:
+```yaml
+swagger: "2.0"
+host: my-api.com
+schemes:
+  - https
+basePath: /
+securityDefinitions:
+  JWTCookie:
+    type: apiKey
+    in: header
+    name: Cookie
+    x-flat-cookiename: authtoken
+    x-flat-jwt:
+      key:
+        file: pubkey.pem
+      alg: RS256
+      claims:
+        iss: "https://trustworthy-token-provider.com"
+      scope-claim: sc # default: scope
+      out-var: $the_claims
+      out-header: JWT
+      post-check-flow: check-jwt.xml
+security:
+  - JWTCookie: []
+paths:
+  /projects/{p}:
+    x-flat-flow: ...
+    get:
+      parameters:
+        - name: p
+          in: path
+          description: The project identifier
+          type: string
+          required: true
+    patch:
+      security:
+        - JWTCookie: [ write ]
+      parameters:
+        - name: p
+          in: path
+          description: The project identifier
+          type: string
+          required: true
+```
+
+check-jwt.xml:
+```xml
+<flow>
+  <!-- $jwt contains the JWT claims, see the out-var property -->
+  <log>
+  {
+    "token_id": {{ $jwt/pid }},
+    "path_id": {{ $request/params/p }}
+  }
+  </log>
+  <error if="not($jwt/pid) or $jwt/pid != $request/params/p">
+  {
+    "status": 401,
+    "message": "Token is not applicable for this project."
+  }
+  </error>
+</flow>
+```
+
+## See also
+
+* [FLAT Security](/reference/OpenAPI/security.md) (reference)

cookbook/post-check-flow.md

@@ -0,0 +1,32 @@
+# Performing Additional Checks on JWT Access Tokens
+
+swagger.yaml:
+
+```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
+      claims:
+        iss: "The token provider"
+      scope-claim: sc # default: scope
+      out-var: $jwt
+      post-check-flow: check-jwt.xml
+paths:
+  /projects/{p}:
+    x-flat-flow: ...
+    get:
+      security:
+        - JWTCookie: [ read ]
+    patch:
+      security:
+        - JWTCookie: [ write ]
+```

cookbook/request-timeout.md

@@ -16,3 +16,8 @@ In case we have to deal with a slow upstream system, the [various timeout option
 ```
 
 Without that `timeout` option the request will be aborted after three seconds – FLAT's default timeout setting.
+
+## See also
+
+* [`request` action timeouts](/reference/actions/request.md#options) (Reference)
+* [default timeouts](/administration/configuration.md#request-timeouts) (Administration)

cookbook/x-flat-jwt.md

@@ -347,6 +347,8 @@ init.xml:
 </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](checking-jwt-tokens.md).
+
 ## See also
 
 * [FLAT Security](/reference/OpenAPI/security.md) (reference)