Environment Variables

A list of environment variables that can be used to configure the application router.

The following table lists the environment variables that you can use to configure the application router. The table also provides a short description of each variable and, where appropriate, an example of the configuration data.

Application Router Configuration Variables

Variable	Description
`httpHeaders`	Configures the application router to return additional HTTP headers in its responses to client requests
`destinations`	Provides information about the available application (microservice) destinations.
`cookies`	Provides cookies that the application router returns to the client in its responses.
`SESSION_TIMEOUT`	Sets the time to trigger an automatic central log out from the User Account and Authentication (UAA) server.
`SEND_XFRAMEOPTIONS`	Sets or changes the `X-Frame-Options` header
`CJ_PROTECT_WHITELIST`	A list of allowed server or domain origins to use when checking for click-jacking attacks.
`WS_ALLOWED_ORIGINS`	A list of the allowed server (or domain) origins that the application router uses to verify requests.
`JWT_REFRESH`	Configures the automatic refresh of the JSON Web Token (JWT) provided by the User Account and Authentication (UAA) service to prevent expiry (default is 5 minutes).
`UAA_SERVICE_NAME`	Specifies the exact name of the UAA service to bind to an application.
`INCOMING_CONNECTION_TIMEOUT`	Specifies the maximum time (in milliseconds) for a client connection. If the specified time is exceeded, the connection is closed.
`TENANT_HOST_PATTERN`	Defines a regular expression to use when resolving tenant host names in the request’s host name.
`COMPRESSION`	Configures the compression of resources before a response to the client.
`SECURE_SESSION_COOKIE`	Configures the enforcement of the `Secure` flag of the application router's session cookie.
`REQUEST_TRACE`	Enables additional traces of the incoming and outgoing requests.
`EXTERNAL_REVERSE_PROXY`	Indicates the use of the application router behind an external reverse proxy outside of the Cloud Foundry domain. For more information, see Customer Header under Headers.
`CORS`	Provides support for cross-origin requests, for example, by allowing the modification of the request header.
`DIRECT_ROUTING_URI_PATTERNS`	Defines a list of URIs that are directed to the routing configuration file (xs-app.json file) of the application router instead of to a specific applicaion's xs-app.json file that is stored in the HTML5 Application Repository. This configuration improves the application loading time and monitoring options.
`EXT_SESSION_MGT`	You can configure external session management. See External Session Management.
`CF_NODEJS_LOGGING_LEVEL`	Sets the minimal logging level of the `cf-nodejs-logging-support` library of the application router.
`STATE_PARAMETER_SECRET`	Enables the use of state parameters to prevent CRFS attacks. If this environment variable is set, the application router creates a state parameter for each initial authorization request. By validating that the authentication server returns the same state parameter in its response, the application server can verify that the response did not originate from a third party.
`HTTP2_SUPPORT`	Enables the application router to start as an HTTP/2 server. Note: To configure HTTP/2 support, you must use Cloud Foundry routes with an HTTP/2 destination protocol. See Configuring HTTP/2 Support in the Cloud Foundry Documentation. As connection-specific header fields aren't supported by the HTTP/2 protocol (see https://datatracker.ietf.org/doc/html/rfc9113), the application router removes such headers automatically when they are returned from a backend to prevent a failure of the HTTP/2 response.
`FULL_CERTIFICATE_CHAIN`	Enables the application router to send the entire chain of certificates provided in the binding of the authentication service (XSUAA or Indentity Authentication) to the backend applications. The certificates are required for mutual TLS authentication (mTLS handshake). See Mutual TLS Authentication (mTLS) and Certificates Handling.

httpHeaders

If configured, the application router sends additional HTTP headers in its responses to a client request. You can set the additional HTTP headers in the <httpHeaders> environment variable. The following example configuration shows how to configure the application router to send two additional headers in the responses to the client requests from the application <myApp>:

cf set-env <myApp> httpHeaders "[ { "X-Frame-Options": "ALLOW-FROM http://acme.com" }, { "Test-Additional-Header": "1" } ]"

or

cf set-env <myApp> httpHeaders '[{ "X-Frame-Options": "ALLOW-FROM http://acme.com" }, { "Test-Additional-Header": "1" }]'

