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.

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

1. Go to:

Loginapp >> Authentication Flows >> Applications

2. Add a new Target Application with application ID represented.
3. 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 REST UI SSO Ticket Extractor plugin. It works best with the Loginapp REST UI which sends the SSO ticket in HTTP header X-IAM-SSO-Ticket.
• 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 check box Allow Locked Users to allow the representation of locked users.
• Add other authentication steps to the flow if required.
4. 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).
5. Airlock Gateway (WAF) Mapping Roles (Credentials) must be configured such that the intended target applications are accessible after passing the authentication flow.
6. 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.
7. Activate the configuration.
8. The representee side of the user representation feature is now configured in the Loginapp REST API.

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:

Loginapp >> Authentication Flows >> Applications >> target application to extend

2. 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.

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

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 (WAF).
• 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.

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 >> Authentication Flows >> 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 here:
Loginapp >> Authentication Flows
In this case, an end-user may not be logged in while being represented.

• Conceptual information:
• User representation
• Identity propagation in user representation
• User representation: representee configuration in the Loginapp REST UI
• User representation: representer configuration in the Loginapp REST API