One-Shot Configuration

Airlock Gateway target application/service mapping configuration

This is about the mapping of the protected target application/service (and not about the Airlock IAM mapping).

The following form fields need to be configured to activate one-shot authentication flow on an Airlock Gateway mapping (main mapping tab):

In the "Access" area:

  • set "Denied access URL" to e.g. /auth/login-oneshot
  • Restricted to Roles: Restrict access to the desired role(s): e.g. serviceAbc
  • Authentication flow: choose One-Shot

In the "Application" area:

Check if the application requires session handling. If not, "session handling" can be set to Sessionless.


Airlock Gateway IAM mapping configuration

To allow one-shot requests on Airlock IAM, the corresponding allow rule must be enabled on the IAM mapping:


See Airlock Gateway for Airlock IAM configuration for further information on the IAM mapping configuration.

IAM One-Shot end-point configuration

Airlock IAM handles one-shot requests in a different way than redirect requests: The Airlock Gateway sends the one-shot requests to IAM end-point 'login-oneshot' (instead of 'check-login' for redirect workflow).

  • The one-shot end-point is configured as follows in IAM:
  • Loginapp >> Airlock One-Shot Authentication
  • Define the target applications or services to be protected.
  • For each target application, the following settings are specific for one-shot:
    • Credential Extractor: specifies how to extract a credential (e.g. a token, a ticket, or a header containing information about the authenticated user) from the HTTP request.
    • Authenticator: specifies how to check whether the credential is valid and thus whether the request is authenticated
    • Failure Responses (error mapper): specifies how to respond to the HTTP Client if the request is not authenticated
  • All other properties (ID propagator, URL pattern, etc.) are the same as in normal target applications.

Authentication workflow

The configured elements mentioned above (Credential Extractor, Authenticator, Failure Responses) are used as follows:

  1. The credential extractor extracts a credential (authentication information) from the HTTP request. Depending on the credential extractor, you have to choose One-Shot or One-Shot with body in the Airlock Gateway (WAF) IAM mapping configuration. In case the credential extraction was not successful, the error mapper (Failure Responses) defines the response that is sent to the client. Otherwise, the workflow continues with the next step.
  2. The extracted credential is checked using the configured authenticator. The credential must be compatible with that authenticator. The credential type produced is documented in the extractor plugin and the authenticator plugin usually documents the supported credential types. In case of authentication failures, the configured behavior of the error mapper (Failure Responses) is executed. In case none of the error types match the given authentication failure type, the default authentication behavior is selected and executed. If authentication is successful, the workflow continues with the next step.
  3. The roles granted by the authenticator are matched against the required roles (a property on the target application - see group Roles Processing) after applying any role transformation rules.
  4. Access is granted and the workflow proceeds to the next step if at least one of the required roles is granted by the authenticator. Otherwise, the error mapper (Failure Responses) defines how to respond to the client.

  5. Eventually, the identity propagator adds identity information (e.g. a JWT header) to the response and the roles using the Airlock Gateway Control-API (CAPI) such that the Gateway can forward the "temporarily stopped" request to the back-end.

Details on One-Shot specific Airlock Gateway Control API commands

In the one-shot workflow, IAM provides the results of the authentication to Airlock Gateway using the Gateway Control API. Among other settings, IAM defines how the Airlock Gateway should proceed with the one-shot workflow.

It can choose the command 'CONTINUE' or 'FINAL_RESPONSE' (see Airlock Gateway manual for details):

  • FINAL_RESPONSE: Airlock Gateway responds with the answer as provided by IAM, i.e. with the status code, body, etc. that are set in the IAM response.
  • CONTINUE: The 'usual' Airlock Gateway workflow is continued, i.e. Airlock Gateway checks if the required roles are present, checks deny rules, etc., and responds accordingly. For example, if the user does not have the required roles, Airlock Gateway responds with a 403. This is completely unrelated to the response generated by IAM.

Example: Authenticate HTTP request with JWT


  • The HTTP client sends a token, e.g. a JSON Web Token (JWT) in a header to authenticate the client
  • Airlock Gateway/IAM use the one-shot flow to validate the token and extract user information from it
  • Airlock IAM may optionally perform a lookup in the user directory (LDAP, DB, ...) to perform additional checks or add more information

Configuration hints:

  • Credential Extractor: use plugin HTTP Header Token Extractor (as SSO Credential)
    • Header Name: e.g.  "Authorization"
    • Decoder: e.g. "JWT Ticket Decoder"
    • the ticket decoder, such as JWT Ticket Decoder
    • all other properties according to the plugin documentation
  • Authenticator: plugin "Lookup and Accept Authenticator" may be used to look up the user in the directory