Sets predefined [Access Control](#access-control) for current `SPA Block` context.
_Example:_ `access_control = ["foo"]`
|
### API Block
@@ -100,39 +101,39 @@ remote/local backend service(s), configured in the nested
`Server Block`. If an error occurred for api endpoints the response gets processed
as json error with an error body payload. This can be customized via `error_file`.
-| Block | Description |
-|:-------------------------------------|:------------|
-| *context* | [Server Block](#server-block). |
-| *label* | Optional. |
-| **Nested blocks** | **Description** |
-| [Endpoint Block(s)](#endpoint-block) | Configures specific endpoint(s) for current `API Block` context. |
-| [CORS Block](#cors-block) | Configures CORS behavior for the current `API Block` context. Overrides the CORS behavior of the parent [Server Block](#server-block). |
-| **Attributes** | **Description** |
-| `base_path` |
Optional.
Configures the path prefix for all requests.
Must be unique if multiple API Blocks are defined.
*Example:* `base_path = "/v1"`
|
-| `error_file` |
Optional.
Location of the error file template.
*Example:* `error_file = "./my_error_body.json"`
|
-| `access_control` |
Optional.
Sets predefined [Access Control](#access-control) for current `API Block` context.
*Example:* `access_control = ["foo"]`
⚠ Inherited by nested blocks.
|
+| Block | Description |
+| :----------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| _context_ | [Server Block](#server-block). |
+| _label_ | Optional. |
+| **Nested blocks** | **Description** |
+| [Endpoint Block(s)](#endpoint-block) | Configures specific endpoint(s) for current `API Block` context. |
+| [CORS Block](#cors-block) | Configures CORS behavior for the current `API Block` context. Overrides the CORS behavior of the parent [Server Block](#server-block). |
+| **Attributes** | **Description** |
+| `base_path` |
Optional.
Configures the path prefix for all requests.
Must be unique if multiple API Blocks are defined.
_Example:_ `base_path = "/v1"`
|
+| `error_file` |
Optional.
Location of the error file template.
_Example:_ `error_file = "./my_error_body.json"`
|
+| `access_control` |
Optional.
Sets predefined [Access Control](#access-control) for current `API Block` context.
_Example:_ `access_control = ["foo"]`
⚠ Inherited by nested blocks.
|
### Endpoint Block
-The `endpoint` blocks define the entry points of Couper. The mandatory *label*
+The `endpoint` blocks define the entry points of Couper. The mandatory _label_
defines the path suffix for the incoming client request. The `path` attribute
changes the path for the outgoing request (compare
[request routing example](./README.md#request-routing-example)). Each `Endpoint Block` must
produce an explicit or implicit client response.
-| Block | Description |
-|:-----------------------------------|:------------|
-| *context* | [Server Block](#server-block), [API Block](#api-block) |
-| *label* |
⚠ Mandatory.
Defines the path suffix for incoming client requests.
⚠ Mandatory if no [Backend Block](#backend-block) is defined.
References or refines a [Backend Block](#backend-block).
|
-| `url` |
Optional.
If defined, the host part of the URL must be the same as the `origin` attribute of the used [Backend Block](#backend-block) or [Backend Block Reference](#backend-block) (if defined).
⚠ Mandatory if no [Backend Block](#backend-block) is defined.
References or refines a [Backend Block](#backend-block).
|
+| `url` |
Optional.
If defined, the host part of the URL must be the same as the `origin` attribute of the used [Backend Block](#backend-block) or [Backend Block Reference](#backend-block) (if defined).
|
+| [Modifier](#modifier) |
Optional.
All [Modifier](#modifier).
|
### Request Block
@@ -157,74 +158,74 @@ The `request` block creates and executes a request to a backend service.
⚠ Multiple `proxy` and `request` blocks are executed in parallel.
-| Block | Description |
-|:----------------------------------------------------|:------------|
-| *context* | [Endpoint Block](#endpoint-block). |
-| *label* |
Partly optional.
A [Proxy Block](#proxy-block) or `Request Block` w/o a label has an implicit label `"default"`.
Only **one** [Proxy Block](#proxy-block) or `Request Block` w/ label `"default"` per [Endpoint Block](#endpoint-block) is allowed.
⚠ Mandatory if no [Backend Block](#backend-block) is defined.
References or refines a [Backend Block](#backend-block).
|
-| `url` |
Optional.
If defined, the host part of the URL must be the same as the `origin` attribute of the used [Backend Block](#backend-block) or [Backend Block Reference](#backend-block) (if defined).
⚠ Mandatory if no [Backend Block](#backend-block) is defined.
References or refines a [Backend Block](#backend-block).
|
+| `url` |
Optional.
If defined, the host part of the URL must be the same as the `origin` attribute of the used [Backend Block](#backend-block) or [Backend Block Reference](#backend-block) (if defined).
Same as `set_response_headers` in [Request Header](#response-header).
|
+| `status` |
HTTP status code.
Optional.
Default `200`.
|
+| `headers` |
Optional.
Same as `set_response_headers` in [Request Header](#response-header).
|
### Backend Block
A `backend` defines the connection to a local/remote backend service. Backends
-can be defined in the [Definitions Block](#definitions-block) and use the *label*
+can be defined in the [Definitions Block](#definitions-block) and use the _label_
as reference.
-| Block | Description |
-|:--------------------------------|:------------|
-| *context* | [Definitions Block](#definitions-block), [Proxy Block](#proxy-block), [Request Block](#request-block). |
-| *label* | ⚠ Mandatory in the [Definitions Block](#definitions-block). |
-| **Nested blocks** | **Description** |
-| [OpenAPI Block](#openapi-block) |
Optional.
Definition for validating outgoing requests to the origin and incoming responses from the origin.
Basic auth for the upstream request in format `username:password`.
|
| `hostname` |
Optional.
Value of the HTTP host header field for the origin request. Since `hostname` replaces the request host the value will also be used for a server identity check during a TLS handshake with the origin.
|
-| `origin` |
⚠ Mandatory.
URL to connect to for backend requests.
⚠ Must start with the scheme `http://...`.
|
-| `path` |
Optional.
Changeable part of upstream URL.
|
-| `path_prefix` |
Optional.
Prefixes all backend request paths with the given prefix.
Relative prefixes are prefixed with a slash `/`.
-| [Modifier](#modifier) |
Optional.
All [Modifier](#modifier).
|
+| `origin` |
⚠ Mandatory.
URL to connect to for backend requests.
⚠ Must start with the scheme `http://...`.
|
+| `path` |
Optional.
Changeable part of upstream URL.
|
+| `path_prefix` |
Optional.
Prefixes all backend request paths with the given prefix.
Relative prefixes are prefixed with a slash `/`.
|
+| [Modifier](#modifier) |
Optional.
All [Modifier](#modifier).
|
#### Transport Settings Attributes
-| Name | Type | Default | Description |
-|:---------------------------------|:-------------------|:----------------|:------------|
-| `connect_timeout` | [Timing](#timings) | `10s` | The total timeout for dialing and connect to the origin. |
-| `disable_certificate_validation` | bool | `false` | Disables the peer certificate validation. |
-| `disable_connection_reuse` | bool | `false` | Disables reusage of connections to the origin. |
-| `http2` | bool | `false` | Enables the HTTP2 support. |
-| `max_connections` | int | `0` (unlimited) | The maximum number of concurrent connections in any state (*active* or *idle*) to the origin. |
-| `proxy` | string | (no default) | A proxy URL for the related origin request. Example: `http://SERVER-IP_OR_NAME:PORT`. |
-| `timeout` | [Timing](#timings) | `300s` | The total deadline duration a backend request has for write and read/pipe. |
-| `ttfb_timeout` | [Timing](#timings) | `60s` | The duration from writing the full request to the origin and receiving the answer. |
+| Name | Type | Default | Description |
+| :------------------------------- | :----------------- | :-------------- | :-------------------------------------------------------------------------------------------- |
+| `connect_timeout` | [Timing](#timings) | `10s` | The total timeout for dialing and connect to the origin. |
+| `disable_certificate_validation` | bool | `false` | Disables the peer certificate validation. |
+| `disable_connection_reuse` | bool | `false` | Disables reusage of connections to the origin. |
+| `http2` | bool | `false` | Enables the HTTP2 support. |
+| `max_connections` | int | `0` (unlimited) | The maximum number of concurrent connections in any state (_active_ or _idle_) to the origin. |
+| `proxy` | string | (no default) | A proxy URL for the related origin request. Example: `http://SERVER-IP_OR_NAME:PORT`. |
+| `timeout` | [Timing](#timings) | `300s` | The total deadline duration a backend request has for write and read/pipe. |
+| `ttfb_timeout` | [Timing](#timings) | `60s` | The duration from writing the full request to the origin and receiving the answer. |
#### Timings
| Valid time unit | Description |
-|:----------------|:-------------|
+| :-------------- | :----------- |
| `ns` | nanoseconds |
| `us` (or `µs`) | microseconds |
| `ms` | milliseconds |
@@ -241,88 +242,87 @@ requests, and the Couper client from invalid answers. An example can be found
To do so Couper uses the [OpenAPI 3 standard](https://www.openapis.org/) to load
the definitions from a given document defined with the `file` attribute.
-| Block | Description |
-|:-----------------------------|:------------|
-| *context* | [Backend Block](#backend-block). |
-| *label* | Not implemented. |
-| **Attributes** | **Description** |
-| `file` |
⚠ Mandatory.
OpenAPI yaml definition file.
|
-| `ignore_request_violations` |
Optional.
Log request validation results, skip err handling.
Log request validation results, skip err handling.
Default `false`.
|
| `ignore_response_violations` |
Optional.
Log response validation results, skip err handling.
Default `false`.
|
**Caveats**: While ignoring request violations an invalid method or path would
-lead to a non-matching *route* which is still required for response validations.
+lead to a non-matching _route_ which is still required for response validations.
In this case the response validation will fail if not ignored too.
### CORS Block
The CORS block configures the CORS (Cross-Origin Resource Sharing) behavior in Couper.
-| Block | Description |
-|:--------------------|:------------|
-| *context* | [Server Block](#server-block), [Files Block](#files-block), [SPA Block](#spa-block), [API Block](#api-block). |
-| *label* | Not implemented. |
-| **Attributes** | **Description** |
+| Block | Description |
+| :------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| _context_ | [Server Block](#server-block), [Files Block](#files-block), [SPA Block](#spa-block), [API Block](#api-block). |
+| _label_ | Not implemented. |
+| **Attributes** | **Description** |
| `allowed_origins` |
⚠ Mandatory.
A list of allowed origin(s).
Can be either of:
a string with a single specific origin (e.g. `"https://www.example.com"`).
`"*"` (all origins are allowed).
an array of specific origins (e.g. `["https://www.example.com", "https://www.another.host.org"]`).
|
-| `allow_credentials` |
Optional.
Set to `true` if the response can be shared with credentialed requests (containing `Cookie` or `Authorization` HTTP header fields).
Default `false`.
|
-| `disable` |
Optional.
Set to `true` to disable the inheritance of CORS from the [Server Block](#server-block) in [Files Block](#files-block), [SPA Block](#spa-block) and [API Block](#api-block) contexts.
Default `false`.
|
-| `max_age` |
Optional.
Indicates the time the information provided by the `Access-Control-Allow-Methods` and `Access-Control-Allow-Headers` response HTTP header fields.
Can be cached (string with time unit, e.g. `"1h"`).
|
+| `allow_credentials` |
Optional.
Set to `true` if the response can be shared with credentialed requests (containing `Cookie` or `Authorization` HTTP header fields).
Default `false`.
|
+| `disable` |
Optional.
Set to `true` to disable the inheritance of CORS from the [Server Block](#server-block) in [Files Block](#files-block), [SPA Block](#spa-block) and [API Block](#api-block) contexts.
Default `false`.
|
+| `max_age` |
Optional.
Indicates the time the information provided by the `Access-Control-Allow-Methods` and `Access-Control-Allow-Headers` response HTTP header fields.
Can be cached (string with time unit, e.g. `"1h"`).
URL of the token endpoint at the authorization server.
|
+| `client_id` |
⚠ Mandatory.
The client identifier.
|
+| `client_secret` |
⚠ Mandatory.
The client password.
|
+| `retries` |
Optional.
The number of retries to get the token and resource, if the resource-request responds with `401 Unauthorized` HTTP status code.
Default: `1`.
|
| `token_endpoint_auth_method` |
Optional.
Defines the method to authenticate the client at the token endpoint.
If set to `client_secret_post`, the client credentials are transported in the request body.
If set to `client_secret_basic`, the client credentials are transported via Basic Authentication.
Default: `client_secret_basic`.
|
-| `scope` |
Optional.
A space separated list of requested scopes for the access token.
|
-
+| `scope` |
Optional.
A space separated list of requested scopes for the access token.
|
### Definitions Block
Use the `definitions` block to define configurations you want to reuse.
[Access Control](#access-control) is **always** defined in the `Definitions Block`.
-| Block | Description |
-|:-----------------------------------------|:------------|
-| *context* | Root of the configuration file. |
-| *label* | Not implemented. |
-| **Nested blocks** | **Description** |
-| [Backend Block(s)](#backend-block) | Defines `Backend Block(s)`. |
-| [Basic Auth Block(s)](#basic-auth-block) | Defines `Basic Auth Block(s)`. |
-| [JWT Block(s)](#jwt-block) | Defines `JWT Block(s)`. |
+| Block | Description |
+| :--------------------------------------------------------- | :-------------------------------------- |
+| _context_ | Root of the configuration file. |
+| _label_ | Not implemented. |
+| **Nested blocks** | **Description** |
+| [Backend Block(s)](#backend-block) | Defines `Backend Block(s)`. |
+| [Basic Auth Block(s)](#basic-auth-block) | Defines `Basic Auth Block(s)`. |
+| [JWT Block(s)](#jwt-block) | Defines `JWT Block(s)`. |
| [JWT Signing Profile Block(s)](#jwt-signing-profile-block) | Defines `JWT Signing Profile Block(s)`. |
-| [SAML Block(s)](#saml-block) | Defines `SAML Block(s)`. |
+| [SAML Block(s)](#saml-block) | Defines `SAML Block(s)`. |
### Basic Auth Block
The `basic_auth` block lets you configure basic auth for your gateway. Like all
[Access Control](#access-control) types, the `Basic Auth` block is defined in the
[Definitions Block](#definitions-block) and can be referenced in all configuration
-blocks by its mandatory *label*.
+blocks by its mandatory _label_.
If both `user`/`password` and `htpasswd_file` are configured, the incoming
credentials from the `Authorization` request HTTP header field are checked against
`user`/`password` if the user matches, and against the data in the file referenced
by `htpasswd_file` otherwise.
-| Block | Description |
-|:----------------|:------------|
-| *context* | [Definitions Block](#definitions-block). |
-| *label* | ⚠ Mandatory. |
-| **Attributes** | **Description** |
-| `user` |
The realm to be sent in a `WWW-Authenticate` response HTTP header field.
|
### JWT Block
@@ -330,37 +330,37 @@ by `htpasswd_file` otherwise.
The `jwt` block lets you configure JSON Web Token access control for your gateway.
Like all [Access Control](#access-control) types, the `jwt` block is defined in
the `definitions` block and can be referenced in all configuration blocks by its
-mandatory *label*.
-
-| Block | Description |
-|:---------------------------|:------------|
-| *context* | [Definitions Block](#definitions-block). |
-| *label* | ⚠ Mandatory. |
-| **Attributes** | **Description** |
-| `cookie = "AccessToken"` |
Optional.
Read `AccessToken` key to gain the token value from a cookie.
List of claims that must be given for a valid token
|
### JWT Signing Profile Block
The `jwt_signing_profile` block lets you configure a JSON Web Token signing
profile for your gateway. It is referenced in the [`jwt_sign()` function](#functions)
-by its mandatory *label*.
-
-| Name | Description |
-|:--------------------------|:------------|
-| *context* | [Definitions Block](#definitions-block). |
-| *label* | ⚠ Mandatory. |
-| **Attributes** | **Description** |
-| `key` |
Optional.
Private key (in PEM format) for `RS*` variants or the secret for `HS*` algorithm.
The token's time-to-live (creates the `exp` claim).
|
+| **`claims`** |
Optional.
Default claims for the JWT payload.
|
### SAML Block
@@ -368,42 +368,42 @@ The `saml` block lets you configure the `saml_sso_url()` [function](#functions)
control for a SAML Assertion Consumer Service (ACS) endpoint.
Like all [Access Control](#access-control) types, the `saml` block is defined in
the `definitions` block and can be referenced in all configuration blocks by its
-mandatory *label*.
-
-| Block | Description |
-|:---------------------------|:------------|
-| *context* | [Definitions Block](#definitions-block). |
-| *label* | ⚠ Mandatory. |
-| **Attributes** | **Description** |
-| `idp_metadata_file` |
⚠ Mandatory.
File reference to the Identity Provider metadata XML file.
|
-| `sp_acs_url` |
⚠ Mandatory.
The URL of the Service Provider's ACS endpoint.
|
-| `sp_entity_id` |
⚠ Mandatory.
The Service Provider's entity ID.
|
-| `array_attributes` |
Optional.
A list of assertion attributes that may have several values.