Tip:

To ensure better security of your application set the Content-Security-Policy header. This is a response header which informs browsers (capable of interpreting it) about the trusted sources from which an application expects to load resources. This mechanism allows the client to detect and block malicious scripts injected into the application. A value can be set via the <httpHeaders> environment variable in the additional headers configuration. The value represents a security policy which contains directive-value pairs. The value of a directive is an allowlist of trusted sources.

Usage of the Content-Security-Policy header is considered second line of defense. An application should always provide proper input validation and output encoding.

destinations

The destinations configuration is an array of objects that is defined in the destinations environment variable. A destination is required for every application (microservice) that is part of the business application. The following table lists the properties that can be used to describe the destination:

Destination Environment Variable Properties

Property	Type	Mandatory	Description
`name`	String	Yes	A unique indentifier for the destination
`url`	String	Yes	The Unique Resource Locator for the application (microservice)
`proxyHost`	String	No	The host of the proxy server used in case the request should go through a proxy to reach the destination. Tip: Mandatory if `proxyPort` is defined.
`proxyPort`	String	No	The port of the proxy server used in case the request should go through a proxy to reach the destination. Tip: Mandatory if `proxyHost` is defined.
`forwardAuthToken`	Boolean	No	If true, the OAuth token will be sent to the destination. The default value is “false”. This token contains the user identity, scopes, and some other attributes. The token is signed by the User Account and Authorization (UAA) service so that the token can be used for user-authentication and authorization purposed by back-end services.
`strictSSL`	Boolean	No	Configures whether the application router should reject untrusted certificates. The default value is “true”. Caution: For testing purposes only. Do not use this property in production environments!
`timeout`	Number	No	A positive integer representing the maximum amount of time to wait for a response (in milliseconds) from the specified destination. The default is 30000ms. Tip: The timeout specified here also applies to the logout path, `logoutPath`, if the logout path is defined, for example, in the application's descriptor file `xs-app.json`.
`proxyType`	String	No	Indicates if the destination is used to access applications in private networks (for example, on-premise) or publicly available on the Internet. Possible value: `onPremise`. If `proxyType` is not specified, the default (Internet access) is assumed. Tip: In Cloud environments, if you set the application's destination `proxyType` to `onPremise`, a binding to the SAP BTP connectivity service is required, and the `forwardAuthToken` property must not be set.
`IASDependencyName`	String	No	Configures the name of the Identity Authentication dependency that is used to exchange the Identity Authentication token used for the user authentication at login. If configured, the exchanged token is then also forwarded to the backend applications.
forwardAuthCertificates	Boolean	No	If `true`, the certificates and key of the authentication service are added to the HTTP connection to the destination. The default value is `false`. For more information see: Mutual TLS Authentication (mTLS) and Certificates Handling

If true, the certificates and key of the authentication service are added to the HTTP connection to the destination. The default value is false. For more information see: Mutual TLS Authentication (mTLS) and Certificates Handling

The following example shows a simple configuration for the <destinations> environment variable:

Sample Code:

[
 {
   "name" : "ui5",
   "url" : "https://sapui5.acme.com",
   "proxyHost" : "proxy",
   "proxyPort" : "8080",
   "forwardAuthToken" : false,
   "timeout" : 1200
 }
]

It is also possible to include the destinations in the manifest.yml file, as illustrated in the following example:

Sample Code:


- name: node-hello-world 
  memory: 100M 
  path: web 
  env: destinations: > 
       [
        {"name":"ui5", "url":"https://sapui5.acme.com"} 
       ]

Additional cookies

If configured, the application router will send additional cookies in its responses to the client. Additional cookies can be set in the <COOKIES> environment variable.

Example of configuration for cookies in the manifest.yml:

Sample Code:

env:
   COOKIES: >
        { "SameSite":"None" }

In this example, the application router sets the SameSite cookie attribute to None for the JSESSIONID cookie in the responses to the client.

Note:

Currently, only the Same Site cookie is supported.

SESSION_TIMEOUT

