Variables

The configuration file allows the use of some predefined variables. There are two phases when those variables get evaluated. The first phase is at config load which is currently related to env and simple function usage. The second evaluation will happen during the request/response handling.

• env are the environment variables.
• request is the client request.
• backend_requests contains all modified backend requests.
• backend_responses contains all original backend responses.

couper

Variable	Type	Description	Example
version	string	Couper's version number.	"1.9.2"
environment	string	The environment Couper currently runs in.	"prod"

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.granted_permissions	list (string)	Permissions granted to the requester as yielded by access controls (see e.g. permissions_claim, roles_claim in the jwt block).	["perm1", "perm2"]
context.required_permission	string	Permission required to perform the requested operation (value of the 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 block 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 beta_oauth2 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 an oidc block additionally:

• id_token: The ID token.
• id_token_claims: A map of claims from the ID token.
• userinfo: A map of properties retrieved from the userinfo endpoint (if the recommended endpoint is available).

beta_token_response

Only available in the beta_token_request block context, beta_token_response allows access to the current token response (see backend_responses for available properties).

backends

backends.<label> allows access to backend information.

Variable	Type	Description	Example
health	object	The current health state.	{"error": "", "healthy": true, "state": "healthy"}
beta_tokens.<token_request_name>	string	The token obtained by the token request with name <token_request_name>.
beta_token	string	The token obtained by the token request with name "default", if configured.

backend

Only available in the backend block context, backend allows access to the current backend information (see backends for available properties).

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.

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