Attribute Collection

Background

Historically, Enrollment Flows permitted the collection of Org Identity and CO Person attributes. This was because the original model of external Org Identity attribute collection via protocols like LDAP and SAML could not be well supported, and so deployers could use these attributes to "simulate" the missing Org Identity data. However, this led to a blurring of the two types of attributes.

Approach

R3 Enrollment Flows (via an Attribute Collection plugin) will only collect Person (formerly CO Person) attributes via forms. External Identity (formerly Org Identity) attributes will be collected via External Identity Sources (or Enrollment Sources). ie: The Person record will be primary, and will permit the attachment of multiple External Identities, as opposed to R2 Enrollment Flows where Org Identity attributes are arguably primary, and can be copied into CO Person attributes.

Plugin Based Architecture

Background

Enrollment Flows were originally designed as a relatively fixed, but configurable, process to support common enrollment patterns. Over the years, support has been added for more complex use cases, and the configuration driven mechanism for enrollment has become brittle. While Enrollment Wedges were introduced to handle one-off requirements, their use is constrained by the overall flow. Additionally, in many Enrollment Flows numerous steps do not execute, leading to extra elapsed time while the browser processes a series of redirects (made worse with additional plugins) (CO-1663).

Approach

R3 Enrollment Flows will be implemented entirely using plugins, where each Enrollment Step maps to a plugin (or more specifically, a plugin model). Similar to jobs, "out of the box" steps will be implemented by a Core plugin. Enrollment Wedges will merge into this plugin infrastructure.

Plugins specify constraints (configuration metadata), including

• Steps that the plugin step must run before or after
• Actors that may run the step (Petitioner, Enrollee, Approver, Vetter)
• Minimum authentication level (Anonymous, CO Person, CO Group Member, etc)

Plugin steps may be configured to run more than once, which should primarily be useful for multiple attribute collection (CO-1002), but may also be useful for other contexts.

Handoff via Actors is managed by the Enrollment Flow engine, and is accomplished via Notifications (sent via email). This process is decoupled from the existing mechanism of Email Confirmation (which is overloaded), though it is conceptually similar to Notify on Approval (but more generic). Handoffs can happen multiple times in any direction. Any time a Handoff is executed, a Redirect option is available to send the no-longer-current Actor to a page with more information.

It may also be useful to handoff a step for background processing (eg: vetting), in which case initial handoff is handled via queueing a job, while continuation of the flow upon completion is handled via Notification.

Functional Requirements

1. Common patterns should be supported via out of the box templates, as is the case now for R2 Configurations.
2. There should be both a "simple" (functionally driven) and "advanced" (low level) configuration mode.
3. R2 Enrollment Flow Configurations need not transmogrify to R3 Configurations, but guidance should be provided for how to migrate.
4. Petitions created using R1 and R2 Enrollment Flows should still be readable.

Notes

1. An implication of this architecture is that some configuration items will move into Plugin configuration. For example, Enrollment Attributes will no longer be attached to the Enrollment Flow itself, but instead to the appropriate plugin configuration for the (Petitioner) Attributes Step (CO-769).
2. It may also be useful to have an Expiration Flow concept built on the same architecture, triggered by Expiration Policies or manually by an Administrator.

Error Handling

Background

When an error happens during an Enrollment Flow, CoPetitionsController generally redirects to / and renders an unhelpful flash, that also disappears when the user tries to click on it to copy the error. Error conditions can also lead to partially created records.

Approach

There will be a well defined error location that (non-stack trace) errors will redirect to, eg: /petitions/error/123. By default, error messages will render inline on this page, rather than in a flash message. Deployments will be able to customize this page, probably via plugins. The error message will also be recorded in the petition.

Administrators will be given a link to examine the error, and select an action:

1. Expunge the petition and any related objects (CO Person, etc).
2. Restart the petition from the next appropriate step.
   1. Where the Petitioner or Enrollee has abandoned a Petition, the restart option should send an email allowing the Petitioner or Enrollee to re-enter the Flow.
3. Terminate the petition and manually complete the record.

Duplicate Detection

Background

There are currently several points where duplicate management takes place, with somewhat different actions as a result:

1. Duplicate Enrollment Mode, which uses the value $REMOTE_USER to identify duplicate enrollments. The exact action taken depends on the configuration. Use of this capability requires Email Verification and Authentication.
2. Advisory Matching, which performs "search while you type" simple name matching. This configuration is only supported for Administrator driven enrollments. Selecting an existing CO Person record interrupts the Enrollment Flow in an unintuitive way.
3. External Matching, which calls out to an ID Match API. In the event of multiple candidate matches, the Petitioner must select an action before the Enrollment Flow can continue.

Approach

It may be desirable to support most or all of the current options going forward, however in general they should operate as External Matching currently does, requiring immediate resolution and appropriately linking (or not) the current Petition to an existing Person record (if found).

Invitation and Email Confirmation Validation

Background

Currently email address confirmation and invitation are conflated into the same step, and require clicking on a somewhat phishy looking link sent via email. These links are also susceptible to premature invalidation (eg: by email clients pre-fetching the URL) or confusion (an enrollee starts enrollment on their desktop, but then goes to their phone to check their email).

Approach

Going forward, Invitation may imply Email Confirmation as a side effect (since it is the same flow, basically) but the two concepts will not be as tightly linked. Instead of embedding nonces into URLs, validation will be via a code sent via email (or text message, etc). For self signup flows, the code will be prompted for inline without interrupting the current page. For invitation flows, a generic entry point will be established (eg: /registry/petitions/reply) that will prompt for the confirmation code and/or an Invitation ID, both of which can be copied from the email or text message. This page can also be independently linked from support pages, providing a verifiable path independent of the email URL.

Setup Assistants Replace Templates

Background

Enrollment Templates were originally created to provide easy-to-duplicate pre-configured Enrollment Flows to simplify setup of new Flows. They rely on Cake's ability to easily duplicate an object and its related models. As Enrollment Flow capabilities increased, not all configurations are easily Templatable. For example, EnvSource relies on an Org Identity Source plugin to be created, which might not exist in a given deployment, and so no Template can be shipped that includes a reference to an Enrollment Source.

Approach

Enrollment Templates will be replaced with a Setup Assistant, which provides common enrollment patterns and creates a default plugin configuration suitable for that pattern. Such patterns include:

• Self Signup with Approval
• Invitation
• Conscription
• Account Linking
• Additional Role Enrollment

The Setup Assistant can determine if a suitable EnvSource configuration exists, and if so offer an option to use it.

The Setup Assistant can also offer plugin specific options. For example, attribute collection might be "None" (for Account Linking), "Minimum Required" (name, affiliation, etc), or "Standard" (title, organization, etc).

Flows vs Policies

Enrollment Flows are intended to be interactive workflows to create new Person and Person Role identities. Expiration Policies are automated processes for adjusting the status of Person Role identities. Both concepts have been available in Registry for some time.

It may be desirable to incorporate their opposites into the same mechanisms, ie: Activation Policies to provide automated processes for enabling Person Roles and Offboarding Flows to create an interactive workflow for removing access.

See Also

• CFM-31 Enrollment Flows
• CFM-61 Expiration Policies
• CO-964 "Activation" Policies
• Org Identity Enrollment Refactoring Design Discussion (historical)