Setting HTTP headers

Each user session on Airlock Gateway has its own header store. The headers in the header store are added to HTTP requests sent to the back-end server. The control API commands introduced below allow modification of the headers in the header store. Optionally, the HTTP headers can be restricted to certain mappings.

  • ADD_HEADERS: add HTTP headers to the header store of the session
  • REMOVE_HEADERS: remove HTTP headers with the specified header name from the header store of the session (the header value is ignored).
  • SET_HEADERS: clear the header store of the session before adding new HTTP headers to it.

The command syntax is:

header-command            = header-command-name "=" header-command-value
header-command-name       = "SET_HEADERS" | "ADD_HEADERS" | "REMOVE_HEADERS"
header-command-value      = header-command-for-mapping-values
header-command-for-mapping-values = [ header-command-for-mapping-value [ "," header-command-for-mapping-values ] ]
header-command-for-mapping-value = header-definition [ "@" mapping-name ]
                                   ;at this place 'header-definition' must be percent encoded

header-definition         = header-name ":" *SP header-value

The header store consists of a list of global headers and separate lists of mapping-specific headers. Using the "@mapping-name" notation, it is possible to restrict the scope of headers to a specific mapping. If no mapping-name is provided, the header is set globally.

For a back-end server request, the matching mapping-specific headers are sent, together with the global headers that have different names than the matching mapping-specific headers.

Don't use SET_HEADERS to replace headers, because it clears the header store. Use REMOVE_HEADERS followed by ADD_HEADERS instead.

These control API commands should not be used to add cookies to the user's cookie store due to the following reasons:

  • The resulting cookies would end up in Airlock Gateway's header store and not in the cookie store. Cookies in the header store are not handled according to the application cookie section.
  • There is a risk of adding the "Cookie" header more than once.
  • The same cookie might exist twice, once in the cookie store and once in the header store. Depending on back-end behaviour, strange errors might occur.

Instead, standard API commands of the applied programming language should be used to create the cookies. By doing this, the cookies are correctly added to Airlock Gateway's cookie store and not to the header store. More information about Airlock Gateway's cookie handling is available in the application cookies section.

The pseudo code example below shows how to add HTTP headers using the control API:

Pseudo code:

response.header="Set-Cookie: AL_CONTROL="+URL_Encode("ADD_HEADERS="+URL_Encode("X-Auth-Header: jsmith")+"@mapping1,"+URL_Encode("X-Auth2-Header: john_smith")+"@mapping2")

Results in:

Set-Cookie: AL_CONTROL=ADD_HEADERS%3DX-Auth-Header%253A%2520jsmith%40mapping1%2CX-Auth2-Header%253A%2520john_smith%40mapping2

In the example, the HTTP header "X-Auth-Header: jsmith" is added for all back-end requests on mapping mapping1. The HTTP header "X-Auth2-Header: john_smith" is added for back-end requests on mapping mapping2.