Organizational Identity Sources allow for the creation of Organizational Identities linked to an external source or "system of record". These sources can include LDAP servers, REST APIs, SQL databases, flat files, and so on. Custom plugins can be written for arbitrary sources.
Organizational Identity Sources can only be defined on a per-CO basis. If org identities are pooled, Organizational Identity Sources are not supported. Once configured, Organizational Identities can be created from these sources in several ways:
syncorgsources
task, as described below.Organizational Identity Sources can be linked to Registry Pipelines in order to automatically create CO Person records.
When an Organizational Identity is created from a source, it is linked to that source and cannot be manually edited, not even by an administrator. However, it can be manually resynced to pull changes from the source.
If the corresponding record is removed from the Organizational Identity Source, on the next sync the Org Identity will be set to status Removed, but the Org Identity itself will remain available – it is not deleted.
If Attribute Enumerations are enabled for any attributes, permitted values for those attributes are constrained to the enumerated options. Source records containing a non-enumerated value will fail to process correctly.
Organizational Identity Sources are available in COmanage Registry v2.0.0 and later.
The terminology used by Registry can be a little confusing when looking at person records related to Organizational Identity Sources.
When called from Registry Job Shell via the syncorgsources
task, Organizational Identity Sources can be configured in the following sync modes:
Not all Organizational Identity Source plugins support all sync modes. Check the documentation for any limitations.
Syncing via Job Shell can be disabled on a per-CO basis via CO Settings >> Disable Org Identity Source Sync.
As of Registry v3.1.0, Org Identities associated with an Organizational Identity Source can be resynced on user login to Registry. This is enabled on a per-Organizational Identity Source basis, by enabling the Sync on Login setting.
Because user login crosses COs, when a user logs in the identifier they used to login will be searched against all Organizational Identities (regardless of CO) for matching CO Person records. Then, any Org Identity associated with those CO Person records will be checked for an associated Organizational Identity Source for the Sync on Login setting. In other words, a login event will resync any suitably configured record, not just the one associated with the identifier used to login.
If external databases are configured as Organizational Identity Sources to sync during login, users may experience login delays related to querying those databases. |
Sync on login is not supported when Organizational Identities are pooled. Unexpected results may occur. |
By default, creating an Org Identity (via Add New Org Identity From Source or any other mechanism) will not create a CO Person.
If the Org Identity Source is attached to a Pipeline, then that Pipeline will likely create a CO Person for the new Org Identity. If a Pipeline Match Strategy is configured, then the Pipeline may attach the new Org Identity to an existing CO Person if the match conditions are satisfied.
To manually link an Org Identity to an existing CO Person, there are two options:
When syncing records from an Org Identity Source, Registry can automatically create an identifier of type ePPN to be injected into the Org Identity created from the Source. This can be useful for (eg) automatically calculating the ePPN of an IdP associated with the Source. There are two settings:
@
.An ePPN will not be generated if one is found in the Org Identity record created from the Source.
Organizational Identity Sources can generate CO Group Memberships via Group Mappings, when the relevant OIS Plugin implements the appropriate interfaces. However, since group memberships attach to a CO Person and not an Organizational Identity, for this to be useful the OIS must typically be attached to a Pipeline, which will then create CO Group Memberships attached to the relevant CO Person record. For OIS Plugins that support this feature, the steps to enable it are:
When a record has been synced to Registry from the Organizational Identity Source, a cached copy is stored in the Organizational Identity Source Record so that Registry may detect when the source record has been updated. By default, this is a full copy of the record as returned to Registry from the backend (in whatever format is returned from the source, eg JSON, XML, etc). This is also useful for tracing problems, as it is possible for an administrator to look at a cached copy of the data.
However, there may be privacy or data retention concerns that make storing a full copy less desirable for a given deployment. As an alternative, Registry can create a hash of the data to be stored instead. This can be enabled via the Hash Source Records configuration option.
When this configuration is changed, existing records are not affected. Furthermore, since the cached copy will no longer match the current source record, all records from the Source will be considered out of date the next time a sync is performed. It is best to determine the appropriate value for this setting prior to significant production usage.
An additional consideration when enabling Hash Source Records for privacy or data retention reasons is that older copies of the source records are maintained by Changelog Behavior. It is insufficient to enable this setting and perform a full sync to remove all old records from the database, rather manual intervention is required. The following SQL is for general guidance and should not be used directly without first testing against a test server:
SQL> update cm_org_identity_source_records set source_record=md5(source_record) where org_identity_source_id=? and (deleted=true or org_identity_source_record_id is not null); |