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.)
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.
- Configure the EnvSource plugin, if not already done.
- Do not attach a Pipeline to the plugin.
- Set Sync Mode to Manual.
- Enable Sync on Login, if appropriate.
- In the attribute configuration, flag at least one identifier type as Login.
- Create a new Enrollment Flow with the following settings:
- Status: Active
- Petitioner Enrollment Authorization: Authenticated User
- Pipeline: None
- Identity Matching: None
- Require Approval: Optional
- Email Confirmation Mode: Optional
- Add CO Person and CO Person Role attributes as appropriate. Do not add any Organizational Identity attributes.
- From the Enrollment Flow configuration page, click Attach Org Identity Sources.
- Click
Add Enrollment Source.- Organizational Identity Source: Select the Env Source you previously configured
- Org Identity Mode: Authenticate
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.
- Configure the EnvSource plugin, if not already done. The same EnvSource used for Self Signup can be attached here as well.
- Do not attach a Pipeline to the plugin.
- Set Sync Mode to Manual.
- Enable Sync on Login, if appropriate.
- In the attribute configuration, flag at least one identifier type as Login.
- Create a new Enrollment Flow with the following settings:
- Status: Active
- Petitioner Enrollment Authorization: CO Person
- Pipeline: None
- Identity Matching: Self
- Require Approval: No (unticked)
- Email Confirmation Mode: None
- 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.)
- From the Enrollment Flow configuration page, click Attach Org Identity Sources.
- Click Add Enrollment Source.
- Organizational Identity Source: Select the Env Source you previously configured
- 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.