Using bearer tokens for session tracking

Instead of exchanging HTTP cookies between the REST client and Airlock Gateway (WAF), this variant is based on so-called bearer tokens.

  • The REST client receives a bearer token from the Gateway (WAF) in the X-Access-Token header (name can be configured).
  • The REST client must send the value of the header back as a bearer token with every request in the Authorization header

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.

Airlock Gateway (WAF) HTTP response header example

HTTP/1.1 401
[other headers omitted]
X-Access-Token: fRRyOP-XTJtEcIQbwdzb_IQw1JfTo3kWRfGDmrfPEVletSZmM6s7iZcJbvO0capQHrOX3cLKqmFfkD2Dr0rwVA
...

HTTP request from REST client example

POST /auth/rest/public/authentication/password/check HTTP/1.1
[other headers omitted]
Authorization: Bearer fRRyOP-XTJtEcIQbwdzb_IQw1JfTo3kWRfGDmrfPEVletSZmM6s7iZcJbvO0capQHrOX3cLKqmFfkD2Dr0rwVA
...
  • IAM Configuration for Bearer Token Session Tracking
    • Loginapp >> Authentication Flows: enable Session Binding With Header Token.

      • Note that with Airlock Gateway 7.4 (and newer), this feature can be entirely configured on Airlock Gateway and the feature does not have to be enabled in Airlock IAM.

      A corresponding configuration in the mapping could look like the following:

      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"
  • Airlock Gateway (WAF) Configuration for Bearer Token Session Tracking
    • In the IAM mapping's Security Gate Expert Settings add:

      • Session.Tracking.ExternalToken.Enable "TRUE"

      Change other session tracking settings according to the Airlock Gateway (WAF) manual.

  • To change the default header names X-Access-Token and Authorization use the following expert settings as a template: Security Gate Expert Settings for Bearer Token Session Tracking:

    • Custom Header Names

    Session.Tracking.ExternalToken.Enable                     "TRUE"
Session.Tracking.ExternalToken.Request.Header.Pattern     "^Authorization: Bearer ([[:graph:]]+)$"
Session.Tracking.ExternalToken.Request.Header.IgnoreCase  "TRUE"
Session.Tracking.ExternalToken.Request.Header.Template    "$1"
Session.Tracking.ExternalToken.Response.Header.Pattern    "^X-Access-Token: ([[:graph:]]+)$"
Session.Tracking.ExternalToken.Response.Header.IgnoreCase "TRUE"
Session.Tracking.ExternalToken.Response.Header.Template   "$1"
  • On the back-end mappings, also enable session tracking: Security Gate Expert Settings for Bearer Token Session Tracking:

    • Default Header Names

    Session.Tracking.ExternalToken.Enable                     "TRUE"
  • To use a custom header (instead of Authorization) use the following expert settings as a template: Security Gate Expert Settings for Bearer Token Session Tracking:

    • Custom header names

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