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 v5.0.0 (CO-1545). |
Attributes can also be collected from authoritative sources via other mechanisms, via Organizational Identity Sources. |
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.) |
The Enrollment Flow Duplicate Enrollment Mode configuration is not supported when using Enrollment Sources. However, as of Registry v4.1.0 EnvSource supports a plugin specific duplicate handing mode. |
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.
An invitation enrollment flow can be used for a new participant who has not yet joined the platform. Unlike the earlier configuration, this version will only create one Organizational Identity (via EnvSource). The enrollee will be able to log into the platform using the login identifier registered with the Organizational Identity based on the environment variables.
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.
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.
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 |
Hidden variables cannot be given default values from environment variables. |
As of Registry v4.0.0, the IdentifierEnroller Plugin offers a similar capability. |
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.
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.