Skip to content

Latest commit

 

History

History
966 lines (752 loc) · 121 KB

REFERENCE.md

File metadata and controls

966 lines (752 loc) · 121 KB
Raw

Reference

Block Reference

Server Block

The server block is one of the root configuration blocks of Couper's configuration file.

Block name Context Label Nested block(s)
server - optional CORS Block, Files Block, SPA Block(s) , API Block(s), Endpoint Block(s)
Attribute(s) Type Default Description Characteristic(s) Example
base_path string - Configures the path prefix for all requests. ⚠ Inherited by nested blocks. base_path = "/api"
hosts tuple (string) ["*:8080"] - ⚠ required, if there is more than one server block. ⚠ Only one hosts attribute per server block is allowed. hosts = ["example.com", "localhost:9090"]
error_file string - Location of the error file template. - error_file = "./my_error_page.html"
access_control tuple (string) - Sets predefined Access Control for server block context. ⚠ Inherited by nested blocks. access_control = ["foo"]
disable_access_control tuple (string) - Disables access controls by name. - disable_access_control = ["foo"]
custom_log_fields object - Defines log fields for Custom Logging. ⚠ Inherited by nested blocks. -

Files Block

The files blocks configure the file serving. Can be defined multiple times as long as the base_path is unique.

Block name Context Label Nested block(s)
files Server Block Optional CORS Block
Attribute(s) Type Default Description Characteristic(s) Example
base_path string - Configures the path prefix for all requests. - base_path = "/files"
document_root string - Location of the document root. ⚠ required document_root = "./htdocs"
error_file string - Location of the error file template. - -
access_control tuple (string) - Sets predefined Access Control for files block context. - access_control = ["foo"]
disable_access_control tuple (string) - Disables access controls by name. - disable_access_control = ["foo"]
custom_log_fields object - Defines log fields for Custom Logging. ⚠ Inherited by nested blocks. -

SPA Block

The spa blocks configure the Web serving for SPA assets. Can be defined multiple times as long as the base_path+paths is unique.

Block name Context Label Nested block(s)
spa Server Block Optional CORS Block
Attribute(s) Type Default Description Characteristic(s) Example
base_path string - Configures the path prefix for all requests. - base_path = "/assets"
bootstrap_file string - Location of the bootstrap file. ⚠ required bootstrap_file = "./htdocs/index.html"
paths tuple (string) - List of SPA paths that need the bootstrap file. ⚠ required paths = ["/app/**"]
access_control tuple (string) - Sets predefined Access Control for spa block context. - access_control = ["foo"]
disable_access_control tuple (string) - Disables access controls by name. - disable_access_control = ["foo"]
custom_log_fields object - Defines log fields for Custom Logging. ⚠ Inherited by nested blocks. -

API Block

The api block bundles endpoints under a certain base_path.

⚠ 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 name Context Label Nested block(s)
api Server Block Optional Endpoint Block(s), CORS Block, Error Handler Block(s)
Attribute(s) Type Default Description Characteristic(s) Example
base_path string - Configures the path prefix for all requests. base_path = "/v1"
error_file string - Location of the error file template. - error_file = "./my_error_body.json"
access_control tuple (string) - Sets predefined Access Control for api block context. ⚠ Inherited by nested blocks. access_control = ["foo"]
disable_access_control tuple (string) - Disables access controls by name. - disable_access_control = ["foo"]
allowed_methods tuple (string) ["*"] == ["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"] Sets allowed methods as default for all contained endpoints. Requests with a method that is not allowed result in an error response with a 405 Method Not Allowed status. The default value * can be combined with additional methods. Methods are matched case-insensitively. Access-Control-Allow-Methods is only sent in response to a CORS preflight request, if the method requested by Access-Control-Request-Method is an allowed method. allowed_methods = ["GET", "POST"] or allowed_methods = ["*", "BREW"]
beta_required_permission expression evaluating to string or object (string) - Permission required to use this API (see error type beta_insufficient_permissions). If the value is a string, the same permission applies to all request methods. If there are different permissions for different request methods, use an object with the request methods as keys and string values. Methods not specified in this object are not permitted. "*" is the key for "all other standard methods". Methods other than GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS must be specified explicitly. A value "" means "no permission required". beta_required_permission = "read" or beta_required_permission = { post = "write", "*" = "" } or beta_required_permission = default(request.path_params.p, "not_set")
custom_log_fields object - Defines log fields for Custom Logging. ⚠ Inherited by nested blocks. -

Endpoint Block

endpoint blocks define the entry points of Couper. The required label defines the path suffix for the incoming client request. Each endpoint block must produce an explicit or implicit client response.

Block name Context Label Nested block(s)
endpoint Server Block, API Block ⚠ required, defines the path suffix for incoming client requests Proxy Block(s), Request Block(s), Response Block, Error Handler Block(s)
Attribute(s) Type Default Description Characteristic(s) Example
request_body_limit string "64MiB" Configures the maximum buffer size while accessing request.form_body or request.json_body content. ⚠ Valid units are: KiB, MiB, GiB request_body_limit = "200KiB"
access_control tuple (string) - Sets predefined Access Control for endpoint block context. - access_control = ["foo"]
disable_access_control tuple (string) - Disables access controls by name. - disable_access_control = ["foo"]
allowed_methods tuple (string) ["*"] == ["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"] Sets allowed methods overriding a default set in the containing api block. Requests with a method that is not allowed result in an error response with a 405 Method Not Allowed status. The default value "*" can be combined with additional methods. Methods are matched case-insensitively. Access-Control-Allow-Methods is only sent in response to a CORS preflight request, if the method requested by Access-Control-Request-Method is an allowed method. allowed_methods = ["GET", "POST"] or allowed_methods = ["*", "BREW"]
beta_required_permission expression evaluating to string or object (string) - Permission required to use this endpoint (see error type beta_insufficient_permissions). Overrides beta_required_permission in a containing api block. If the value is a string, the same permission applies to all request methods. If there are different permissions for different request methods, use an object with the request methods as keys and string values. Methods not specified in this object are not permitted. "*" is the key for "all other standard methods". Methods other than GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS must be specified explicitly. A value "" means "no permission required". For api blocks with at least two endpoints, all endpoints must have either a) no beta_required_permission set or b) either beta_required_permission or disable_access_control set. Otherwise, a configuration error is thrown. beta_required_permission = "read" or beta_required_permission = { post = "write", "*" = "" } or beta_required_permission = default(request.path_params.p, "not_set")
custom_log_fields object - Defines log fields for Custom Logging. ⚠ Inherited by nested blocks. -
Modifiers - - - - -