You can configure the triggering of an automatic central log-out from the User Account and Authentication (UAA) service if an application session is inactive for a specified time. A session is considered to be inactive if no requests are sent to the application router. The following command shows how to set the environment variable <SESSION_TIMEOUT> to 40 (forty) minutes for the application <myApp1>:

cf set-env <myApp1> SESSION_TIMEOUT 40

Note:

You can also set the session timeout value in the application's manifest.yml file, as illustrated in the following example:

Sample Code:

- name: myApp1 
  memory: 100M
  path: web
  env:
    SESSION_TIMEOUT: 40

Tip:

If the authentication type for a route is set to "xsuaa" (for example, "authenticationType": "xsuaa"), the application router depends on the UAA server for user authentication, and the UAA server might have its own session timeout defined. To avoid problems caused by unexpected timeouts, it is recommended that the session timeout values configured for the application router and the UAA are identical."

SEND_XFRAMEOPTIONS

By default, the application router sends the X-Frame-Options header with the value “SAMEORIGIN”. You can change this behavior either by disabling the sending of the default header value (for example, by setting SEND_XFRAMEOPTIONS environment variable to false) or by overriding the value, for example, by configuring additional headers (with the <httpHeaders> environment variable).

The following example shows how to disable the sending of the X-Frame-Options for a specific application, myApp1:

cf set-env <myApp1> SEND_XFRAMEOPTIONS false

CJ_PROTECT_WHITELIST

The <CJ_PROTECT_WHITELIST> specifies a list of origins (for example, host or domain names) that do not need to be protected against click-jacking attacks. This list of allowed host names and domains are used by the application router's allowlist service to protect XS advanced applications against click-jacking attacks. When an HTML page needs to be rendered in a frame, a check is done by calling the allowlist service to validate if the parent frame is allowed to render the requested content in a frame. The check itself is provided by the allowlist service

The following example shows how to add a host name to the click-jacking protection allowlist for the application, myApp1:

cf set-env <myApp1> CJ_PROTECT_WHITELIST {<protocol>, <hostname>, <portNr>}

The content is a JSON list of objects with the properties listed in the following table:

Allowlist of Host and Domain Names

Property	Type	Mandatory	Description
`protocol`	String	No	URI scheme, for example “HTTP”.
`host`	String	Yes	A valid host name, for example, `acme.com.hostname`, or a domain name defined with an asterisk () `.acme.com`.
`port`	String/Number	No	Port string or number containing a valid port.

Note:

Matching is done against the properties provided. For example, if only the host name is provided, the allowlist service matches all schemata and protocols.

xs set-env <myApp1> CJ_PROTECT_WHITELIST {<*.acme.com>}

WS_ALLOWED_ORIGINS

When the application router receives an upgrade request, it verifies that the origin header includes the URL of the application router. If this is not the case, then an HTTP response with status 403 is returned to the client. This origin verification can be further configured with the environment variable <WS_ALLOWED_ORIGINS>, which defines a list of the allowed origins the application router uses in the verification process.

Note:

The structure of the <WS_ALLOWED_ORIGINS> variable is the same as the variable <CJ_PROTECT_WHITELIST>.

cf set-env <myApp1> WS_ALLOWED_ORIGINS {<*.acme.com>}

JWT_REFRESH

The JWT_REFRESH environment variable is used to configure the application router to refresh a JSON Web Token (JWT) for an application, by default, 5 minutes before the JWT expires, if the session is active.

cf set-env <myApp1> JWT_REFRESH 1

If the JWT is close to expiration and the session is still active, a JWT refresh will be triggered <JWT_REFRESH> minutes before expiration. The default value is 5 minutes. To disable the automatic refresh, set the value of <JWT_REFRESH> to 0 (zero).

UAA_SERVICE_NAME

The UAA_SERVICE_NAME environment variable enables you to configure an instance of the User Account and Authorization service for a specific application, as illustrated in the following example:

cf set-env <myApp1> UAA_SERVICE_NAME <myUAAServiceName>

Note:

The details of the service configuration are defined in the <VCAP_SERVICES> environment variable, which is not configured by the user.

INCOMING_CONNECTION_TIMEOUT

