Cirrus Invitation Documentation

Many organizations with to limit the use of external or guest access only to users who have been explicitly "sponsored" by enterprise account holders. Sponsored accounts can address accountability and other compliance concerns. Most times, this functionality ends up being a customization to existing administrative or identity management solutions that must be maintained by the organization over time.

Cirrus Invitation provides a solution to manage sponsorship of external access without the need to maintain the underlying systems. Invitation provides a lightweight workflow that allows sponsors to "invite" specific end users (designated as guests) and on board them to an external login method using an email invitation. The external login methods supported are:

• Social Login Providers such as Google, Facebook, Microsoft, LinkedIn, and others supported by the Cirrus Gateway
• A customer affiliated guest account provided by the Cirrus External Identity Provider
• The Cirrus Identity hosted EduAccessID service
• An account from a federated identity provider:
  • From an identity provider published in a public trust federation such as InCommon or one of the eduGAIN federations
  • From an identity provider published in a non-eduGAIN federation (metadata would have to be exchanged directly with Cirrus Identity Support)
  • From an unpublished identity provider where the metadata is directly exchanged with Cirrus Identity Support

Cirrus Invitation is based on a few principles:

1. Sponsors are affiliated with the organization
2. End users use external accounts that are appropriate for the services being accessed -- in most cases the accounts already exist but depending on the allowed login methods, a new account may need to be created
3. For most deployment patterns, sponsors can be authenticated with the organization’s enterprise identity provider (the exception would be if invitations are being generated using Cirrus APIs)
4. Sponsorship is a form of course grained access control (authorization) -- the lack of a sponsor prevents access to one or more service provide

Customers will often subscribe to one or more additional Cirrus Identity modules to support desired implementation patterns. In addition to enabling Invitation, Cirrus Identity Provider Proxy and Cirrus External Identity Provider instances may be provisioned, and some initial setup for Cirrus Gateway and/or Cirrus Account Linking may also take place.

The following are the steps needed to get started using Cirrus Invitation:

1. Customers should consider the planning steps before starting. If help is needed, Cirrus Identity offers generally accepted practices, customer stories, and professional services to help.

2. Depending on the target audience, Cirrus will provision other modules based on the customer’s subscription (or trial/PoC agreement). Modules such as Cirrus Gateway, Cirrus External Identity Provider, Cirrus Account Linking, and Cirrus External Identity Provider each have associated setup. See the “Getting Started” for each module as appropriate:

   • Cirrus Gateway Getting Started

   • Cirrus Account Linking Getting Started

   • Cirrus Identity Provider Proxy Getting Started

   • Cirrus External Identity Provider Getting Started

3. If there is an identity provider or service provider that is needed by Invitation, but the metadata for the SP/IdP is not published to federation metadata (for example InCommon or eduGAIN), the metadata needs to be sent to support@cirrusidentity.com for configuration.

4. A member of the organization needs to have access to the Cirrus Console and to be granted the “Organization Administrator” (org admin) role for your organization (see Cirrus Console Getting Started).

5. The SP (or the SP side of a Cirrus Proxy) will need to be active in the Cirrus Console and have the Invitation capability enabled. If it has not already been configured, an org admin will create the SP in the Console so it can be configured. While configuring the SP, the option to allow the SP to use Invitation needs to be enabled.

6. From the Cirrus Console, an org admin will configure the organization level Invitation settings found on the “My Orgs | Invitation Service” page:

   • Configure the email invitation validity period -- this can be overridden if Cirrus APIs are used to send invitations

   • Configure the duration of sponsorship -- this can be overridden if Cirrus APIs are used to send invitations

   • Configure the organization wide email subject line -- this can be overridden if Cirrus APIs are used to send invitation (See Message Setup for more detail)

   • Configure the organization wide invitation include -- generally accepted practice is to include the “INVITATION_LINK” here (See Message Setup for more detail)

   • Enable domain blocking to prevent the sending and/or claiming of invitations from any email address associated with the organization’s domain.

7. From the Cirrus Console, an org admin will configure the email settings found on the “My Orgs | Email Handler” page. By default, email sent from Invitation will be sent using Cirrus Identity mail infrastructure. Generally accepted practice is for customers to have email originate from the organization's email infrastructure. Customers control this capability from the “Email Handler” page.

8. From the Cirrus Console, an admin will configure the Cirrus Gateway to enable social login capabilities (see Cirrus Gateway Getting Started). Generally Invitation is used with social login options, however that is not a requirement and can be skipped if the Cirrus External Identity Provider and/or federated identity providers are the only ones be integrated.

9. From the Cirrus Console, an admin will configure the Cirrus Discovery Service to enable the end user to select the identity provider (social login, Cirrus External IdP, and/or federated identity providers) for login (see Cirrus Discovery Getting Started).

10. From the Cirrus Console, an admin will start the configuration by going to the “My SPs | Invitation Service” page for the desired SP and starting the configuration:

    • Make sure to “Enable Invitations” if invitations will be used to control access. Most Invitation use cases will want this enabled and only in specific Cirrus Account Linking cases should this be disabled.

    • Set basic attributes about the messages

    • Establish how sponsors will be authorized to create invitations

    • Define the required attributes

    • Define the content of messages (See Message Setup for more detail)

    • Set if non-social identity providers will be allowed -- this should be set if Cirrus External Identity Provider and/or federated identity providers will be allowed and should only be set if the SP is associated with a Cirrus Proxy

    • Set if sponsors will be allowed to upload a file of end users to invite

    • Set if expiration notices should go out individuals

11. Change the configuration of SPs to trust the proper IdP, utilize the Cirrus Proxy if appropriate, and utilize the Cirrus Discovery Service as outlined by:

    • Cirrus Discovery Getting Started

    • Cirrus Gateway Getting Started

    • Cirrus Identity Provider Proxy Getting Started

