Child pages
  • Consuming External Attributes via Web Server Environment Variables
Skip to end of metadata
Go to start of metadata

A typical deployment pattern includes the collection of authoritative attributes provided from an external source, typically via a SAML or OIDC assertion, which are then passed to Registry via web server environment variables. This document describes best practices for collecting and managing attributes via this mechanism.

The supported approaches for the collection of authoritative attributes via environment variables have been changed in Registry v3.1.0. The newer mechanisms provide a clearer separation between authoritative attributes and CO attributes. The older mechanisms are considered deprecated, and will be removed in Registry v4.0.0 (CO-1545).

Attributes can also be collected from authoritative sources via other mechanisms, via Organizational Identity Sources.

Using EnvSource To Create Organizational Identities

Registry v3.1.0 introduces the EnvSource Organizational Identity Source plugin, which can be used to create Organizational Identities based on the attributes provided in web server environment variables. Typical uses of this plugin would be as part of a self sign-up enrollment flow, or as part of a self-service account linking enrollment flow.

Organizational Identities require a Primary Name. As such, EnvSource must be able to retrieve name values from the environment (ie: the remote identity provider must assert name attributes) in order to create an Organizational Identity. (Otherwise an error about "Save Associated" will be generated.)

In v3.1.0, Enrollment Flow duplicate enrollment detection is not supported when using Enrollment Sources. (CO-1577)

Self Signup

A self sign-up enrollment flow can be used for a new participant who has not yet joined the platform. This configuration will create a new Organizational Identity based on the attributes received via the environment variables, and a new CO Person record attached to the Organizational Identity, using attributes provided by the enrollee. (But see also Populating Default Values During Enrollment, below.) The enrollee will be able to log into the platform using the login identifier registered with the Organizational Identity.

  1. Configure the EnvSource plugin, if not already done. (If you are reusing an existing plugin configuration, make sure it has exactly the same settings as below.)
    1. Do not attach a Pipeline to the plugin.
    2. Set Sync Mode to Manual.
    3. Enable Sync on Login, if appropriate.
    4. In the attribute configuration, flag at least one identifier type as Login.
  2. Create a new Enrollment Flow with the following settings:
    1. Status: Active
    2. Petitioner Enrollment Authorization: Authenticated User
    3. Pipeline: None
    4. Identity Matching: None
    5. Require Approval: Optional
    6. Email Confirmation Mode: Optional
      1. (warning) Email confirmation is not yet fully supported (CO-1624)
  3. Add CO Person and CO Person Role attributes as appropriate. Do not add any Organizational Identity attributes.
  4. From the Enrollment Flow configuration page, click Attach Org Identity Sources.
  5. Click (plus) Add Enrollment Source.
    1. Organizational Identity Source: Select the Env Source you previously configured
    2. Org Identity Mode: Authenticate

Invitation

An invitation enrollment flow can be used for a new participant who has not yet joined the platform. This configuration will currently create two new Organizational Identities (CO-1578), one to send the invitation and one based on the attributes received via the environment variables. A new CO Person record will be created attached to both Organizational Identities, using attributes provided by the enrollee. (But see also Populating Default Values During Enrollment, below.) The enrollee will be able to log into the platform using the login identifier registered with the Organizational Identity based on the environment variables.

  1. Configure the EnvSource plugin, if not already done. (If you are reusing an existing plugin configuration, make sure it has exactly the same settings as below.)
    1. Do not attach a Pipeline to the plugin.
    2. Set Sync Mode to Manual.
    3. Enable Sync on Login, if appropriate.
    4. In the attribute configuration, flag at least one identifier type as Login.
  2. Create a new Enrollment Flow with the following settings:
    1. Status: Active
    2. Petitioner Enrollment Authorization: CO Admin, COU Admin, CO or COU Admin, or another suitably restricted setting
    3. Pipeline: None
    4. Identity Matching: None or Advisory
    5. Require Approval: Optional
    6. Email Confirmation Mode: Automatic or Review
    7. Require Enrollee Authentication: Yes
  3. Add CO Person and CO Person Role attributes as appropriate. Add at least a minimal set of Organizational Identity attributes (Official Name and Email, both of which can be copied to CO Person).
  4. From the Enrollment Flow configuration page, click Attach Org Identity Sources.
  5. Click (plus) Add Enrollment Source.
    1. Organizational Identity Source: Select the Env Source you previously configured
    2. Org Identity Mode: Identify

Account Linking

An account linking enrollment flow can be used for a participant with an existing CO Person record who wishes to add a new Organizational Identity, typically to authenticate using a different identity.

  1. Configure the EnvSource plugin, if not already done. The same EnvSource used for Self Signup can be attached here as well. (If you are reusing an existing plugin configuration, make sure it has exactly the same settings as below.)
    1. Do not attach a Pipeline to the plugin.
    2. Set Sync Mode to Manual.
    3. Enable Sync on Login, if appropriate.
    4. In the attribute configuration, flag at least one identifier type as Login.
  2. Create a new Enrollment Flow with the following settings:
    1. Status: Active
    2. Petitioner Enrollment Authorization: CO Person
    3. Pipeline: None
    4. Identity Matching: Self
    5. Require Approval: No (unticked)
    6. Email Confirmation Mode: None
  3. Do not add any Enrollment Attributes. (You will be asked to add one by default, simply page back or follow the breadcrumbs to skip it.)
  4. From the Enrollment Flow configuration page, click Attach Org Identity Sources.
  5. Click (plus) Add Enrollment Source.
    1. Organizational Identity Source: Select the Env Source you previously configured
    2. Org Identity Mode: Authenticate

Populating Default Values During Enrollment

EnvSource is used to populate Organizational Identities. While a pipeline could be used to create a CO person record from this organizational identity, this is not typically recommended as external identity providers usually do not release sufficient attributes to create a full CO Person record. More typically, enrollment attributes are configured to present a form to the enrollee, for purposes of collecting additional attributes.

Attributes from environment variables can be used to pre-populate the enrollment attributes, reducing the amount of typing necessary. These attributes become the default values for the CO Person record, but can be changed by the petitioner. To configure this, simply set the appropriate environmental variable name in the Environment Variable For Default Value configuration for each Enrollment Attribute.

This mechanism is completely unrelated to EnvSource.

Note that names are treated specially, since they have multiple components. The specified variable will be appended with _HONORIFIC, _GIVEN, _MIDDLE, _FAMILY, or _SUFFIX to generate the variable name for the appropriate component. For example, if the variable name ENV_OIS_NAME is specified, ENV_OIS_NAME_GIVEN will be used for the first/given name.

Hidden variables cannot be given default values from environment variables.

CMP Enrollment Attributes

Prior to Registry v3.1.0, CMP Enrollment Attributes were used to provide this capability. See Registry Platform Configuration for more information. This functionality is scheduled for removal in Registry v4.0.0 (CO-1545).

In general, this older capability should not be used with the newer capabilities described above. However, if both are configured the newer capability will take precedence.

Email Confirmation and Authentication

If only the authenticated identifier is desired, Email Confirmation and Authentication can be used to collect it, and attach it to an Organizational Identity created by the Enrollment Flow. See the Enrollment Flow documentation for more information.

  • No labels