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:

  1. Who is the target audience to be linked?

    1. Does the audience vary based on the service provider being accessed?

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

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

  2. What is/are the Service Providers that will be accessed?

    1. Do the Service Providers meet Cirrus Identity Provider Proxy requirements?

    2. Do the Service Providers have an authorization process to control access that is separate from authenticating to the service?

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

    4. 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?

  3. Does the target audience have the needed identifiers to access the Service Providers?

    1. Is there a identity registry that covers the target audience?

    2. Is there a system-of-record that covers the target audience?

    3. Does the organization want to create identifiers for this audience?

    4. Does the organization need Cirrus Identity to provider an identifier?

  4. Which of the following two integration patterns makes the most sense to accomplish account linking for your use case?

    1. Authentication-based account linking (common for Alumni and Retiree use cases where users have had an enterprise account in the past)

      1. Users accessing an application are redirected to a login screen which displays the IdP options for login (discovery)

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

      3. The user can link by logging in with an existing enterprise account, and the linking identifier is included in the SAML assertion or

      4. The user can link by correctly responding to Knowledge-based ID Verify question and the linking identifier is returned securely JWT

    2. API-based account linking

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

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

      3. The API call triggers an email to the user with a link to the identity “claim page” which displays the IdP options for login

      4. The chooses the login provider and logs in if they are not already authenticated

      5. The attributes returned from the external identity provider are linked to the internal linking identifier and stored in the Cirrus Identity account linking table

  5. What identity provider(s) are appropriate for the target audience to use for linking?

    1. Social login using Cirrus Gateway?

    2. Cirrus External Identity Provider?

    3. Federated Identity Providers?

    4. Another identity provider?

  6. If the organization is letting end users choose when to link (Question #1.3), how will the end user’s identity be verified?

    1. By logging in to the enterprise identity provider?

    2. By using a knowledge based verification system using a set of questions?

    3. By some other method?

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

  1. Customers should answer Questions 1-6. If help is needed, Cirrus Identity offers generally accepted practices, customer stories, and professional services to help.

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

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

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

    1. Cirrus Gateway Getting Started

    2. Cirrus Invitation Getting Started

    3. Cirrus External Identity Provider Getting Started

  6. 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 ( for configuration.

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

  8. 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 (See Cirrus Proxy Documentation for further details).

  9. Change the configuration for the SP to use the Cirrus Discovery Service - the discovery URL is "" 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.

Account Linking | Using Cirrus Account Linking

Focus on Access Management and not ID Tracking

NetId, employee ID, UID, card ID, and the Insert-Name-Here-ID -- Organizations invariably have multiple identifiers to manage access to applications. The Cirrus Account Linking service is the solution to connect those identifiers to an external identity (either social or our External Identity Provider accounts) so you can easily manage access for the same user even as they migrate from one identity provider to another.

One Individual with Multiple Digital Identities

You may have a Google email address, Twitter handle, and LinkedIn profile. Each of those digital identities is a slice of the digital “You” shared to a different audience. Account Linking gives you the choice to use one of your digital identities to establish a relationship with an organization by linking it to data the organization maintains.  Organizations can then authorize access to services as appropriate based on internal risk analysis.

Common Uses

  • Applicant Access

  • Alumni Engagement

  • Online Learning

How It Works

Account Linking can happen several different ways, depending on the customer situation and the user audience. The common element is that the digital identity the user chooses, such as Google, Microsoft, or LinkedIn,is connected to data provided by the organization. The linking can take place in an authentication flow (via SAML or JWT) or via  REST based  APIs and the JSON data format. Cirrus Identity provides configurable UI forms and email workflow, making it easy to set up the right account linking flow for our customers.