Cirrus Gateway Documentation

Cirrus Product Documentation
May 14, 2024 11:20:23 AM

Table of Contents

Overview of Configuration

Configuration Information: Establish Shared API Key

Configuration Information: Connect Cirrus Proxy with Cirrus Gateway

 

Many applications provide a way to enable login from personal account identity providers (such as Google, Microsoft, Apple, or others). These solutions tend to only work with a single application, whereas end users rarely use a single application in an organization.

The Cirrus Gateway is a solution that allows a number of personal account providers to be integrated with any organization application or hosted service. The Gateway is used in conjunction with the Cirrus Identity Proxy which facilitates the integration with target applications.

Customers must establish integrations with each personal account provider. These take the form of keys and secrets shared between the provider and the Cirrus Gateway. Cirrus Identity maintains the Gateway as a hosted solution. There is nothing customers run onsite.


The Cirrus Gateway currently supports the following personal account providers:

  • Amazon
  • Apple
  • Google
  • LinkedIn
  • Microsoft
  • ORCID

 

Customers must select which personal account providers to allow. The following factors can influence selection of different providers:

  • The targeted audience – for example if primarily a research audience ORCID may be useful, versus casual users where Google, Microsoft, and Apple would be sufficient
  • The organization’s policies and procedures – each organization may choose certain providers based on other organization choices
  • Cirrus would recommend Google, Microsoft, and/or Apple as a starting set of providers

 

Overview of Configuration

The following are pre-requisites to start using the Cirrus Gateway:

Pre-requisite 1 - Based on the Customer’s subscription, Cirrus Identity Customer Success will need to enable the Cirrus Identity Gateway for the organization and the specific providers an organization wishes to use.

 

Pre-requisite 2 - A Customer staff member needs to have access to the Cirrus Console and to be granted the “Organization Administrator” (org admin) role for your organization.

 

Pre-requisite 3 - A Cirrus Identity Proxy tenant must exist to enable the Cirrus Gateway.

 

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

 

Step 1 - An Org Admin should create a Shared API Key within the Cirrus Admin Console for each provider that will be integrated with the Proxy tenant. The Org Admin will need a developer account for each Gateway provider to complete the integration. For each enabled provider, the Org Admin will follow the instructions available in the Console. Multiple Shared API Keys can be configured for the same provider depending on the needs of the Customer.

 

Step 2 - Once Shared API Keys are defined, the Org Admin will enable the Cirrus Gateway at the Proxy tenant level. Part of this configuration will be to enable the specific providers that will be used for the Proxy tenant and specify which Shared API Key should be used.

Once these steps are complete, the Gateway will be ready to use.

 

Configuration Information: Establish Shared API Key

This section contains instructions for setting Shared API Keys for one of the personal login providers supported by the Cirrus Gateway.

Before starting, the Org Admin will need a developer account for each personal login provider to be integrated. The detailed instructions for integrating each provider are presented in the Cirrus Console on the right side of each Shared API Key configuration. For each provider, the following general steps will be required:

Step 1 - Navigate to the provider developer console from the link provided in the Cirrus Console Shared API Key configuration and define an application that will lead back to the Cirrus Gateway.

Step 2 - If needed, perform steps to set permissions to access data. For example, LinkedIn has separate permissions to release the email address.

Step 3 - If needed, perform necessary steps to establish your brand for the provider integration including uploading a logo, and providing a link to terms-of-service or privacy policy.

Step 4 - Create an API key value with the associated API secret, and copy those to the Cirrus Console Shared API Key configuration.

Step 5 - Set the redirect URI provided in the Cirrus Console Shared API Key configuration for your new provider integration.

 

The following is a screenshot of the Cirrus Console Shared API Key setup for Microsoft (sensitive data has been redacted):

 

Configuration Information: Connect Cirrus Proxy with Cirrus Gateway

This section contains instructions for configuring the Gateway Provider for a specific Cirrus Proxy tenant:

 

Step 1 - Navigate to the Cirrus Proxy tenant SP configuration by either selecting the Cirrus Proxy tenant from the menu above, or by selecting it from the list of Proxies on the dashboard.

 

Both routes will take you to the Proxy Details configuration. Select “Discovery Service”.

 

Step 2 - Once you reach the Discovery Service, select “Gateway Service” from the menu on the left. Enable the Cirrus Gateway from the Gateway Service page, and select the specific providers to be used with the proxy tenant. The other fields on the Gateway Service page can be left to their defaults unless advised by Cirrus Identity Customer Success. Save the settings when complete.

 

Step 3 - After saving the changes to the Gateway Service page, configuration options for each of the enabled providers will show up in the left menu. To configure each, select them one at a time.

 

NOTE - SP-Specific API Configurations are being deprecated and should not be configured unless instructed to do so by Cirrus Identity Customer Success.

 

Step 4 - To configure each provider, click on the configuration item. At the top, you should always select “Shared API Key” from the “API Setup Option”. Select a Shared API Key from the drop down list (if you do not see one, you will need to first set up a Shared API Key). Unless otherwise advised by Cirrus Identity, ePPN Configuration should be set to “Unique ID Scoped to…”. Press Save when complete.

 

NOTE - If the provider is LinkedIn, there is an additional setting to request the email address – there are also additional steps that must be configured on the LinkedIn side of the integration.

 

Step 6 - The providers are automatically added to the Discovery Service configuration for the Proxy tenant. You should review the Discovery Service configuration after adding or removing any Cirrus Gateway providers.

 

Once enabled, the providers are active. You can use the “Test Login” option at the lower right of each provider to verify the configuration is working.

© Copyright Cirrus Identity, Inc.