The INCOMING_CONNECTION_TIMEOUT environment variable enables you to set the maximum time (in milliseconds) allowed for a client connection, as illustrated in the following example:

cf set-env <myApp1> INCOMING_CONNECTION_TIMEOUT 60000

If the specified time is exceeded, the connection is closed. If INCOMING_CONNECTION_TIMEOUT is set to zero (0), the connection-timeout feature is disabled. The default value for INCOMING_CONNECTION_TIMEOUT is 120000 ms (2 min).

TENANT_HOST_PATTERN

The TENANT_HOST_PATTERN environment variable enables you to specify a string containing a regular expression with a capturing group. The requested host is matched against this regular expression. The value of the first capturing group is used as the tenant Id. as illustrated in the following example:

cf set-env <myApp1> TENANT_HOST_PATTERN

COMPRESSION

The COMPRESSION environment variable enables you to configure the compression of resources before a response to the client, as illustrated in the following example:

cf set-env <myApp1> COMPRESSION

Here is a complete example of the compression environment variable:

Sample Code:

 env:
   COMPRESSION: >
        { 
	  "enabled": true,
	  "minSize": 2048,
	  "compressResponseMixedTypeContent": true
	  }

SECURE_SESSION_COOKIE

The SECURE_SESSION_COOKIE can be set to true or false. By default, the Secure flag of the session cookie is set depending on the environment the application router runs in. For example, when the application router is running behind a router that is configured to serve HTTPS traffic, then this flag will be present. During local development the flag is not set.

Note:

If the Secure flag is enforced, the application router will reject requests sent over unencrypted connections.

The following example illustrates how to set the SECURE_SESSION_COOKIE environment variable:

cf set-env <myApp1> SECURE_SESSION_COOKIE true

REQUEST_TRACE

You can enable additional traces of the incoming and outgoing requests by setting the environment variable <REQUEST_TRACE>“true”. If enabled, basic information is logged for every incoming and outgoing request to the application router.

The following example illustrates how to set the REQUEST_TRACE environment variable:

cf set-env <myApp1> REQUEST_TRACE true

Tip:

This is in addition to the information generated by the Node.js package @sap/logging that is used by the XS advanced application router.

CORS

The CORS environment variable enables you to provide support for cross-origin requests, for example, by allowing the modification of the request header. Cross-origin resource sharing (CORS) permits Web pages from other domains to make HTTP requests to your application domain, where normally such requests would automatically be refused by the Web browser's security policy.

Cross-origin resource sharing (CORS) is a mechanism that allows restricted resources on a Web page to be requested from another domain (protocol and port) outside the domain (protocol and port) from which the first resource was served. The CORS configuration enables you to define details to control access to your application resource from other Web browsers. For example, you can specify where requests can originate from or what is allowed in the request and response headers. The following example illustrates a basic CORS configuration:

[
  {
      "uriPattern": "^\route1$",
      "allowedMethods": [
        "GET"
      ],
      "allowedOrigin": [
        {
          "host": "host.acme.com",
          "protocol": "https",
          "port": 345
        }
      ],
      "maxAge": 3600,
      "allowedHeaders": [
        "Authorization",
        "Content-Type"
      ],
      "exposeHeaders": [
        "customHeader1",
        "customHeader2"
      ],
      "allowedCredentials": true
    }
]

The CORS configuration includes an array of objects with the following properties, some of which are mandatory:

Available Settings for CORS Options

