The control API command HTTP_BASIC_AUTH allows adding a basic authentication header to an Airlock Gateway session. In order to propagate the authentication header to the back-end application, the option "SSO credential propagation" on the mapping must be set to "Basic-Auth". HTTP Basic-Auth is a simple way of signing in the user on the back-end application (single sign-on).
The command syntax is:
;; HTTP_BASIC_AUTH
basic-auth-command = basic-auth-command-name "=" basic-auth-command-value
basic-auth-command-name = "HTTP_BASIC_AUTH"
basic-auth-command-value = basic-auth-definitions
basic-auth-definitions = basic-auth-definition [ "," basic-auth-definitions ]
basic-auth-definition = basic-auth-value [ "@" mapping-name ]
;at this place 'basic-auth-value' must be percent encoded
Because Airlock Gateway applies Base64 encoding when sending the basic authentication to the back-end, the basic-auth-definition must not be Base64 encoded. Otherwise basic authentication on the back-end application would fail. If no mapping name is provided in basic-auth-definition the scope of the definition is global, i.e., it is valid on all mappings. Since a back-end request may only contain a single basic authentication header, global definitions will only be added to a back-end request if no mapping-specific definition is available. An existing basic authentication header is removed from an Airlock Gateway session if the basic-auth-value is empty.
Example:
The pseudo code examples below show how to set the HTTP basic authentication header using the control API.
Pseudo code:
response.header="Set-Cookie: AL_CONTROL="+URL_Encode("HTTP_BASIC_AUTH="+URL_Encode(UTF8_Encode("username@domainname:password"))
+"@mapping1")
Results in:
Set-Cookie: AL_CONTROL=HTTP_BASIC_AUTH%3Dusername%2540domainname%253Apassword%40mapping1
Pseudo code:
response.header="Set-Cookie: AL_CONTROL="+URL_Encode("HTTP_BASIC_AUTH="+URL_Encode(UTF8_Encode("domainname\\username:password"))
+"@mapping2")
Results in:
Set-Cookie: AL_CONTROL=HTTP_BASIC_AUTH%3Ddomainname%255Cusername%253Apassword%40mapping2
Pseudo code:
response.header="Set-Cookie: AL_CONTROL="+URL_Encode("HTTP_BASIC_AUTH="+URL_Encode(UTF8_Encode("dbuser:enth43mm"))+"@private,"
Results in:
+URL_Encode(UTF8_Encode("admin:mypwd"))+"@mapping3")
Set-Cookie: AL_CONTROL=HTTP_BASIC_AUTH%3Ddbuser%253Aenth43mm%40private%2Cadmin%253Amypwd%40mapping3
In the last example, user dbuser gets password enth43mm for the mapping private and user admin gets password mypwd for the mapping mapping3.
The examples shown above use the pseudo function UTF8_Encode(). Airlock Gateway only performs a URL_Decode() and does not require UTF-8 encoding. However, the back-end application might require additional encodings, such as UTF-8 or ISO-8859-1.