The Generic ID Propagator plugin

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

Overview

The Generic ID 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.

Table: Tasks of the Generic ID Propagator

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.

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:

Table: Ticket string providers for the Generic ID Propagator

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.

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.

Table: Value providers for identity propagation (excerpt)

Value provider

Description

Container Flow Attribute Value Map Provider

Provides a map for multiple non-persistent strings.

Context-Data Map

Provides all context data attributes of the user (e.g. email address, postal address, correspondence language, etc.)

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)

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.

SSO Ticket Context Data Provider

Context data attributes that have been extracted from an SSO ticket validated in the authentication flow.

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.

Value Provider Map

Provides a single Key to Plugin map for non-persistent strings.

Note that more value providers are available in the Config Editor.

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:

Table: Supported ticket adders

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 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 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 UI. The Loginapp 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.