Endpoint Sequence

If request and/or proxy block definitions are sequential based on their backend_responses.* variable references at load-time they will be executed sequentially. Unexpected responses can be caught with error handling.

Proxy Block

The proxy block creates and executes a proxy request to a backend service.

⚠ Multiple proxy and Request Blocks are executed in parallel.

Block name Context Label Nested block(s)
proxy Endpoint Block ⚠ A proxy block or Request Block w/o a label has an implicit label "default". Only one proxy block or Request Block w/ label "default" per Endpoint Block is allowed. Backend Block (⚠ required, if no Backend Block reference is defined or no url attribute is set.), Websockets Block (⚠ Either websockets attribute or block is allowed.)
Attribute(s) Type Default Description Characteristic(s) Example
backend string - Backend Block reference, defined in Definitions Block ⚠ required, if no Backend Block or url attribute is defined. backend = "foo"
expected_status tuple (number) - If defined, the response status code will be verified against this list of codes. If the status-code is unexpected an unexpected_status error can be handled with an error_handler. - -
url string - If defined, the host part of the URL must be the same as the origin attribute of the Backend Block (if defined). - -
websockets bool false Allows support for websockets. This attribute is only allowed in the 'default' proxy block. Other proxy blocks, Request Blocks or Response Blocks are not allowed in the current Endpoint Block. ⚠ Either websockets attribute or block is allowed. websockets = true
Modifiers - - - - -

Request Block

The request block creates and executes a request to a backend service.

⚠ Multiple Proxy and request blocks are executed in parallel.

