Invitation | Using Cirrus Invitation
When configuring the Invitation Service for an SP, there are a number of configurable text messages and email messages that can be customized using substitution strings. A substitution string is a code word that is replaced by values from your Org and SP configuration when the message is displayed or the email is sent. The following table describes the available substitution strings and where they can be used.
|Step Number||Invitation Flow Step|
|1||Guest Invitation Message|
|2||Invitation Claim User Interface|
|3||Guest Email Address Verification Message - Not Customer Configurable|
|4a||Guest Feedback Online|
|4b||Guest Feedback Email|
|5||Sponsor Feedback Email|
|6||Authorization Error User Interface|
|Substitution String||Description||Step 1||Step 2||Step 3||Step 4a||Step 4b||Step 5||Step 6|
|APPLICATION_NAME||The "Friendly Name" of the application, from the SP configuration.||X||X||X||X||X||X||X|
|APPLICATION_LINK||The URL of the application, from the SP invitation configuration.||X||X||X||X||X||X|
|EMAIL_VALIDATION_CODE||The validation code used to validate a new email address. This is dynamically generated when a request is sent.||X|
|GUEST_SUPPORT_EMAIL||Email address to which support requests should be directed. This is taken from the SP invitation configuration.||X||X||X||X||X||X|
|GUEST_FIRST_NAME||The first name of the guest.||X||X|
|GUEST_LAST_NAME||The last name of the guest.||X||X|
|GUEST_EMAIL||The email address of the guest used for the invite.
NOTE: This value will change if the the end user claims the invitation with an email address different from the orientating address (see INVITE_EMAIL). Once the claim process is complete, this value will reflect the "mail" value on the guest object.X
|GUEST_EPPN||The guest's ePPN.
NOTE: This is only known after the guest has accepted the invitation.
|GUEST_EXPIRATION_DATE||The date on which the guest account will expire. The date will be in the 'Mon DD, YYYY' format, for example 'Jan 1, 2020'.||X||X||X|
|GUEST_SOCIAL_PROVIDER||The social login provider that was used to claim the invitation.
NOTE: This is only known after the guest has accepted the invitation.
|INVITE_EMAIL||The email address the invitation was initially sent to. This value does not change and will be reflected by the data value "mailForInvite" on the guest object.
NOTE: This is only reported after the guest has accepted the invitation. Before that, it would equal the GUEST_EMAIL.
|INVITATION_LINK||The URL to include in the invitation. The user will click on this link to accept the invitation.||X|
|INVITATION_VALIDITY_PERIOD||Number of days the invitation will remain valid.||X|
|SPONSOR_EMAIL||The email address of the sponsor.||X||X||X||X||X|
|SPONSOR_FIRST_NAME||The first name of the sponsor.||X||X||X||X||X|
|SPONSOR_LAST_NAME||The last name of the sponsor||X||X||X||X||X|
|SPONSOR_FULL_NAME||Full name of sponsor, equivalent to 'SPONSOR_FULL_NAME SPONSOR_LAST_NAME'||X||X||X||X||X|
Invitation Service and Account Linking - Email Address Handling
This solution describes how the email address is handled during the registration process of both the Cirrus Identity Invitation Service (Invitation) and Cirrus Identity Account Linking (Account Linking).
Most configurations of both the Invitation and Account Linking products have a process flow as follows:
The user is sent an email with a registration URL based on a request from the Invitation or Account Linking product
The user clicks the registration URL or selects the URL and pastes it into a browser, and is taken to a Cirrus Identity page to accept the registration by logging in with a social identity provider
The social provider releases attributes about the user to Cirrus Identity as part of the authentication assertion
If needed, the user provides additional attributes that are not available from the social provider (see examples below)
Cirrus Identity completes the registration by connecting the email address to the original Invitation or Account Linking request
During this process, the address that is used to send the email with the registration URL and the address that gets connected to the completed request should be treated as mutually exclusive. The reasons for this vary depending on the following scenarios:
A user receives the email with the registration URL at a GMail address and registers it with Google as a social provider
A user receives the email with the registration URL at one address and registers it with a social provider associated with a different email address (for example the user receives the registration URL at their GMail address and logs in with Yahoo)
A user receives the email with the registration URL at one address and registers it with a social provider that has email address as an optional attribute (for example Facebook)
A user receives the email with the registration URL at one address and registers it with a social provider that does not release email as an attribute (for example Instagram)
All the scenarios start with the same user experience.
|The user receives an email with a registration URL. In this case "Ted Thunder" received his at "email@example.com" which is hosted by Google.||Screenshot|
|When Ted clicks the registration URL or selects the URL and pastes it into a browser, he is taken to the Cirrus Identity registration user interface (which looks very similar to the Cirrus Identity Discovery service).||Screenshot|
Depending which social provider is picked by the user, the email that results will change as illustrated by the following examples.
The first example is if Ted Thunder selects Google as the social provider.
|When Ted picks "Google Login", he will either be taken to the standard Google authentication user interface, or since he most likely is already logged in, will just confirm he wants to use the existing Google session.||Screenshot|
|In the case of Google , once Ted picks his account, the registration process proceeds directly to completion. The Cirrus Identity registration user interface will provide feedback that the process is complete.
 Because of a user interface change by Google, Google no longer asks users to confirm the release of attributes.
