Enrollment flows reside under the 'Configuration' form of a CO. Only CO administrators can configure these options, other users do not have this link.
New COs do not have any enrollment flows yet, but you can easily add or restore the default templates, which serve as a starting point for further configuration. Before configuring a new enrollment flow, you can duplicate a relevant template.
After this, the enrollment flow can be configured, which requires three steps:
A typical enrollment flow configuration form looks like this:
Important fields here are:
- Petitioner Enrollment Authorization: this defines who can start the enrollment. For invitation flows, you want this to be set to administrators of the CO or a relevant COU. For self-signup, you normally want this to be 'Authenticated Users'
- Require Approval for Enrollment: typically, this is checked to enable administrators to approve individual petitions, although you may want to uncheck this for invitation flows, where approval is done beforehand
- Email Confirmation Mode: this determines whether the enrollee can review their enrollment after clicking on the link in the confirmation email. If set to 'Automatic', enrollment proceeds immediately. 'Review' is a sensible setting.
- Require Enrollee Authentication: for self-signup flows where only authenticated users can enroll, authentication was already done at the start (and the IdP provided attributes were linked), so this option can be unchecked ('off'). For invitation flows, you want the enrollee to authenticate after accepting the enrollment (review), so the system can gather the IdP provided attributes and this setting needs to be enabled ('on')
The other fields are either less relevant or very obvious and allow administrators to further personalize the enrollment experience.
Enrollment attributes determine the attributes gathered of, from or by the enrollee during the enrollment flow:
A typical list of attributes looks as follows:
This list determines which attributes are gathered and to which destination object the attributes are copied (note: not from which source). Administrators can determine which values are required, which fields are visible and which attributes can be further modified by the user:
- If using the SamlSource OIS plugin (see below), the authorative IdP attributes are stored non-modifiable in an attached Organisational Identity (OrgIdentity). It is therefore not essential that specific information needs to be non-modifiable to allow administrators to properly identify enrolled COPersons: administrators can always look at the related OrgIdentity with the relevant IdP attributes. This information is clearly visible when perusing an enrolled COPerson's data.
- The SamlSource plugin tries to split a displayName field into givenName and familyName, but it uses a simple algorithm. Consider allowing users to modify their name to avoid cases where this automatic splitting fails, or where users have a different preferred name than their officially registered institute name. This opens the door for people that want to impersonate as someone else, but as mentioned above: administrators have easy access to the IdP provided attributes to correct such cases.
- The email address provided by the IdP might not be the preferred address for this specific CO of that COPerson, so consider allowing users to modify their email address. Alternatively, consider adding a hidden field for the official email address and a modifiable field for the preferred email address
- Please note that copying the IdP provided attributes without allowing users to modify (or even see) the values might violate the user consent and/or the institute privacy guidelines, depending on the scope of the CO and additional policies. In general, it is best practice to only filled required attributes using the IdP provided data as default, but allow users to modify their actual value before proceeding with enrollment.
- For invitation flow enrollment, the IdP attributes are not available yet when these attributes are gathered, so there is no way to copy IdP provided attributes.
Note: the following 3 attributes are REQUIRED for any invitation flow:
- Affiliation (CO Person Role)
COmanage will happily accept a flow without those attributes, but will then fail to submit the enrollment form with incomprehensible error messages like "Please check the highlighted field", while not of the fiels are highlighted.
A typical attribute configuration form looks like this:
- select the SamlSource Plugin
- 'Sync Mode' should be 'Manual', because the SAML data is only available when the user logs in and hence cannot be synced when the user is offline
- 'Sync on Login' should be checked ('on')
- SamlSource creates a login identifier based on different settings, so the 'EPPN' fields can be disregarded.
- Detecting changes does not cause any relevant behaviour, so hashing is not required
After completing this form, the SamlSource plugin can be setup:
- The Prefix used is 'MELLON_', without the quotes, but including the underscore
- The Identifier used by SCZ is called 'cmuid' (again, without the quotes)
With at least one OIS configured, a new option appears with the enrollment flow configuration screen:
You can add several OIS-es, but the general case is to have only the SamlSource OIS:
- for invitation flows, you need to set this to 'Identify', so you get an additional OrgIdentity record through which you can identify the enrolled COPerson afterwards
- for self-signup flows, you need to set this to 'Authenticate', so an OrgIdentity is created upon initial authentication, which can be used to set default values for enrollment attributes