Invitation | Getting Started
Planning Cirrus Invitation
Step 1 - Identify the implementation pattern
The first planning step is to identify the Cirrus Invitation implementation pattern to use. There are three generally accepted patterns:
The simplest pattern is to invite individual end users to access a single service provider using the Cirrus Gateway social login providers (Google, Facebook, Microsoft, LinkedIn, or others).
The most common pattern is to invite individual end users to access a Cirrus Identity Provider Proxy. This pattern addresses several use cases:
Use of the Proxy removes the constraint of a service provider needing to support multi-lateral SAML federation and enables a broader selection of service providers to leverage the Invitation solution
Many times, the target audience for Invitation needs to access a collection of service providers -- using Proxy ensures all of the service providers receive the same information about the individual
This pattern also supports enforcement of invitations claimed using non-social identity providers such as the Cirrus External Identity Provider and other federated identity providers
A more advanced pattern is to invite individual end users and to also use Cirrus Account Linking to attach one or more organizational identifiers to the invitation. The value of this pattern is to combine the access control characteristics that sponsorship brings with the access life cycle characteristics that are made possible with stable, organization controlled identifiers.
The following table summarizes the three patterns:
|Pattern||"Gateway Pattern"||"Proxy Pattern"||"Linking Pattern"|
Cirrus Identity Provider Proxy
Cirrus External IdP (if used)
Cirrus Identity Provider Proxy
Cirrus Account Linking
Cirrus External IdP (if used)
|Social Providers||Social Providers
Cirrus External IdP
Cirrus External IdP
|At Gateway||At Proxy||At Proxy|
Step 2 - Determining how sponsors will send invitations
The next planning step is to figure out the process sponsors will use to send the invitations. The integration patterns discussed in Step 1 support three methods for creating the invitation. The first two methods leverage a web based user interface to either send invitations in small numbers (up to about ten) or to upload a comma-delimited file (CSV) to send the invitations.
Sponsors can be authorized to access this interface in the following ways:
Authorize specific eduPersonAffiliation values for sending invitations in the configuration
Authorize by eduPersonEntitlement for sending invitations in the configuration
Authorize specific SP or Org Console administrators for sending invitations in the configuration
The interface for the sponsor looks as follows:
The third option for sending invitations is to use Cirrus APIs to create the invitations. The APIs support creating individual invitations or processing batches contained in a comma-delimited file (CSV). The API option is useful when the sponsor interaction will be taking place in another system (for example a student requesting access for a parent from within the student administration system).
Step 3 - Consider Messaging
The third planning step is to consider the messaging that will be used with both sponsors, and end users. The Invitation solution provides a basic workflow of email messages and online dialog to enable the claiming process. Where appropriate, Cirrus Identity has made these messages configurable by the customer with options to include dynamic content. Customers will want to consider the following as they configure messaging:
Is the messaging going to be specific to one service provider, a group of service providers, or generic for the whole organization?
Is the messaging going to be for a specific audience (for example applicants or alumni) or will it need to cover a broader audience of external access end users?
How much detail should be provided in the messages? Is there an option to have simpler messages and provide a link to a central knowledge base or FAQ on the organization’s website?
To help with your planning, see “Invitation | Message Setup” for descriptions and available dynamic content options for each of the Invitation email and dialog messages.
Cirrus Invitation “Hello World”
Customers subscribing to Cirrus Invitation will have the Invitation capability enabled for the customer’s organization. This is set by Cirrus Identity and customers should contact “firstname.lastname@example.org” if there is a belief it should be enabled. This can be verified by looking at the bottom of the “Organization” page on the “My Org” menu as follows:
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:
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.
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:
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 Cirrus Identity Support (email@example.com) for configuration.
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).
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.
From the Cirrus Console, an org admin will configure the organization level Invitation settings found on the “My Orgs | Invitation Service” page:
Configure the invitation time-to-live -- this can be overridden if Cirrus APIs are used to send invitations
Configure the invitation duration -- this can be overridden if Cirrus APIs are used to send invitations
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.
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.
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 will only be used.
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).
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
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:
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.