Authorization of a user session is controlled by adding and removing roles and their corresponding timeouts. Access to a back-end application requiring a certain role is granted by adding this role to the user's session. There are three commands to add, remove and set roles in a user session:
ADD_CREDENTIALS: add the roles listed in the command valueREMOVE_CREDENTIALS: remove the roles listed in the command valueSET_CREDENTIALS: remove all existing roles and set those listed in the command value
Each time roles are added to a session, by default Airlock Gateway automatically changes the session cookie to prevent session fixation and similar attacks.
The command syntax is:
;; SET_CREDENTIALS, ADD_CREDENTIALS, REMOVE_CREDENTIALS
credential-command = credential-command-name "=" credential-command-value
credential-command-name = "SET_CREDENTIALS" | "ADD_CREDENTIALS" | "REMOVE_CREDENTIALS"
credential-command-value = credential-definitions
;at this place 'credential-definitions' must be percent encoded
credential-definitions = credential-definition [ "," credential-definitions ]
credential-definition = credential-name [ ":" credential-timeout [ ":" credential-lifetime [ ":" keep-id-flag ] ] ]
credential-name = 1*ALPHANUM
credential-timeout = value-in-seconds
credential-lifetime = value-in-seconds
keep-id-flag = "K"
value-in-seconds = 1*DIGIT
ALPHANUM = ALPHA | DIGIT
The credential-timeout defines how long an idle session holds this specific role. If the specified timeout is 0 or if no timeout is specified at all, the configured session timeout is used. Airlock Gateway support recommends to use a short session timeout which will be extended by one or more longer credential-timeouts after successful authentication.
The credential-lifetime can be set additionally to the credential-timeout. If the specified lifetime is 0 or if no lifetime is specified at all, the configured session lifetime is used. The lifetime defines the longest possible use of a role. After this time the role will be removed. A credential-timeout with longer validity will not extend the credential-lifetime. To set the credential-lifetime and use the configured session timeout as the credential-timeout, use the value 0 for the credential-timeout, e.g. "test:0:300". The credential-definitions "test", "test:0" and "test:0:0" are equivalent.
Lifetime settings (system session lifetime and credential-lifetime) are inelastic limitations. They ensure an upper limit of the access time.
The keep-id-flag indicates that it's not necessary to change the session cookie when adding the role. This flag must be used with caution, because when used incorrectly, session fixation and similar attacks are possible.
To use the keep-id flag for a role but still use the configured session timeout for credential-timeout and the configured session lifetime for credential-lifetime, use the value 0 for the credential-timeout and credential-lifetime, e.g. "test:0:0:K".
For REMOVE_CREDENTIALS the credential-timeout setting, the credential-lifetime setting and the keep-id flag have no meaning.
Example:
The pseudo code example below shows how to set the three roles "public:180", "employee:0:64800", and "secret:600:3600" using the control API.
Pseudo code:
response.header="Set-Cookie: AL_CONTROL="+URL_Encode("SET_CREDENTIALS="+URL_Encode("public:180,employee:0:64800,secret:600:3600")) Results in:
Results in:
Set-Cookie: AL_CONTROL=SET_CREDENTIALS%3Dpublic%253A180%252Cemployee%253A0%253A64800%252Csecret%253A600%253A360