User representation – representee configuration in the Loginapp REST API

This article shows how to configure the representee side of the user representation feature in the Loginapp REST API.


The user representation feature involves two Airlock IAM instances:

  • The representer side
  • The representee side

Important conceptual information about the user representation feature can be found in User representation.

This configuration instruction is about the representee side only.

The representee-IAM authenticates the representee by verifying the representation SSO ticket sent by the representer-IAM.

  • There are two possibilities how this can be achieved:
  • Dedicated auth flow – add a new authentication flow that accepts the representation SSO ticket.
  • Existing auth flow(s) – modify one or more existing authentication flows to accept the representation SSO ticket as an alternative.


  • Information to decode and verify the representation SSO ticket sent by the representer IAM must be available (public key, encoding format, etc.).
  • Either of the license bundles IDM or AVALOQ must be licensed.

Instructions - dedicated auth flow

To create a new flow that accepts the representation SSO ticket, do the following:

  1. Go to:
  2. Loginapp >> Applications and Authentication >> Applications

  3. Add a new Target Application with the application ID represented.
  4. Add an Authentication Flow with the Representation SSO Ticket Identifying Step.
    • Configure the step according to the representer configuration.
    • As Ticket Extractor It is recommended to use Loginapp UI SSO Ticket Extractor plugin. It works best with the Loginapp UI which sends the SSO ticket in HTTP header X-IAM-SSO-Ticket.
    • When choosing the Accepted SSO Tickets Repository, please consider the security notice below.
    • Make sure the flow grants the tags required to access the intended target application(s) and/or protected self-service(s). Note, that tags can also be granted based on ticket attributes - see property Ticket Tag Extractors.
    • Enable the check box Allow Locked Users to allow the representation of locked users.
    • Add other authentication steps to the flow if required.
    • In some use cases, it is not desirable that the login statistics (e.g. latest login timestamp) of the represented user be updated. Use the property Update Login Statistics in the Default Authentication Processor to disable it.
  5. Application Selector: specifying an application selector is only necessary if the REST client selects the flow by specifying a URL (instead of using the application ID).
  6. Airlock Gateway (WAF) Mapping Roles (Credentials) must be configured such that the intended target applications are accessible after passing the authentication flow.
  7. Identity Propagation:
    • Configure identity propagation as required by the target application.
    • To propagate the representer ID, check the plugin documentation for details. In most identity propagator plugins, it can be referenced using the key REPRESENTER_ID (in the additional information map). In the Generic Identity Propagation plugin, it is available using the key representer-user-id if using the User Identity Map.
  8. Activate the configuration.
  9. The representee side of the user representation feature is now configured in the Loginapp REST API.

Security Implications of SSO Ticket Repository Choice

All successfully accepted SSO tickets are stored in order to prevent replay attacks.

There are two possibilities to store SSO tickets:

  • In memory with plugin In-Memory Accepted SSO Tickets Repository
    This is simple and straightforward in configuration and okay for single-instance deployments. If more than one IAM instance is active, their list of accepted SSO tickets is not shared.
  • On the database with plugin Persistent Accepted SSO Tickets Repository
    This requires a database connection configuration, an up-to-date database schema (at least IAM 8.1 DB schema), and the configuration of the Accepted SSO Tickets Clean-up Task in the Service Container module.
    This configuration is more secure and prevents replay attacks even across multiple IAM instances.

It is highly recommended to use the Persistent Accepted SSO Tickets Repository for production.

Instructions - extend an existing authentication flow

As an alternative to the above configuration procedure, one or more existing authentication flows may be extended to accept representation SSO tickets in addition to the already configured flow (e.g. the interactive authentication flow for the end-user).

  1. Go to:
  2. Loginapp >> Applications and Authentication >> Applications >> target application to extend

  3. Instead of the existing authentication flow, add a Selection Step with the following configuration:
    • Add one Selection Option with the Representation SSO Ticket Identifying Step (details see above) and plugin User Represented Condition as Condition.
    • Configure the authentication steps of the original authentication flow as Fallback Flow.
    • Depending on the use case, it may make sense to only configure part of the original flow as Fallback Flow and put the rest after the introduced Selection Step. As a result, both the representer and the end-user have to pass the corresponding steps.

  4. Leave the rest of the target application configuration as it was.
  5. See above regarding the propagation of the representer ID.
  6. Activate the configuration.
  7. The representee side of the user representation feature is now configured in the Loginapp REST API.

Access control configuration hints

The configured authentication flow makes sure the representer can access target applications and protected self-services according to access control settings. Usually, the representer is not allowed to access all applications available to the end-user. It makes no sense, for example, that the representer can change the password for the end-user.

  • To achieve this, use the same access control concepts as for the end-user:
  • Limit the set of roles (credentials) sent to the Airlock Gateway.
  • Use Authorization Conditions and Access Conditions for protected self-services.
  • Only make user representation available in selected Target Application configurations.

After accessing a target application or using a protected self-service, the representer may want to access another application or service or open the application portal. This requires the representer to go through an authentication flow again.

Note that this time, the representation SSO ticket may no more be available or be expired. The authentication flow must therefore be passed with tags obtained in the first authentication flow (and stored in the session). When configuring representation, you must therefore make sure, that the corresponding auth flow(s) are passable by the representer with the tags obtained during the representation auth flow.

Note about parallel sessions (behavior upon existing sessions)

Airlock IAM may be configured to assure an end-user has only one active session at a time (or one per client type). The corresponding configuration can be found here:
Loginapp >> Applications and Authentication >> Behavior Upon Existing Session

Sessions of represented users are not taken into account. Thus, an end-user may be logged in while being represented by a representer.

To change this, i.e. to also take representer sessions into account, uncheck the option Disable Session Behavior When Represented in Loginapp >> Applications and Authentication. In this case, an end-user may not be logged in while being represented.