CORS Property	Type	Mandatory	Description
`uriPattern`	String	Yes	A regular expression (RegExp) representing the source routes to which the CORS configuration applies. To ensure that the RegExp matches the complete path, surround it with ^ and $,f or example, `"uriPattern": "^\route1$"`. Defaults: none
`allowedOrigin`	Array	Yes	A comma-separated list of objects each of which contains a host name, port and protocol that are allowed by the server, for example: `[{“host”: "www.acme.com"}]` or `[{“host”: “.acme.com”}]`. Note: Matching is case-sensitive. In addition, if no port or protocol is specified, the default is `“”`. The default configuration is: `[{“host”: ""}]`, which means that the server allows any origin to access the resource.
`allowedMethods`	Array	No	A comma-separated list of HTTP methods that are allowed by the server, for example, `“GET”, “POST”`. If `allowMethods` is defined but no method is specified, the default `“GET”, “POST”, “HEAD”, “OPTIONS”` (all) applies. Tip: The specified methods must be upper-case, for example,`GET`. Matching of the method type is case-sensitive.
`allowedHeaders`	Array	No	A comma-separated list of request headers that are allowed by the server. the default values are as follows: `[“Origin”, “Accept”, “X-Requested-With”, “Content-Type”, “Access-Control-Request-Method”, “Access-Control-Request-Headers”]`.
`maxAge`	String	No	A single value specifying the length of time (in seconds) a preflight request should be cached for. A negative value that prevents CORS filter from adding this response header to the pre-flight response. If `maxAge` is defined but no value is specified, the default time of “1800” seconds applies.
`exposeHeaders`	Array	No	A comma-separated list of response headers that are allowed to be exposed. If `exposeHeaders` is defined but no response header is specified for exposure, no default value is supplied.
`allowedCredentials`	Boolean	No	A Boolean flag that indicates whether the specified resource supports user credentials. The default setting is “true”.

It is also possible to include the CORS configuration in either the manifest.yml or the manifest-op.yml file. The code in the following example enables the CORS configuration for any route with a source URI pattern that matches the RegExp “^\route1$”:

Sample Code:

CORS Configuration in the manifest.yml File

- name: node-hello-world
  memory: 100M
  path: web
  env:
    CORS: >
      [
        {
          "allowedOrigin":[
                            {
                                "host":"my_host",
                                "protocol":"https"
                            }
                          ],
          "uriPattern":"^/route1$"
        }

DIRECT_ROUTING_URI_PATTERNS

With the direct routing URI patterns configuration, you can define a list of URIs that are directed to the routing configuration file (xs-app.json file) of the application router instead of to a specific application's xs-app.json file that is stored in the HTML5 Application Repository. This configuration improves the application loading time and monitoring options because it prevents unnecessary calls to the HTML5 Application Repository.

The configuration is an array of strings or regular expressions. You have to provide only the first segment in the URL, after the approuter host. For example, for the URL https://<approuter-host>/route1/index.html, you enter route1 in the direct routing URI patterns array.

Sample Code:


 env:
    DIRECT_ROUTING_URI_PATTERNS: >
      ["route1", "^route2$", "route3"]

`CF_NODEJS_LOGGING_LEVEL`

With the CF_NODEJS_LOGGING_LEVEL variable, you can set the minimal logging level of the cf-nodejs-logging-support library of the application router. The following levels are available:

off
error
warn
info
verbose
debug
silly

The default value is error.

Here is a sample content for the CF_NODEJS_LOGGING_LEVEL environment variable:

Sample Code:

env:
    CF_NODEJS_LOGGING_LEVEL: "debug"

Note:

The application router also uses the @sap/logging library. To configure the log level for this library, you use the XS_APP_LOG_LEVEL environment variable.

Related Information

Application Router

Routing Configuration File

Files

environment-variables-ba52705.md

Latest commit

History

environment-variables-ba52705.md

File metadata and controls

Environment Variables

Note:

httpHeaders

Tip:

destinations

Tip:

Tip:

Caution:

Tip:

Tip:

Sample Code:

Sample Code:

Additional cookies

Sample Code:

Note:

SESSION_TIMEOUT

Note:

Sample Code:

Tip:

SEND_XFRAMEOPTIONS

CJ_PROTECT_WHITELIST

Note:

WS_ALLOWED_ORIGINS

Note:

JWT_REFRESH

UAA_SERVICE_NAME

Note:

INCOMING_CONNECTION_TIMEOUT

TENANT_HOST_PATTERN

COMPRESSION

Sample Code:

SECURE_SESSION_COOKIE

Note:

REQUEST_TRACE

Tip:

CORS

Note:

Tip:

Sample Code:

DIRECT_ROUTING_URI_PATTERNS

Sample Code:

CF_NODEJS_LOGGING_LEVEL

Sample Code:

Note:

`CF_NODEJS_LOGGING_LEVEL`