Generic Identity Propagator
17.2.2.8.1. The Generic Identity Propagator plugin

The Generic Identity Propagator plugin is a multi-purpose plugin for identity propagation in the Loginapp REST API and the Loginapp REST UI. This section explains how it is structured and used.

Overview

The Generic Identity Propagator plugin generates a string (basically a character sequence) bearing the identity information to transport. This string is called a ticket.

To offer flexibility regarding the contents and structure of the ticket, the plugin divides its task into the following steps. They are directly reflected in the configuration structure.

Task
Description
Generate ticket string
Selects the identity attributes to propagate and represents them in a ticket string. This may include cryptographic protection of the identity data (e.g. generate a JWT).
Encode ticket string
Encodes the ticket string before further processing (e.g. URL-encoding or base-64).
Transport ticket string
Adds the encoded ticket to the response in order to transmit it to the target application.
Condition
The configured condition determines whether the identity propagator is used at all.
Table 21: Tasks of the Generic Identity Propagator

Ticket string generation

To generate a string bearing the right identity attributes to be propagated, a Ticket String Provider plugin is used. The contents, structure, format, and potential cryptographic protection are configured within the ticket string provider.

Airlock IAM offers many ticket string provider plugins. The important ones for identity propagation are:

Ticket string provider
Description
Ticket String Provider
Based on a list of value providers (see below) this plugin creates a structured ticket - basically a list of name-value pairs - and encodes them in a JWT (other legacy encodings are supported but not recommended).
Using JWTs offers proven and flexible cryptographic protection mechanisms and standard attributes used for identity propagation (so-called claims).
Template-Based String Provider
Based on a list of value providers (see below) this plugin fills in identity attributes in a configured string template.
This allows, for example, to generate arbitrary JSON structures or simple ticket strings bearing only the username.
Note that this ticket string provider does not support digital signatures or encryption.
Table 22: Ticket string providers for the Generic Identity Propagator

Value Providers

The above-mentioned ticket string providers make use of the value provider concept.

Value providers are configured to collect information from various sources and make them available in the ticket string providers.

Check out the plugin documentation of each value provider plugin in the Config Editor to learn what identity attributes are made available and what identifiers can be used to reference them.

Value provider
Description
User Identity Map
Provides different user-id attributes:
  • internal user ID
  • provided user ID: ID as entered by the end-user in the login form
  • representer ID: the ID of the representer (if the end-user is represented)
User Statistics Map
Provides information about the last login, the number of failed logins, and alike.
Roles Provider
Provides the roles granted to the user.
  • roles: a string with the concatenated roles (including timeout and lifetime if present).
  • roles-list: the roles as a list (including timeout and lifetime if present).
  • role-names: a string with the concatenated role names (without timeout and lifetime).
  • role-names-list: the role names as a list (without timeout and lifetime).
The set of roles may be from various sources:
  • user repository
  • based on tags acquired in the authentication flow
  • configuration (with or without conditions)
  • OAuth / OIDC flow
  • SSO ticket (extracted in authentication flow)
Context-Data Map
Provides all context data attributes of the user (e.g. email address, postal address, correspondence language, etc.)
SSO Ticket Context Data Provider
Context data attributes that have been extracted from an SSO ticket validated in the authentication flow.
OAuth 2.0 Credential Context-Data Map
Context data attributes extracted from an OAuth/OIDC authorization code grant in the authentication flow.
OAuth 2.0 Tokens Map
Provides OAuth / OIDC access and ID tokens used in an OAuth/OIDC authorization code grant in the authentication flow.
Table 23: Value providers for identity propagation (excerpt)

Ticket string encoding

The ticket string generated by the ticket string provider (see above) can be encoded using a configured list of encoders.

Encoding the ticket string before adding it to the response may be required for several reasons:

  • It may be required by the receiving target application.
  • It may be required by the Ticket Adder plugin.
  • A cookie value containing special characters may require encoding. E.g. myCookie="myRoles=admin,authenticated" must be encoded with a URL String Encoder to avoid issues with the "=" in the cookie value.

Adding the encoded ticket to the response

To propagate the ticket to the target application a suitable transport mechanism in the form of a Ticket Adder must be configured.

The following transport mechanisms are currently supported:

Ticket adder plugin
Description
Cookie Ticket Adder
Sends the encoded ticket string to the target application as an HTTP cookie by storing it in the Airlock Gateway (WAF) cookie store. The cookie is sent to the target application with every subsequent request on the same session.
Note that the cookie is not sent to the browser (or other HTTP clients).
Request Header Ticket Adder
Sends the encoded ticket string to the target application as an HTTP header by storing it in the Airlock Gateway (WAF) header store. The header is sent to the target application with every subsequent request on the same session.
Note that the header is not sent to the browser (or other HTTP clients).
Response Header Ticket Adder
Sends the encoded ticket string to the HTTP client (browser or other) in an HTTP header.
SPA Forward Location Parameter Adder
Sends the encoded ticket string in a header especially reserved for the Loginapp REST UI. The Loginapp REST UI extracts the ticket string from the header and uses it in the forward URL as an SSO ticket.
The ticket string is therefore passed to the target application as GET parameter when redirecting the browser to the target application after successful authentication.
Table 24: Supported ticket adders

Further information and links