Session tracking with bearer tokens

Goal

Session tracking can be accomplished by exchanging HTTP cookies or bearer tokens between the REST client and Airlock Gateway (WAF). In this example, we use the bearer token variant to work with an Airlock IAM installation.

  • The REST client receives a bearer token from the Gateway (WAF) in the "Access-Token" header:

    • Airlock Gateway (WAF) HTTP response header example

    HTTP/1.1 401
[other headers omitted]
Access-Token: fRRyOP-XTJtEcIQbwdzb_IQw1JfTo3kWRfGDmrfPEVletSZmM6s7iZcJbvO0capQHrOX3cLKqmFfkD2Dr0rwVA
...
  • The REST client must return the value of the header as bearer token with every request in the authorization header:

    • HTTP request from REST client example

    POST /auth/rest/public/authentication/password/check HTTP/1.1
[other headers omitted]
Authorization: Bearer fRRyOP-XTJtEcIQbwdzb_IQw1JfTo3kWRfGDmrfPEVletSZmM6s7iZcJbvO0capQHrOX3cLKqmFfkD2Dr0rwVA
...

Initial thoughts

Note that Airlock Gateway (WAF) may send back a new bearer token at any point in the conversation. The REST client must always use the newest value. This is done to mitigate certain types of attacks.

All following procedures are exemplary and will vary according to your setup or needs.

Instruction (part 1) - Configure Airlock IAM for session binding with header token

  1. Go to:
    Loginapp > REST API Configuration > Authentication API Settings (Flow-based)
  2. Enable Session Binding With Header Token. Change the header name if desired.

Instruction (part 2) - Configure Airlock Gateway for bearer token session tracking

  1. Go to:
    Application Firewall > Reverse Proxy
  2. In the mapping detail page of the Gateway installation, select the Expert Settings tab.
  3. Enable the Security Gate expert settings using the radio button.
  4. To use default header names, add:
    5. # Security Gate Expert Settings for Bearer Token Session Tracking: Default Header Names
    Session.Tracking.HeaderToken.Enable                      "TRUE"
  5. For each connected back-end mapping:
    Open the mapping detail page, enable the Security Gate expert settings using the radio button and add session tracking as follows:
    6. # Security Gate Expert Settings for Bearer Token Session Tracking: Default Header Names
    Session.Tracking.HeaderToken.Enable                      "TRUE"

Instruction (optional) - Use custom settings

  1. In the mapping detail page of the IAM installation:
    Use the following expert settings as a template to change the default header names Access-Token and Authorization or to extract the token if it is not provided as a plain header value.

    2. Security Gate Expert Settings for Bearer Token Session Tracking: Custom Settings

    Session.Tracking.HeaderToken.Enable                      "TRUE"
Session.Tracking.HeaderToken.Response.Header.Name                 "Access-Token"
Session.Tracking.HeaderToken.Request.Header.Name                  "Authorization"
Session.Tracking.HeaderToken.Request.Header.Value.Pattern         "^Bearer ([[:graph:]]+)$"
Session.Tracking.HeaderToken.Request.Header.Value.IgnoreCase      "TRUE"
Session.Tracking.HeaderToken.Request.Header.Value.Template        "$1"
  2. For each connected back-end mapping:
    Open the mapping detail page and use the following expert settings as a template:

    3. Security Gate Expert Settings for Bearer Token Session Tracking: Custom Settings

    Session.Tracking.HeaderToken.Enable                      "TRUE"
Session.Tracking.HeaderToken.Request.Header.Name                  "Authorization"
Session.Tracking.HeaderToken.Request.Header.Value.Pattern         "^Bearer ([[:graph:]]+)$"
Session.Tracking.HeaderToken.Request.Header.Value.IgnoreCase      "TRUE"
Session.Tracking.HeaderToken.Request.Header.Value.Template        "$1"

Known errors and solutions (optional)

This section will describe the problem or problems, why they apply and the way to solve or to work around the problem.