Block name Context Label Nested block(s)
request Endpoint Block ⚠ A Proxy Block or Request Block w/o a label has an implicit label "default". Only one Proxy Block or Request Block w/ label "default" per Endpoint Block is allowed. Backend Block (⚠ required, if no backend block reference is defined or no url attribute is set.
Attribute(s) Type Default Description Characteristic(s) Example
backend string - backend block reference, defined in Definitions Block ⚠ required, if no Backend Block is defined. backend = "foo"
body string - - Creates implicit default Content-Type: text/plain header field. -
expected_status tuple (number) - If defined, the response status code will be verified against this list of codes. If the status-code is unexpected an unexpected_status error can be handled with an error_handler. - -
form_body object - - Creates implicit default Content-Type: application/x-www-form-urlencoded header field. -
headers object - - Same as set_request_headers in Request Header. -
json_body null, bool, number, string, object, tuple - - Creates implicit default Content-Type: text/plain header field. -
method string "GET" - - -
query_params - - - Same as set_query_params in Query Parameter. -
url string - - If defined, the host part of the URL must be the same as the origin attribute of the used Backend Block or Backend Block Reference (if defined). -

Response Block

The response block creates and sends a client response.

Block name Context Label Nested block(s)
response Endpoint Block no label -
Attribute(s) Type Default Description Characteristic(s) Example
body string - - Creates implicit default Content-Type: text/plain header field. -
json_body null, bool, number, string, object, tuple - - Creates implicit default Content-Type: application/json header field. -
status integer 200 HTTP status code. - -
headers object - Same as set_response_headers in Request Header. - -

Backend Block

The backend block defines the connection to a local/remote backend service.

⚠ Backends can be defined in the Definitions Block and referenced by label.

Block name Context Label Nested block(s)
backend Definitions Block, Proxy Block, Request Block, OAuth2 CC Block, JWT Block, OAuth2 AC Block (beta), OIDC Block ⚠ required, when defined in Definitions Block OpenAPI Block, OAuth2 CC Block, Health Block
Attribute(s) Type Default Description Characteristic(s) Example
basic_auth string - Basic auth for the upstream request. format is "username:password" -
custom_log_fields object - Defines log fields for Custom Logging. - -
hostname string - 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 string - URL to connect to for backend requests. ⚠ required. ⚠ Must start with one of the URI schemes https or http. -
path string - Changeable part of upstream URL. - -
path_prefix string - Prefixes all backend request paths with the given prefix - -
connect_timeout duration "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 integer 0 (unlimited) The maximum number of concurrent connections in any state (active or idle) to the origin. - -
proxy string - A proxy URL for the related origin request. - "http://SERVER-IP_OR_NAME:PORT"
timeout duration "300s" The total deadline duration a backend request has for write and read/pipe. - -
ttfb_timeout duration "60s" The duration from writing the full request to the origin and receiving the answer. - -
use_when_unhealthy bool false Ignores the health state and continues with the outgoing request - -
Modifiers - - All Modifiers - -

Duration

Duration units Description
ns nanoseconds
us (or µs) microseconds
ms milliseconds
s seconds
m minutes
h hours

OpenAPI Block

The openapi block configures the backends proxy behavior to validate outgoing and incoming requests to and from the origin. Preventing the origin from invalid requests, and the Couper client from invalid answers. An example can be found here. To do so Couper uses the OpenAPI 3 standard to load the definitions from a given document defined with the file attribute.

⚠ While ignoring request violations an invalid method or path would 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.

Block name Context Label Nested block(s)
openapi Backend Block - -
Attribute(s) Type Default Description Characteristic(s) Example
file string - OpenAPI yaml definition file. ⚠ required file = "openapi.yaml"
ignore_request_violations bool false Log request validation results, skip error handling. - -
ignore_response_violations bool false Log response validation results, skip error handling. - -

CORS Block

The cors block configures the CORS (Cross-Origin Resource Sharing) behavior in Couper.

⚠ Overrides the CORS behavior of the parent block.

Block name Context Label Nested block(s)
cors Server Block, Files Block, SPA Block, API Block. no label -
Attribute(s) Type Default Description Characteristic(s) Example
allowed_origins string or tuple (string) - An allowed origin or a list of allowed origins. Can be either of: a string with a single specific origin, "*" (all origins are allowed) or an array of specific origins allowed_origins = ["https://www.example.com", "https://www.another.host.org"]
allow_credentials bool false Set to true if the response can be shared with credentialed requests (containing Cookie or Authorization HTTP header fields). - -
disable bool false Set to true to disable the inheritance of CORS from the Server Block in Files Block, SPA Block and API Block contexts. - -
max_age duration - Indicates the time the information provided by the Access-Control-Allow-Methods and Access-Control-Allow-Headers response HTTP header fields. ⚠ Can be cached max_age = "1h"

Note: Access-Control-Allow-Methods is only sent in response to a CORS preflight request, if the method requested by Access-Control-Request-Method is an allowed method (see the allowed_method attribute for api or endpoint blocks).

OAuth2 CC Block

The oauth2 block in the Backend Block context configures the OAuth2 Client Credentials flow to request a bearer token for the backend request.

Block name Context Label Nested block(s)
oauth2 Backend Block no label Backend Block
Attribute(s) Type Default Description Characteristic(s) Example
backend string - Backend Block Reference - -
grant_type string - - ⚠ required, to be set to: client_credentials grant_type = "client_credentials"
token_endpoint string - URL of the token endpoint at the authorization server. ⚠ required -
client_id string - The client identifier. ⚠ required -
client_secret string - The client password. ⚠ required. -
retries integer 1 The number of retries to get the token and resource, if the resource-request responds with 401 Unauthorized HTTP status code. - -
token_endpoint_auth_method string "client_secret_basic" 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. -
scope string - A space separated list of requested scope values for the access token. - scope = "read write"

The HTTP header field Accept: application/json is automatically added to the token request. This can be modified with request header modifiers in a backend block.

Websockets Block

The websockets block activates support for websocket connections in Couper.

Block name Context Label Nested block(s)
websockets Proxy Block no label -
Attribute(s) Type Default Description Characteristic(s) Example
timeout duration - The total deadline duration a websocket connection has to exists. - timeout = 600s
set_request_headers - - - Same as set_request_headers in Request Header. -

Definitions Block

Use the definitions block to define configurations you want to reuse.

⚠ Access Control is always defined in the definitions block.

Block name Context Label Nested block(s)
definitions - no label Backend Block(s), Basic Auth Block(s), JWT Block(s), JWT Signing Profile Block(s), SAML Block(s), OAuth2 AC Block(s), OIDC Block(s)

Basic Auth Block

The basic_auth block lets you configure basic auth for your gateway. Like all Access Control types, the basic_auth block is defined in the Definitions Block and can be referenced in all configuration blocks by its required 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 name Context Label Nested block(s)
basic_auth Definitions Block ⚠ required Error Handler Block(s)
Attribute(s) Type Default Description Characteristic(s) Example
user string "" The user name. - -
password string "" The corresponding password. - -
htpasswd_file string "" The htpasswd file. Couper uses Apache's httpasswd file format. apr1, md5 and bcrypt password encryptions are supported. The file is loaded once at startup. Restart Couper after you have changed it. -
realm string "" The realm to be sent in a WWW-Authenticate response HTTP header field. - -
custom_log_fields object - Defines log fields for Custom Logging. ⚠ Inherited by nested blocks. -

The user is accessable via request.context.<label>.user for successfully authenticated requests.

JWT Block

The jwt block lets you configure JSON Web Token access control for your gateway. Like all Access Control types, the jwt block is defined in the Definitions Block and can be referenced in all configuration blocks by its required label.

Since responses from endpoints protected by JWT access controls are not publicly cacheable, a Cache-Control: private header field is added to the response, unless this feature is disabled with disable_private_caching = true.

Block name Context Label Nested block(s)
jwt Definitions Block ⚠ required JWKS backend, Error Handler Block(s)
Attribute(s) Type Default Description Characteristic(s) Example
cookie string - Read token value from a cookie. cannot be used together with header or token_value cookie = "AccessToken"
custom_log_fields object - Defines log fields for Custom Logging. ⚠ Inherited by nested blocks. -
header string - Read token value from a request header field. ⚠ Implies Bearer if Authorization (case-insensitive) is used, otherwise any other header name can be used. Cannot be used together with cookie or token_value. header = "Authorization"
token_value string - expression to obtain the token cannot be used together with cookie or header token_value = request.form_body.token[0]
key string - Public key (in PEM format) for RS* and ES* variants or the secret for HS* algorithm. - -
key_file string - Optional file reference instead of key usage. - -
signature_algorithm string - - Valid values: "RS256", "RS384", "RS512", "HS256", "HS384", "HS512", "ES256", "ES384", "ES512" -
claims object - Object with claims that must be given for a valid token (equals comparison with JWT payload). The claim values are evaluated per request. claims = { pid = request.path_params.pid }
required_claims string - List of claim names that must be given for a valid token - required_claims = ["roles"]
beta_permissions_claim string - name of claim containing the granted permissions The claim value must either be a string containing a space-separated list of permissions or a list of string permissions beta_permissions_claim = "scope"
beta_permissions_map object (string) - mapping of granted permissions to additional granted permissions Maps values from beta_permissions_claim and those created from beta_roles_map. The map is called recursively. beta_permissions_map = { p1 = ["p3", "p4"], p2 = ["p5"] }
beta_roles_claim string - name of claim specifying the roles of the user represented by the token The claim value must either be a string containing a space-separated list of role values or a list of string role values beta_roles_claim = "roles"
beta_roles_map object (string) - mapping of roles to granted permissions Non-mapped roles can be assigned with * to specific permissions. beta_roles_map = { role1 = ["p1", "p2"], role2 = ["p3"], "*" = ["public"] }
jwks_url string - URI pointing to a set of JSON Web Keys (RFC 7517) - jwks_url = "http://identityprovider:8080/jwks.json"
jwks_ttl duration "1h" Time period the JWK set stays valid and may be cached. - jwks_ttl = "1800s"
jwks_max_stale duration "1h" Time period the cached JWK set stays valid after its TTL has passed. - jwks_max_stale = "45m"
backend string - backend reference for enhancing JWKS requests - backend = "jwks_backend"
disable_private_caching bool false If set to true, Couper does not add the private directive to the Cache-Control HTTP header field value. - -

The attributes header, cookie and token_value are mutually exclusive. If all three attributes are missing, header = "Authorization" will be implied, i.e. the token will be read from the incoming Authorization header.

If the key to verify the signatures of tokens does not change over time, it should be specified via either key or key_file (together with signature_algorithm). Otherwise, a JSON web key set should be referenced via jwks_url; in this case, the tokens need a kid header.

A JWT access control configured by this block can extract permissions from

  • the value of the claim specified by beta_permissions_claim and
  • the result of mapping the value of the claim specified by beta_roles_claim using the beta_roles_map.

The jwt block may also be referenced by the jwt_sign() function, if it has a signing_ttl defined. For HS* algorithms the signing key is taken from key/key_file, for RS* and ES* algorithms, signing_key or signing_key_file have to be specified.

Note: A jwt block with signing_ttl cannot have the same label as a jwt_signing_profile block.

Attribute(s) Type Default Description Characteristic(s) Example
signing_key string - Private key (in PEM format) for RS* and ES* variants. - -
signing_key_file string - Optional file reference instead of signing_key usage. - -
signing_ttl duration - The token's time-to-live (creates the exp claim). - -

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 by its required label.

An example can be found here.

Block name Context Label Nested block(s)
jwt_signing_profile Definitions Block ⚠ required -
Attribute(s) Type Default Description Characteristic(s) Example
key string - Private key (in PEM format) for RS* and ES* variants or the secret for HS* algorithm. - -
key_file string - Optional file reference instead of key usage. - -
signature_algorithm - - - ⚠ required. Valid values: "RS256", "RS384", "RS512", "HS256", "HS384", "HS512", "ES256", "ES384", "ES512" -
ttl duration - The token's time-to-live (creates the exp claim). - -
claims object - Default claims for the JWT payload. The claim values are evaluated per request. claims = { iss = "https://the-issuer.com" }
headers object - Additional header fields for the JWT. alg and typ cannot be set. headers = { kid = "my-key-id" }

OAuth2 AC Block (Beta)

The beta_oauth2 block lets you configure the oauth2_authorization_url() function and an access control for an OAuth2 Authorization Code Grant Flow redirect endpoint. Like all Access Control types, the beta_oauth2 block is defined in the Definitions Block and can be referenced in all configuration blocks by its required label.

Block name Context Label Nested block(s)
beta_oauth2 Definitions Block ⚠ required Backend Block, Error Handler Block
Attribute(s) Type Default Description Characteristic(s) Example
backend string - Backend Block Reference ⚠ Do not disable the peer certificate validation with disable_certificate_validation = true! -
authorization_endpoint string - The authorization server endpoint URL used for authorization. ⚠ required -
token_endpoint string - The authorization server endpoint URL used for requesting the token. ⚠ required -
token_endpoint_auth_method string "client_secret_basic" 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. -
redirect_uri string - The Couper endpoint for receiving the authorization code. ⚠ required. Relative URL references are resolved against the origin of the current request URL. The origin can be changed with the accept_forwarded_url attribute if Couper is running behind a proxy. -
grant_type string - The grant type. ⚠ required, to be set to: "authorization_code" grant_type = "authorization_code"
client_id string - The client identifier. ⚠ required -
client_secret string - The client password. ⚠ required. -
scope string - A space separated list of requested scope values for the access token. - scope = "read write"
verifier_method string - The method to verify the integrity of the authorization code flow ⚠ required, available values: "ccm_s256" (code_challenge parameter with code_challenge_method S256), "state" (state parameter) verifier_method = "ccm_s256"
verifier_value string or expression - The value of the (unhashed) verifier. ⚠ required; e.g. using cookie value created with oauth2_verifier() function verifier_value = request.cookies.verifier
custom_log_fields object - Defines log fields for Custom Logging. ⚠ Inherited by nested blocks. -

If the authorization server supports the code_challenge_method S256 (a.k.a. PKCE, see RFC 7636), we recommend verifier_method = "ccm_s256".

The HTTP header field Accept: application/json is automatically added to the token request. This can be modified with request header modifiers in a backend block.

OIDC Block

The oidc block lets you configure the oauth2_authorization_url() function and an access control for an OIDC Authorization Code Grant Flow redirect endpoint. Like all Access Control types, the oidc block is defined in the Definitions Block and can be referenced in all configuration blocks by its required label.

Block name Context Label Nested block(s)
oidc Definitions Block ⚠ required Backend Block, Error Handler Block
Attribute(s) Type Default Description Characteristic(s) Example
backend string - Backend Block Reference ⚠ Do not disable the peer certificate validation with disable_certificate_validation = true! -
configuration_url string - The OpenID configuration URL. ⚠ required -
configuration_ttl duration "1h" The duration to cache the OpenID configuration located at configuration_url. - configuration_ttl = "1d"
configuration_max_stale duration "1h" Duration a cached OpenID configuration stays valid after its TTL has passed. - configuration_max_stale = "2h"
token_endpoint_auth_method string "client_secret_basic" 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. -
redirect_uri string - The Couper endpoint for receiving the authorization code. ⚠ required. Relative URL references are resolved against the origin of the current request URL. The origin can be changed with the accept_forwarded_url attribute if Couper is running behind a proxy. -
client_id string - The client identifier. ⚠ required -
client_secret string - The client password. ⚠ required. -
scope string - A space separated list of requested scope values for the access token. openid is automatically added. scope = "profile read"
verifier_method string - The method to verify the integrity of the authorization code flow available values: "ccm_s256" (code_challenge parameter with code_challenge_method S256), "nonce" (nonce parameter) verifier_method = "nonce"
verifier_value string or expression - The value of the (unhashed) verifier. ⚠ required; e.g. using cookie value created with oauth2_verifier() function verifier_value = request.cookies.verifier
custom_log_fields object - Defines log fields for Custom Logging. ⚠ Inherited by nested blocks. -
jwks_ttl duration "1h" Time period the JWK set stays valid and may be cached. - jwks_ttl = "3h"
jwks_max_stale duration "1h" Time period the cached JWK set stays valid after its TTL has passed. - jwks_max_stale = "1h30m"
configuration_backend string - Backend Block Reference ⚠ Do not disable the peer certificate validation with disable_certificate_validation = true! -
jwks_uri_backend string - Backend Block Reference ⚠ Do not disable the peer certificate validation with disable_certificate_validation = true! -
token_backend string - Backend Block Reference ⚠ Do not disable the peer certificate validation with disable_certificate_validation = true! -
userinfo_backend string - Backend Block Reference ⚠ Do not disable the peer certificate validation with disable_certificate_validation = true! -

In most cases, referencing one backend (backend attribute) for all the backend requests sent by the OIDC client is enough. You should only use configuration_backend, jwks_uri_backend, token_backend or userinfo_backend if you need to configure a specific behaviour for the respective request (e.g. timeouts).

If the OpenID server supports the code_challenge_method S256 the default value for verifier_methodis "ccm_s256", "nonce" otherwise.

The HTTP header field Accept: application/json is automatically added to the token request. This can be modified with request header modifiers in a backend block.

SAML Block

The saml block lets you configure the saml_sso_url() function and an access control for a SAML Assertion Consumer Service (ACS) endpoint. Like all Access Control types, the saml block is defined in the Definitions Block and can be referenced in all configuration blocks by its required label.

Block name Context Label Nested block(s)
saml Definitions Block ⚠ required Error Handler Block
Attribute(s) Type Default Description Characteristic(s) Example
idp_metadata_file string - File reference to the Identity Provider metadata XML file. ⚠ required -
sp_acs_url string - The URL of the Service Provider's ACS endpoint. ⚠ required. Relative URL references are resolved against the origin of the current request URL. The origin can be changed with the accept_forwarded_url attribute if Couper is running behind a proxy. -
sp_entity_id string - The Service Provider's entity ID. ⚠ required -
array_attributes tuple (string) [] A list of assertion attributes that may have several values. Results in at least an empty array in request.context.<label>.attributes.<name> array_attributes = ["memberOf"]
custom_log_fields object - Defines log fields for Custom Logging. ⚠ Inherited by nested blocks. -

Some information from the assertion consumed at the ACS endpoint is provided in the context at request.context.<label>:

  • the NameID of the assertion's Subject (request.context.<label>.sub)
  • the session expiry date SessionNotOnOrAfter (as UNIX timestamp: request.context.<label>.exp)
  • the attributes (request.context.<label>.attributes.<name>)

Health Block

Defines a recurring health check request for its backend. Results can be obtained via the backends.<label>.health variables. Changes in health states and related requests will be logged. Default User-Agent will be Couper / <version> health-check if not provided via headers attribute. An unhealthy backend will return with a backend_unhealthy error.

Block name Context Label Nested block
beta_health backend block –
Attributes Type Default Description Characteristics Example
expected_status tuple (number) [200, 204, 301] wanted response status code expected_status = [418]
expected_text string – text response body must contain expected_text = "alive"
failure_threshold number 2 failed checks needed to consider backend unhealthy failure_threshold = 3
headers object – request headers headers = {User-Agent = "health"}
interval duration "1s" time interval for recheck interval = "5s"
path string – URL path/query on backend host path = "/health"
timeout duration "2s" maximum allowed time limit bounded by interval timeout = "3s"

Settings Block

The settings block lets you configure the more basic and global behavior of your gateway instance.

Context Label Nested block(s)
- no label -
Attribute(s) Type Default Description Characteristic(s) Example
accept_forwarded_url tuple (string) [] Which X-Forwarded-* request headers should be accepted to change the request variables url, origin, protocol, host, port. Valid values are "proto", "host" and "port". The port in X-Forwarded-Port takes precedence over a port in X-Forwarded-Host. Affects relative url values for sp_acs_url attribute and redirect_uri attribute within beta_oauth2 & oidc. ["proto","host","port"]
default_port number 8080 Port which will be used if not explicitly specified per host within the hosts list. - -
health_path string "/healthz" Health path which is available for all configured server and ports. - -
https_dev_proxy tuple (string) [] List of tls port mappings to define the tls listen port and the target one. A self-signed certificate will be generated on the fly based on given hostname. Certificates will be hold in memory and are generated once. ["443:8080", "8443:8080"]
log_format string "common" Switch for tab/field based colored view or JSON log lines. Valid values are "common" and "json". - -
log_level string "info" Set the log-level to one of: "info", "panic", "fatal", "error", "warn", "debug", "trace". - -
log_pretty bool false Global option for json log format which pretty prints with basic key coloring. - -
no_proxy_from_env bool false Disables the connect hop to configured proxy via environment. - -
request_id_accept_from_header string "" Name of a client request HTTP header field that transports the request.id which Couper takes for logging and transport to the backend (if configured). - X-UID
request_id_backend_header string Couper-Request-ID Name of a HTTP header field which Couper uses to transport the request.id to the backend. - -
request_id_client_header string Couper-Request-ID Name of a HTTP header field which Couper uses to transport the request.id to the client. - -
request_id_format string "common" Valid values are "common" and "uuid4". If set to "uuid4" a rfc4122 uuid is used for request.id and related log fields. - -
secure_cookies string "" Valid values are "" and "strip". If set to "strip", the Secure flag is removed from all Set-Cookie HTTP header fields. - -
xfh bool false Option to use the X-Forwarded-Host header as the request host. - -
beta_metrics bool false Option to enable the Prometheus metrics exporter. - -
beta_metrics_port number 9090 Prometheus exporter listen port. - -
beta_service_name string "couper" The service name which applies to the service_name metric labels. - -
ca_file string "" Option for adding the given PEM encoded ca-certificate to the existing system certificate pool for all outgoing connections. - -

Defaults Block

The defaults block lets you define default values.

Block name Context Label Nested block(s)
defaults - - -
Attribute(s) Type Default Description Characteristic(s) Example
environment_variables object (string) – One or more environment variable assigments - environment_variables = {ORIGIN = "https://httpbin.org" ...}

Examples:

Error Handler Block

The error_handler block lets you configure the handling of errors thrown in components configured by the parent blocks.

The error handler label specifies which error type should be handled. Multiple labels are allowed. The label can be omitted to catch all relevant errors. This has the same behavior as the error type *, that catches all errors explicitly.

Concerning child blocks and attributes, the error_handler block is similar to an Endpoint Block.

Block name Context Label Nested block(s)
error_handler API Block, Endpoint Block, Basic Auth Block, JWT Block, OAuth2 AC Block (Beta), OIDC Block, SAML Block optional Proxy Block(s), Request Block(s), Response Block, Error Handler Block(s)
Attribute(s) Type Default Description Characteristic(s) Example
custom_log_fields object - Defines log fields for Custom Logging. ⚠ Inherited by nested blocks. -
Modifiers - - - - -

Examples:

Access Control

The configuration of access control is twofold in Couper: You define the particular type (such as jwt or basic_auth) in definitions, each with a distinct label (must not be one of the reserved names: beta_granted_permissions, beta_required_permission). Anywhere in the server block those labels can be used in the access_control list to protect that block. ⚠ access rights are inherited by nested blocks. You can also disable access_control for blocks. By typing disable_access_control = ["bar"], the access_control type bar will be disabled for the corresponding block context.

All access controls have an option to handle related errors. Please refer to Errors.

Health-Check

The health check will answer a status 200 OK on every port with the configured health_path. As soon as the gateway instance will receive a SIGINT or SIGTERM the check will return a status 500 StatusInternalServerError. A shutdown delay of 5s for example allows the server to finish all running requests and gives a load-balancer time to pick another gateway instance. After this delay the server goes into shutdown mode with a deadline of 5s and no new requests will be accepted. The shutdown timings defaults to 0 which means no delaying with development setups. Both durations can be configured via environment variable. Please refer to the docker document.

Variables

couper

Variable Type Description Example
version string Couper's version number "1.3.1"

env

Environment variables can be accessed everywhere within the configuration file since these references get evaluated at start.

You may provide default values by means of environment_variables in the defaults block:

// ...
   origin = env.ORIGIN
// ...
defaults {
  environment_variables = {
    ORIGIN = "http://localhost/"
    TIMEOUT = "3s"
  }
}

request

Variable Type Description Example
id string Unique request id
method string HTTP method "GET"
headers.<name> string HTTP request header value for requested lower-case key
cookies.<name> string Value from Cookie request header for requested key (⚠ last wins!)
query.<name> list (string) Query parameter values
path_params.<name> string Value from a named path parameter defined within an endpoint path label
body string Request message body
form_body.<name> list (string) Parameter in a application/x-www-form-urlencoded body
json_body various Access JSON decoded message body. Media type must be application/json or application/*+json.
context.beta_granted_permissions list (string) Permissions granted to the requester as yielded by access controls (see e.g. beta_permissions_claim, beta_roles_claim in the jwt block). ["perm1", "perm2"]
context.beta_required_permission string Permission required to perform the requested operation (value of the beta_required_permission attribute of endpoint (or api) block).
context.<name>.<property_name> various Request context containing information from the Access Control.
url string Request URL "https://www.example.com/path/to?q=val&a=1"
origin string Origin of the request URL "https://www.example.com"
protocol string Request protocol "https"
host string Host of the request URL "www.example.com"
port integer Port of the request URL 443
path string Request URL path "/path/to"

The value of context.<name> depends on the type of block referenced by <name>.

For a Basic Auth and successfully authenticated request the variable contains the user name.

For a JWT Block the variable contains claims from the JWT used for Access Control.

For a SAML Block the variable contains

  • sub: the NameID of the SAML assertion
  • exp: optional expiration date (value of SessionNotOnOrAfter of the SAML assertion)
  • attributes: a map of attributes from the SAML assertion

For an OAuth2 AC Block, the variable contains the response from the token endpoint, e.g.

  • access_token: the access token retrieved from the token endpoint
  • token_type: the token type
  • expires_in: the token lifetime
  • scope: the granted scope (if different from the requested scope)

and for OIDC additionally:

  • id_token: the ID token
  • id_token_claims: a map of claims from the ID token
  • userinfo: a map of claims retrieved from the userinfo endpoint

backends

backends.<label> allows access to backend information.

Variable Type Description Example
health object current health state {"error": "", "healthy": true, "state": "healthy"}

backend_request

backend_request holds information about the current backend request. It is only available in a Backend Block, and has the same attributes as a backend request in backend_requests.<label> (see backend_requests below).

backend_requests

backend_requests is an object with all backend requests and their attributes. To access a specific request use the related label. Request and Proxy blocks without a label will be available as default. To access the HTTP method of the default request use backend_requests.default.method .

Variable Type Description Example
id string Unique request id
method string HTTP method "GET"
headers.<name> string HTTP request header value for requested lower-case key
cookies.<name> string Value from Cookie request header for requested key (⚠ last wins!)
query.<name> list (string) Query parameter values
body string Backend request message body
form_body.<name> list (string) Parameter in a application/x-www-form-urlencoded body
json_body various Access JSON decoded message body. Media type must be application/json or application/*+json.
context.<name>.<property_name> various Request context containing claims from JWT used for Access Control or information from a SAML assertion, <name> being the JWT Block's or SAML Block's label and property_name being the claim's or assertion information's name
url string Backend request URL "https://www.example.com/path/to?q=val&a=1"
origin string Origin of the backend request URL "https://www.example.com"
protocol string Backend request protocol "https"
host string Host of the backend request URL "www.example.com"
port integer Port of the backend request URL 443
path string Backend request URL path "/path/to"

backend_response

backend_response represents the current backend response. It is only available in a Backend Block, and has the same attributes as a backend response in backend_responses.<label> (see backend_responses below).

backend_responses

backend_responses is an object with all backend responses and their attributes. Use the related label to access a specific response. Request and Proxy blocks without a label will be available as default. To access the HTTP status code of the default response use backend_responses.default.status .

Variable Type Description Example
status integer HTTP status code 200
headers.<name> string HTTP response header value for requested lower-case key
cookies.<name> string Value from Set-Cookie response header for requested key (⚠ last wins!)
body string The response message body
json_body various Access JSON decoded message body. Media type must be application/json or application/*+json.

Functions

Name Type Description Arguments Example
base64_decode string Decodes Base64 data, as specified in RFC 4648. encoded (string) base64_decode("Zm9v")
base64_encode string Encodes Base64 data, as specified in RFC 4648. decoded (string) base64_encode("foo")
contains bool Determines whether a given list contains a given single value as one of its elements. list (tuple or list), value (various) contains([1,2,3], 2)
default string Returns the first of the given arguments that is not null or an empty string. If no argument matches, the last argument is returned. arg... (various) default(request.cookies.foo, "bar")
join string Concatenates together the string elements of one or more lists with a given separator. sep (string), lists... (tuples or lists) join("-", [0,1,2,3])
json_decode various Parses the given JSON string and, if it is valid, returns the value it represents. encoded (string) json_decode("{\"foo\": 1}")
json_encode string Returns a JSON serialization of the given value. val (various) json_encode(request.context.myJWT)
jwt_sign string jwt_sign creates and signs a JSON Web Token (JWT) from information from a referenced JWT Signing Profile Block (or JWT Block with signing_ttl) and additional claims provided as a function parameter. label (string), claims (object) jwt_sign("myJWT")
keys list Takes a map and returns a sorted list of the map keys. inputMap (object or map) keys(request.headers)
length integer Returns the number of elements in the given collection. collection (tuple, list or map; no object) length([0,1,2,3])
lookup various Performs a dynamic lookup into a map. The default (third argument) is returned if the key (second argument) is not found in the inputMap (first argument). inputMap (object or map), key (string), default (various) lookup({a = 1}, "b", "def")
merge object or tuple Deep-merges two or more of either objects or tuples. null arguments are ignored. An attribute value with a different type than the current value is set as the new value. merge() with no parameters returns null. arg... (object or tuple) merge(request.headers, { x-additional = "myval" })
oauth2_authorization_url string Creates an OAuth2 authorization URL from a referenced OAuth2 AC Block or OIDC Block. label (string) oauth2_authorization_url("myOAuth2")
oauth2_verifier string Creates a cryptographically random key as specified in RFC 7636, applicable for all verifier methods; e.g. to be set as a cookie and read into verifier_value. Multiple calls of this function in the same client request context return the same value. oauth2_verifier()
relative_url string Returns a relative URL by retaining path, query and fragment components. The input URL s must begin with /<path>, //<authority>, http:// or https://, otherwise an error is thrown. s (string) relative_url("https://httpbin.org/anything?query#fragment") // returns "/anything?query#fragment"
saml_sso_url string Creates a SAML SingleSignOn URL (including the SAMLRequest parameter) from a referenced SAML Block. label (string) saml_sso_url("mySAML")
set_intersection list or tuple Returns a new set containing the elements that exist in all of the given sets. sets... (tuple or list) set_intersection(["A", "B", "C"], ["B", D"])
split tuple Divides a given string by a given separator, returning a list of strings containing the characters between the separator sequences. sep (string), str (string) split(" ", "foo bar qux")
substr string Extracts a sequence of characters from another string and creates a new string. The "offset" index may be negative, in which case it is relative to the end of the given string. The "length" may be -1, in which case the remainder of the string after the given offset will be returned. str (string), offset (integer), length (integer) substr("abcdef", 3, -1)
to_lower string Converts a given string to lowercase. s (string) to_lower(request.cookies.name)
to_number number Converts its argument to a number value. Only numbers, null, and strings containing decimal representations of numbers can be converted to number. All other values will produce an error. num (string or number) to_number("1,23"), to_number(env.PI)
to_upper string Converts a given string to uppercase. s (string) to_upper("CamelCase")
unixtime integer Retrieves the current UNIX timestamp in seconds. unixtime()
url_encode string URL-encodes a given string according to RFC 3986. s (string) url_encode("abc%&,123")

Modifiers

Request Header

Couper offers three attributes to manipulate the request header fields. The header attributes can be defined unordered within the configuration file but will be executed ordered as follows:

Modifier Contexts Description
remove_request_headers Endpoint Block, Proxy Block, Backend Block, Error Handler list of request header to be removed from the upstream request.
set_request_headers Endpoint Block, Proxy Block, Backend Block, Error Handler Key/value(s) pairs to set request header in the upstream request.
add_request_headers Endpoint Block, Proxy Block, Backend Block, Error Handler Key/value(s) pairs to add request header to the upstream request.

All *_request_headers are executed from: endpoint, proxy, backend and error_handler.

Response Header

Couper offers three attributes to manipulate the response header fields. The header attributes can be defined unordered within the configuration file but will be executed ordered as follows:

Modifier Contexts Description
remove_response_headers Server Block, Files Block, SPA Block, API Block, Endpoint Block, Proxy Block, Backend Block, Error Handler list of response header to be removed from the client response.
set_response_headers Server Block, Files Block, SPA Block, API Block, Endpoint Block, Proxy Block, Backend Block, Error Handler Key/value(s) pairs to set response header in the client response.
add_response_headers Server Block, Files Block, SPA Block, API Block, Endpoint Block, Proxy Block, Backend Block, Error Handler Key/value(s) pairs to add response header to the client response.

All *_response_headers are executed from: server, files, spa, api, endpoint, proxy, backend and error_handler.

Set Response Status

The set_response_status attribute allows to modify the HTTP status code to the given value.

Modifier Contexts Description
set_response_status Endpoint Block, Backend Block, Error Handler HTTP status code to be set to the client response.

If the HTTP status code ist set to 204, the response body and the HTTP header field Content-Length is removed from the client response, and a warning is logged.

Parameters

Query Parameter

Couper offers three attributes to manipulate the query parameter. The query attributes can be defined unordered within the configuration file but will be executed ordered as follows:

Modifier Contexts Description
remove_query_params Endpoint Block, Proxy Block, Backend Block, Error Handler list of query parameters to be removed from the upstream request URL.
set_query_params Endpoint Block, Proxy Block, Backend Block, Error Handler Key/value(s) pairs to set query parameters in the upstream request URL.
add_query_params Endpoint Block, Proxy Block, Backend Block, Error Handler Key/value(s) pairs to add query parameters to the upstream request URL.

All *_query_params are executed from: endpoint, proxy, backend and error_handler.

server "my_project" {
  api {
    endpoint "/" {
      proxy {
        backend = "example"
      }
    }
  }
}

definitions {
  backend "example" {
    origin = "http://example.com"

    remove_query_params = ["a", "b"]

    set_query_params = {
      string = "string"
      multi = ["foo", "bar"]
      "${request.headers.example}" = "yes"
    }

    add_query_params = {
      noop = request.headers.noop
      null = null
      empty = ""
    }
  }
}

Form Parameter

Couper offers three attributes to manipulate the form parameter. The form attributes can be defined unordered within the configuration file but will be executed ordered as follows:

Modifier Contexts Description
remove_form_params Endpoint Block, Proxy Block, Backend Block, Error Handler list of form parameters to be removed from the upstream request body.
set_form_params Endpoint Block, Proxy Block, Backend Block, Error Handler Key/value(s) pairs to set form parameters in the upstream request body.
add_form_params Endpoint Block, Proxy Block, Backend Block, Error Handler Key/value(s) pairs to add form parameters to the upstream request body.

All *_form_params are executed from: endpoint, proxy, backend and error_handler.

The *_form_params apply only to requests with the POST method and the Content-Type: application/x-www-form-urlencoded HTTP header field.

server "my_project" {
  api {
    endpoint "/" {
      proxy {
        backend = "example"
      }
    }
  }
}

definitions {
  backend "example" {
    origin = "http://example.com"

    remove_form_params = ["a", "b"]

    set_form_params = {
      string = "string"
      multi = ["foo", "bar"]
      "${request.headers.example}" = "yes"
    }

    add_form_params = {
      noop = request.headers.noop
      null = null
      empty = ""
    }
  }
}

Path Parameter

An endpoint label could be defined as endpoint "/app/{section}/{project}/view" { ... } to access the named path parameter section and project via request.path_params.*. The values would map as following for the request path: /app/nature/plant-a-tree/view:

Variable Value
request.path_params.section nature
request.path_params.project plant-a-tree