Account Linking | Getting Started
Planning Cirrus Account Linking
The Cirrus Account Linking solution is powerful and requires a bit of up front planning to ensure you realize the highest organization-wide value for the integration. Before starting with Account Linking, some initial questions you’ll need to answer:
Who is the target audience to be linked?
Does the audience vary based on the service provider being accessed?
Does the audience vary based on an event happening (for example getting accepted to the university, graduating from university, or paying for a continuing studies course)?
Will the organization initiate the account linking process or will the end user - put another way, should the organization choose to opt the audience into the account linking process or should end users choose for themselves?
What is/are the Service Providers that will be accessed?
Do the Service Providers meet Cirrus Identity Provider Proxy requirements?
Do the Service Providers have an authorization process to control access that is separate from authenticating to the service?
Do the Service Providers use an identifier to drive the authorization process, what is the identifier, and is that identifier known outside of the service?
Do the Service Providers support just-in-time (JIT) provisioning, or is there an automated method (for example an API) to execute the user provisioning process to ensure only authorized (provisioned) users can access the application?
Does the target audience have the needed identifiers to access the Service Providers?
Is there a identity registry that covers the target audience?
Is there a system-of-record that covers the target audience?
Does the organization want to create identifiers for this audience?
Does the organization need Cirrus Identity to provider an identifier?
Which of the following two integration patterns makes the most sense to accomplish account linking for your use case?
Authentication-based account linking (common for Alumni and Retiree use cases where users have had an enterprise account in the past)
Users accessing an application are redirected to a login screen which displays the IdP options for login (discovery)
If a user picks an external IdP, logs in, and the attributes returned have not been seen before, the account linking service redirects the user to a linking page
The user can link by logging in with an existing enterprise account, and the linking identifier is included in the SAML assertion or
The user can link by correctly responding to Knowledge-based ID Verify question and the linking identifier is returned securely JWT
API-based account linking
A user registers with the organization or a target SP and has a unique identifier associated with the organization (ERP identifier or SP-specific identifier)
The organization makes a REST API call to Cirrus Identity which includes the linking identifier for the user, and the user’s valid email address (among other attributes such as default expiry date and any required custom data)
The API call triggers an email to the user with a link to the identity “claim page” which displays the IdP options for login
The chooses the login provider and logs in if they are not already authenticated
The attributes returned from the external identity provider are linked to the internal linking identifier and stored in the Cirrus Identity account linking table
What identity provider(s) are appropriate for the target audience to use for linking?
If the organization is letting end users choose when to link (Question #1.3), how will the end user’s identity be verified?
By logging in to the enterprise identity provider?
By using a knowledge based verification system using a set of questions?
By some other method?
Will current members of the organization (enterprise account holders) also be an audience accessing the service? Will enterprise account holders also be able to link external identity providers and access the application with them?
Cirrus Account Linking “Hello World”
Customers subscribing to Cirrus Account Linking will also subscribe to Cirrus Identity Provider Proxy, and may subscribe to one or more additional modules to support desired implementations. During customer on-boarding, Cirrus staff will provision a UAT Proxy instance and will perform some initial configuration.
The following are the steps needed to get started using Cirrus Account Linking:
Customers should answer Questions 1-6. If help is needed, Cirrus Identity offers generally accepted practices, customer stories, and professional services to help.
Customers will need to coordinate with Cirrus Identity on the details of the identifier that will be used for account linking. Cirrus Identity will need these details to configure the Proxy.
Cirrus Identity will provision a Proxy instance and register the SP side of the Proxy with the InCommon trust federation. This will allow identity providers to access metadata. Identity Providers will need to adjust attribute release to the Proxy for any attributes needed.
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)
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, and Cirrus Invitation each have associated setup. See the “Getting Started” for each module as appropriate:
If there is an identity provider that is needed by the account linking audience, but the metadata for the 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.
From the Cirrus Console, an admin will configure the Cirrus Discovery Service for the SP side of the Proxy. This will be the user interface users are redirected to when they click the “login” button of the SP. All of the identity providers options for the account linking audience, as well as the organization’s enterprise identity provider should be configured (See Cirrus Discovery Getting Started).
Change the configuration for service providers to trust the Proxy IdP. Cirrus Identity will provide the path to the IdP metadata but it will generally be at a URL of the form https://NAME.proxy.cirrusidentity.com/saml2/idp/metadata.php (See Cirrus Proxy Documentation for further details).
Change the configuration for the SP to use the Cirrus Discovery Service - the discovery URL is "https://apps.cirrusidentity.com/console/ds/index" and details for different service provider platforms are available here.
Once these steps are complete, you are ready to use Account Linking with your service provider.