One-shot authentication with authenticators

This article explains how to configure one-shot authentication using authenticators in Airlock IAM. This is the legacy method for configuring one-shot authentication.

  • Dedicated endpoint: /login-oneshot
 
Notice

If you are still working with one-shot based on authenticators, you should replace this legacy approach as soon as the flow-based approach supports your authentication mechanism. For more information, see One-shot authentication with flows.

To configure one-shot based on authenticators, perform the next steps:

  • Loginapp >> 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) 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 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.

Use case: Authenticate HTTP request with JWT

Description of the use case:

  • The HTTP client sends a token, e.g. a JSON Web Token (JWT) in a header to authenticate the client.
  • Airlock Gateway/IAM uses 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 the 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