Once these steps are complete, you are ready to use Invitation. Invitation can be tested using the Invitation Service webform from the Cirrus Console. That same form can be used by properly authorized sponsors (See 10.3).

To monitor invitations, the Invitation Service menu has a “My Guests” page to present each sponsor the guests they sponsor. Administrators can see all pending and claimed invitations from the “My SPs | Pending Invitations” and “My SPs | Guests” pages respectively.

Email Configuration: Email Address Handling

Objective

This solution describes how the email address is handled during the registration process of both the Cirrus Invitation Service and Cirrus Account Linking.

Background

Most configurations of both the Invitation and Account Linking products have a process flow as follows:

1. The user is sent an email with a registration URL based on a request from the Invitation or Account Linking product

2. 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

3. The social provider releases attributes about the user to Cirrus Identity as part of the authentication assertion

4. If needed, the user provides additional attributes that are not available from the social provider (see examples below)

5. 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:

1. A user receives the email with the registration URL at a GMail address and registers it with Google as a social provider 

2. 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)

3. 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) 

4. 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 Weibo)

Scenario #1

1. "Ted Thunder" receives an email with a registration URL at "ted.thunder@athena-institute.net" which is hosted by Google.

2. Ted clicks the registration URL and is taken to the Cirrus Identity registration user interface (which looks very similar to the Cirrus Discovery Service).

3. Ted picks "Google Login" and is taken through the standard Google authentication flow.

4. The registration process proceeds directly to completion and the resulting email address is "ted.thunder@athena-institute.net".

Scenario #2

1. "Ted Thunder" receives an email with a registration URL at "ted.thunder@athena-institute.net" which is hosted by Google.

2. Ted clicks the registration URL and is taken to the Cirrus Identity registration user interface (which looks very similar to the Cirrus Discovery Service).

3. Ted picks "Yahoo Login" and is taken through the Yahoo authentication flow.

4. Ted will then be taken to the Cirrus Identity registration interface. Because Yahoo does not release name, the user must provide them. The email address (“ted@yahoo.com”) is editable, but if changed a verification process is triggered.

5. When Ted completes the registration, the resulting email address is "ted@yahoo.com".

Scenario #3

1. "Ted Thunder" receives an email with a registration URL at "ted.thunder@athena-institute.net" which is hosted by Google.

2. Ted clicks the registration URL and is taken to the Cirrus Identity registration user interface (which looks very similar to the Cirrus Discovery Service).

3. Ted picks "Facebook Login" and is taken through the Facebook authentication flow.

4. Facebook will ask for release of attributes. If there is an email address available (for example “ted@gmail.com”), the registration process proceeds directly to completion and resulting email address is “ted@gmail.com”.

Scenario #4

1. "Ted Thunder" receives an email with a registration URL at "ted.thunder@athena-institute.net" which is hosted by Google.

2. Ted clicks the registration URL and is taken to the Cirrus Identity registration user interface (which looks very similar to the Cirrus Discovery Service).

3. Ted picks "Weibo Login" and is taken through the Weibo authentication flow.

4. Ted will then be taken to the Cirrus Identity registration interface. Because Weibo does not release email the user must provide one. The email address will default to the invited one (“ted.thunder@athena-institute.net”) but is editable. If it is changed, a verification process is triggered.

5. When Ted completes the registration, the resulting email address is “ted.thunder@athena-institute.net” (assuming he did not change it and go through the validation process).

Email Configuration: Invitation Message Setup

Inviting Guests

 Overview

Cirrus Invitation provides an interface that can be used by sponsors to invite individuals to become a guest of the organization. This interface can be used interactively to invite small numbers of individuals or it can be used to upload a file to handle larger numbers.

Interactive

To use the interactive user interface:

1. Log in to the Cirrus Console. For sponsors there should only be a menu option “Invitation Service” (administrators will have additional options as shown below)

2. Select “Invite Guests” from the options at the left

3. Follow the instructions from the application owner

4. Provide one or more email addresses for the individuals you wish to invite

5. Agree to the terms of service

6. Press the “Send Invite” button

File upload

Format the list

Before the file can be uploaded, it must be properly formatted. Most customers will find using a spreadsheet application such as Microsoft Excel or Google Sheets a convenient way to compile and format such lists (this example will use Excel).

The file must also contain the data elements expected by your organization’s Cirrus deployment. Customers will typically use one of the following sets of data elements:

Basic List - A list that just contains email addresses. The first row must have the header name “emailAddress” exactly as shown.

List with Organization Data - A list where each row is an email address and organization identifiers (customData) associated with the individual. This customData will be specific to the organziation’s deployment. The first row must have the header names “emailAddress” and “customData” exactly as shown. The custom data elements are a comma separated list of key:value pairs in a single cell.

Advanced - A list where each row is an email address and additional data elements to support integration. This can contain any of the elements permitted by the /api/v1/batchInviteCsv Cirrus API endpoint (see the Cirrus API Documentation for details).

Prepare the list

Once you have the data compiled and formatted, Cirrus Identity expects the file to be a comma-separated-value (CSV) file. For Microsoft Excel, you would use the following dialog to export a spreadsheet as a CSV file.

Upload the list

To use the file upload capability:

1. Log in to the Cirrus Console. For sponsors there should only be a menu option “Invitation Service” (administrators will have additional options as shown below)

2. Select “Upload File...” button on the right

3. From the “Invitation File Upload” dialog, browse for the CSV file you created in the “Prepare the list” step

4. Agree to the terms of service

5. Press the “Upload” button -- your list will be processed in the background

You should see the following after a successful upload.