Cirrus Account Linking Documentation

Tables of Contents

1. Overview

2. Planning Steps

3. Getting Started

4. Using Cirrus Account Linking

Overview

Traditionally organizations have focused on maintaining user access accounts that are distinct and tightly integrated with the organization’s operational procedures. As organizations try to improve the customer experience, the need to provide online access to larger numbers of audiences with looser affiliation strains this operational practice.

Cirrus Account Linking provides solutions to manage access for these loosely affiliated end users without the need to provision new access accounts. By addressing complex access lifecycle issues, the Account Linking solution can allow access to:

Cirrus Account Linking is based on a few principles:

  1. End users use non-enterprise accounts that are appropriate for the services being accessed (social login or other third party identity provider) instead of creating new enterprise user accounts
  2. Service providers differentiate between being able to authenticate and being authorized to access the service -- access is based on an organizational identifier the end user has been assigned
  3. The account an end user uses to accesses the organization’s services will change over time, for example from social login, to enterprise login, and then back to social login. To streamline access across the lifecycle, the organization can identify the end user based on one or more enterprise identifiers associated with the account
Cirrus Identity Account Linking Solutions - connect accounts from your IDP, social logins (via the Cirrus Identity Gateway) and other services to provide logins to any of your enterprise applications.

The Cirrus Account Linking service is integrated with the Cirrus Identity Provider Proxy and they work in tandem to enable access. This will lead to a deployment where the Proxy stands between the Service Providers and the Identity Providers. In general, any service provider and identity provider that supports SAML v2.0 or CAS can be accommodated by the Proxy. See the Proxy documentation for SP and IdP support details.

Account Linking also integrates with other Cirrus Services depending on the end user identity provider needs and desired implementation patterns. The solutions are:

    • Cirrus Discovery - Used to provide the discovery UI for the Proxy; Discovery is also InCommon/eduGAIN aware so it also enables linking federated identity providers
    • Cirrus Gateway - Used to enable linking of social login accounts (for example Google, Facebook, Microsoft, LinkedIn, or others)
    • Cirrus APIs - Used to integrate organization data sources with Cirrus Account Linking

    Cirrus Account Linking is implemented using one of three base implementation patterns:

    1. User Initiated Account Linking (Authentication Based) - The end user authenticates with an account the individual prefers (often a social login), and that account is linked to an organizational identifier using one of several methods:
    • By logging in with the organization’s primary enterprise identity provider
    • By using a knowledge based verification system which traditionally asks the end user a series of questions to establish the relationship to the organization
    • By pre-provisioning the account linking information using Cirrus APIs to establish the relationship to the organization
    2. Organization Initiated Account Linking - The organization typically makes an API call that triggers the Cirrus Invitation service to send an email to the user. Users click a unique URL in the email and land on a "claim" page where they see a list of login providers they can choose from (see Discovery Configuration for more information on choosing the list of providers). In the process, the account is linked to the organizational identifier using one of several methods:
      • When the organization creates the request, the organizational identifier is attached to the request which is linked to the account at the time of claim
      • When the end user claims the request and the organization is notified of the claim, the organization issues an organizational identifier to link to the account after the claim
      • The organization leverages the unique ID that Cirrus creates at the time of claim as the identifier

    3. Self-Registration -- This is a separate add-on that you can use with the Account Linking service and is discussed here

    Planning Steps

    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?

    • 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?

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

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

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

    Option 1: User Initiated Account Linking (authentication-based) commonly used 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 via JWT

    Option 2: Organization Initiated Account Linking using APIs

    • 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

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

    6) 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?

    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?

    Next, you will want to look at Cirrus Account Linking - Getting Started.

    Getting Started

    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 take a moment and think about their Account Linking Deployment. Cirrus Identity can offer generally accepted practices, customer stories, and professional services to help. Reviewing the questions covered by the Cirrus Account Linking | Planning Steps is a good first step:

    • Who is the target audience to be linked?
    • What is/are the Service Providers that will be accessed?
    • Does the target audience have the needed identifiers to access the Service Providers?
    • Which of the Account Linking integration patterns (authentication-based or API-based) makes the most sense for your use case?
    • 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 (see the details for Question 1.1), how will the end user’s identity be verified?
    • 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?

    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 OrgBrandedID, and Cirrus Invitation each have associated setup. See the “Getting Started” for each module as appropriate:

    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 (support@cirrusidentity.com) 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 "https://NAME.proxy.cirrusidentity.com/saml2/idp/metadata.php" (See Cirrus Proxy Documentation for further details).

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

    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, our External Identity Provider, the EduAccessID, or a federated partner) 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

    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.

    © Copyright Cirrus Identity, Inc.

    Blog comments