Env Source is an External Identity Source Plugin designed to pull attributes from environment variables, generally populated by web server authentication modules, typically something like mod_auth_shib or mod_auth_openidc.

Env Source is designed to primarily collect identities as part of an Enrollment Flow.

Configuration

Env Source is part of the EnvSource Registry Plugin, which is enabled by default.

Env Source consists of several Entry Point Models of different types. The primary configuration is handle via the External Identity Source instance, which is responsible for defining how the External Identity is collected via the Web Server Service Provider.

• When adding a new External Identity Source, the Plugin is EnvSource.EnvSources.
• Env Source does not support Manual, Update, or Full sync modes. However the External Identity Source mode ("Status") should be set to Manual.

A second Entry Point Model (EnvSourceCollectors) is for Enrollment Flow use, and is described below.

A third Entry Point Model (EnvSourceDetours) is used to update Env Source Identities on login, and is described below.

Mapping Attributes

Env Source reads environment variables, typically set by the web server, for information about the currently authenticated user. Populating these variables is beyond the scope of this document, refer to the appropriate authentication module documentation for further information.

Configuration of which environment variables to read from is via the Environment Variable Map. This Map will be used to construct an External Identity and a single External Identity Role. Affiliation, Department, Organization, and Title will attach to the External Identity Role, all other attributes will attach to the External Identity.

In general, all attributes are single valued, however see Web Server Service Provider below for more information.

Most attributes are optional, however at minimum a Source Key Identifier is required, and a Name and Affiliation should be populated.

Affiliation

Affiliation values must match the Database Value of the configured Affiliation Type.

Source Key

An environment variable must be mapped to Identifier (Source Key), which will serve as the unique key for the record. This should be the authenticated identifier (the equivalent of $REMOTE_USER) in order for Sync on Login to work (see below).

Default Types

For attributes that support Types (Name, Address, Email Address, Telephone Number, and Affiliation) default Types must be configured. These Types will be used when creating these attributes since type labels cannot be conveyed via the environment variables themselves.

Web Server Service Provider

The Web Server Service Provider configuration is used to tell Env Source which software is in use to populate the environment variables, allowing Env Source to modify its behavior accordingly. Currently, this is only used to permit multiple values to be parsed out of a single variable:

• Shibboleth: The provided values are split on semicolons (;)
• SimpleSamlPhp: The provided values are split on commas (,)
• Other: No parsing takes place, only single values are supported

Sync on Login

See Updating Attributes on Login, below.

Lookaside File

The Lookaside File simplifies testing by providing a file of variables to read. When configured, the actual environment variables (as returned by getenv()) are ignored and the values from the Lookaside File are used instead. The file is a simple PHP .ini file, consisting of the configured variable names and their values.

The configuration value is the full path to the Lookaside File. When configured, the file must be readable by the web server. If the file is configured but not readable, an error will be thrown.

; Lookaside file for envsource debugging, in .ini format

ENV_SOURCE_KEY = "123456789@university.edu"
ENV_GIVEN = "Pat"
ENV_FAMILY = "Lee"
...

Using Env Source in an Enrollment Flow

In order to create an External Identity using Env Source during an Enrollment Flow, create a new Enrollment Flow Step with the following configuration:

• Plugin: EnvSource.EnvSourceCollectors
• Actor Type: Petitioner for self signup flows or Enrollee for all other types of flows

On the Plugin configuration page, select the desired External Identity Source Env Source configuration.

Env Source Collector will trigger web server authentication. If the Enrollee is not already authenticated, it may be desirable to advise the Enrollee that they will be asked to login before continuing.

Duplicate Management

Env Source performs basic duplicate detection using the Source Key. A given Source Key may only be present in one External Identity. If an Enrollment Flow attempts to collect an identity via Env Source that has a Source Key already present in an External Identity, Env Source will flag the Petition as a duplicate and redirect the user to the Redirect on Duplicate URL if configured, or the duplicate-landing Mostly Static Page if not.

Updating Attributes on Login

The identities created by Env Source can be updated when the user associated with the identity logs in to the platform. Enabling this requires two steps.

Setting up EnvSourceDetour (Platform Administrator)

EnvSourceDetour is a Traffic Plugin that runs after the user authenticates but before control is returned to the application. Because there is no CO context during authentication, Traffic Plugins operate at the Platform level, which means they must be configured by a Platform Administrator, not a CO Administrator.

1. From the COmanage CO, navigate to ALL > Platform-Wide Configuration > Traffic Detours >  Add a New Traffic Detour.
   1. Plugin: EnvSource.EnvSourceDetours 
2. There is no further plugin specific configuration, but due to current UI limitations an Edit page will appear with a Save button. It is not necessary to click the Save button, but also there is no harm in doing so.

EnvSourceDetour must be set up once per Platform, not once per CO.

Enabling Sync on Login (CO Administrator)

When a user authenticates, EnvSourceDetour will use the authenticated identifier (which should be the Source Key) to find Env Source Identities registered in any CO. If Sync on Login is enabled for the Env Source configuration that created the identity, any changes to the provided attributes will be processed and the Pipeline rerun.

Keep in mind this entire process happens during the login redirect sequence, so if there are slow processes involved in the Pipeline (especially, for example, provisioning) it is possible to run into issues with browser timeouts, and so use of Sync on Login in such situations may not be desirable.

Searching Env Source Records

It is possible to search Env Source records via the standard External Identity Source search interface ("Search Source" from the External Identity Source index page), however this can only search the cached records of synced, existing source records.

See Also

• Managing Apache Web Server Environment Variables
• Registry Table: env_sources
• Registry Table: env_source_collectors
• Registry Table: env_source_detours
• Registry Table: env_source_identities
• Registry External Identities
• Registry PE Pipelines

Changes From Earlier Versions

As of Registry v5.1.0

• The System of Record ID is now called the Source Key.
• Lookaside Files are supported.
• Duplicate Handling Mode is no longer supported, since a Source Key can only exist in one active External Identity, and External Identities are no longer permitted to assert login identifiers.
• Login Identifier flags are no longer supported, since External Identities are no longer allowed to assert login identifier status.

Env Source was not available in Registry v5.0.x.