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.

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.

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. If it does not have exactly the same settings as below you may instead create and configure a second instance of the EnvSource plugin.)
   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.  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  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  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  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.

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 v5.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. This functionality is deprecated and scheduled for removal in v5.0.0.