|The resulting email address that is bound to the initial request in this case is "firstname.lastname@example.org"||Screenshot|
The second scenario is if Ted Thunder selects Yahoo as the social provider.
|When Ted picks "Yahoo Login", he will be taken to the standard Yahoo authentication user interface. In this case, Ted has a Yahoo account called "hollyfeldl".||Screenshot|
|Yahoo asks Ted to confirm the release of attributes, in this case to the "Athena Institute Invite Proxy".||Screenshot|
|Ted will then be taken to the Cirrus Identity registration interface. Because Yahoo does not release separate first and last names, the user must provide them. The email address is editable, but if changed a verification process is triggered.||Screenshot|
|Ted fills out the registration using his "Mark Rank" alter ego.||Screenshot|
|When Ted completes the registration, he receives feedback the registration is complete.||Screenshot|
|The resulting email address that is bound to the initial request in this case is "email@example.com"
NOTE: Since Yahoo does not provide an internal opaque ID, we have configured the Cirrus Identity Gateway to set the EPPN to be the Yahoo email address.
The third scenario is if Ted Thunder selects Facebook as the social provider.
|In this case we have configured the Gateway to add the email attribute from the Facebook profile if it is available.||Screenshot|
|When Ted picks "Facebook Login", he will be taken to a Facebook authentication interface. In this case, Ted is again using "hollyfeldl" persona for his Facebook account (associated email "firstname.lastname@example.org").||Screenshot|
|As in other scenarios, Facebook will ask for release of attributes. If there is an email address available, the registration process will just proceed to the final results page (shown here). If there is not an email address or the email address is not released by the profile, the Cirrus Identity registration user interface will ask for an email with the default being the email address the original registration URL was sent to.||Screenshot|
|The resulting email address that is bound to the initial request in this case is "email@example.com" which was the address released from the Facebook profile. If an address was entered, that would be the one bound to the request.||Screenshot|
The forth scenario is if Ted Thunder selects Instagram as the social provider.
|When Ted picks "Instagram Login", he will be taken to an Instagram authentication interface. In this case, Ted is again using "hollyfeldl" persona for his Instagram account (associated email "firstname.lastname@example.org").||Screenshot|
|Instagram does not have separate First Name and Last Name options. The user needs to fill those in. The user also has to set an email address. The email address that the original registration URL was sent to is populated by default.||Screenshot|
|In this case, Ted fills in his first and last names and leaves his address as is. The registration can then be completed.||Screenshot|
|The resulting email address that is bound to the initial request in this case is "email@example.com".||Screenshot|
If during the registration process, an email address is entered that is both different from the one that received the original registration URL and was not provided directly by a social provider, an extra step will be taken to verify the email address. That process is as follows:
|In the registration user interface, the user will be prompted to validate the email address.||Screenshot|
|The message will look like what is presented to the right. When the user clicks the confirmation URL or selects the URL and pastes it into a browser, the registration will be completed. The result will be the normal feedback as outlined by the above scenarios.||Screenshot|