Documentation

Cirrus Gateway Documentation

Written by Cirrus Product Documentation | May 14, 2024 6:20:23 PM

Table of Contents

1. Overview

2. Planning Steps

3. Getting Started

4. Configuration Information: Configuring a Service Provider

i. Social Provider Metadata Configuration

ii. Metadata Configuration - Shibboleth SP

5. Configuration Information: Social IDP Integration

i. Initial Social Provider API integrations

ii. Adding Additional Service Providers with Same Social Provider API integrations

iii. Adding Authorized Redirect URIs to Social Provider Developer Consoles

iv. Managing Social Provider Integrations

6. Attribute Mappings

Overview

Many applications provide a way to enable login from one of several social identity providers (Google, Microsoft, LinkedIn, 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 general purpose solution that allows any of a number of social providers to be integrated with any organization application or hosted service that supports the SAML v2.0 authentication protocol. When the Gateway is used in conjunction with the Cirrus Identity Provider Proxy, customers have a central point to manage social logins. This can be used for a suite of applications or services, more protocol options (including CAS), and additional proxy capabilities.

Customers only need to establish API integrations with each social provider. These take the form of keys and secrets shared between the social provider and the Gateway. No other maintenance required. Cirrus Identity maintains the Gateway as a hosted solution. We deploy changes as each social provider updates API integration rules. There is nothing customers run onsite. We’re on top of the integration details so you can forget about them.

The Cirrus Gateway currently supports the following social providers:

Provider

Protocol

Useful Links

Notes

Google

OpenID Connect

App Console

Sign Up

Sign Up Help

Dev Policy

  

Microsoft

OpenID Connect

App Console

Sign Up

Sign Up Help

Dev Policy

This includes Outlook, Hotmail, MSN, Skype, and Windows Live accounts; Office365 domain accounts can also be used if the API integration is properly configured.

LinkedIn

OpenID Connect

App Console

Sign Up

Sign Up Help

Dev Policy

  

Amazon

OAuth2

 App Console

Sign Up

Sign Up Help

Dev Policy

  

Cirrus Identity continually evaluates the social login offerings based on social provider API support, customer needs, and changes in end user utilization of different social login platforms.  

Planning Steps

The single biggest planning step for the Cirrus Gateway is selecting which social providers to allow. Several factors go into this selection. While the target audience will play a significant factor, there are other aspects of each provider that should also be considered (see table below).

  • The availability of an email address - many service providers or use cases require an email address to provision a user profile
  • How an ePPN will be constructed - Cirrus Identity generally recommends using the Social Provider’s internal ID with a scope
  • Does the Social Provider’s ID statically define the end user, or does it function as a targeted ID that depends on the API integration
  • What is the API rate limit - while usually not a significant issue, most of the Social Providers have rate limits on their APIs
Provider Email Address ePPN Recommendation API Limits Notes
Google Email provider - user cannot change Unique ID scoped to the provider (@google.com)

ID tied to user

“Your application is limited to the number ofAPI calls it can make by a usage courtesy quota. To view the courtesy limit and to request additional quota for your application, in the Google Developers Console, ...” choose “IAM & Admin” in the Google Console and select “Quotas”.

Google provides an ID that is unique to the user and we recommend that you use this ID. The ID will be scoped to @google.com by the Cirrus Gateway.

 
Microsoft Email provider - user cannot change Unique ID scoped to the provider (@live.com)

ID tied to user

No Information Available

Microsoft provides an ID that is unique to the user and we recommend that you use this ID. The ID will be scoped to @live.com by the Cirrus Gateway.
LinkedIn Available - user can change Unique ID scoped to the provider (@linkedin.com)

ID tied to API Key

“... make more than 500,000 daily calls to an API.. ”

See Section 1.4.2 of Terms of Service https://developer.linkedin.com/legal/api-terms-of-use for more details...

LinkedIn only provides a targeted ID for the user is tied to the actual API Key/Secret, and not the LinkedIn application that you associate with your SP. You must share the same API Key/Secret with each of the SPs that will be integrated with LinkedIn.

NOTE: LinkedIn allows you to regenerate the API Key/Secret for any application. If you do this, the user ID will change. If you use LinkedIn, be sure to never change the API Key/Secret.
Yahoo Email provider - user cannot change Email Address

 

We recommend you do not add Yahoo. Yahoo is no longer supporting their OpenID V2 login method. While, Yahoo has released an OpenID Connect login method, our assessment of the implementation indicates a solution that will be both difficult to implement and impractical for customers to manage going forward.
Amazon Available - user can change Unique ID scoped to the provider (@amazon.com)

ID tied to user

 

Amazon provides an ID that is unique to the user and we recommend that you use this ID. The ID will be scoped to @amazon.com by the Cirrus Gateway.

Getting Started

The Cirrus Gateway enables any Service Provider (SP) that supports SAML v2.0 to leverage social login as a method for authentication. It is also quick to setup if the SP supports the use of a SAML based discovery service. If you have an SP that doesn’t quite meet these requirements, consider using the Gateway with the Cirrus Identity Provider Proxy - Getting Started as an integrated authentication solution (the Proxy supports additional protocols).

NOTE: If you are using a Proxy, your target SP will trust the Proxy as its identity provider (IdP), and the “SP” in the instructions below will be for the Proxy (see Cirrus Identity Provider Proxy - Getting Started). The Cirrus Proxy is automatically integrated with the Gateway for social login and you will not need to perform Steps #4 and #7 below.
 
The following are the steps needed to get started using the Cirrus Gateway:
 
1) Customers should take a moment and think about their Gateway Deployment. Cirrus Identity can offer generally accepted practices, customer stories, and professional services to help. Reviewing how to select social providers covered by the Cirrus Gateway - Planning Steps is a good place to start.
 
2) 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).
 
3) From the Cirrus Console, an org admin will enable social providers for the organization -- this should be any social providers an organization wants to allow.
 
4) Cirrus Identity needs the metadata for any service providers (SP) that you want to use with the Gateway. If the SP is registered with one of the eduGAIN federations (InCommon, UK Fed, CAF, or others) we already have it. If not, you can send us the metadata and we will load it (if you anticipate having a high volume of SPs to add, you can set up a metadata aggregate that Cirrus Identity can consume regularly).

5) From the Cirrus Console, an org admin will create the SP in the Console so it can be configured (not for Proxy integration). At this point, the org admin may designate an SP admin to complete the setup.

6) From the Cirrus Console, an admin will enable the desired social providers specific to the SP (this may be a subset of social providers allowed at the org level). The admin will need a developer account for each social provider to complete the API integration. For each enabled social provider, the admin will follow the instructions available in the Console integrate the Social Provider (see Gateway - Social IdP Integration).

7) From the Cirrus Console, an admin will configure the Cirrus Discovery Service -- to enable login via social identity providers, the organization’s enterprise identity provider (see Cirrus Discovery - Getting Started), as well as other federated partners and custom IdPs. Note that customers can run their own Discovery Service if they prefer. See #8 below for links to the Cirrus metadata for the social identity provider endpoints.
 
8) For SPs integrating directly with the gateway (not for Proxy integration), you will need to change the configuration for the SP to consume Cirrus Gateway metadata - the metadata is available at https://md.cirrusidentity.com/metadata/CirrusIdentitySocialProviders-metadata.xml (further details on Gateway - Configuring a Service Provider). 
 
9) Change the configuration for the SP to use the Cirrus Discovery Service - the discovery URL should be set to a value of "https://apps.cirrusidentity.com/console/ds/index" (further details on configuring different service providers).
 
Once these steps are complete, you are ready to use the Gateway.

Configuration Information: Configuring a Service Provider

Social Provider Metadata Configuration

In the Cirrus Gateway, each social provider has its own SAML metadata endpoint. We take each of these endpoints and put them into a metadata bundle. You will need to configure your SAML SP to consume metadata for the social provider IdP endpoints. Since we may add a new social provider to the service at any time, it is best if you refresh the metadata on a daily basis.

NOTE - Customers using the Cirrus Identity Provider Proxy

If you are integrating your SP with the Cirrus Identity Provider Proxy then you probably want to be consuming the metadata for your specific proxy, not the Gateway bundle. Proxies are customer specific and you'll want to follow our instructions on consuming customer metadata.

Social Provider Metadata
An aggregate of the social provider metadata is available at the following URL:
https://md.cirrusidentity.com/metadata/CirrusIdentitySocialProviders-metadata.xml

You can also find per entity metadata for each IdP endpoint for the social providers. 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Metadata Configuration - Shibboleth SP

Metadata for the Shibboleth Service Provider is configured in the shibboleth2.xml file. An example configuration for the Gateway metadata bundle is as follows:

<MetadataProvider type="XML" url="https://md.cirrusidentity.com/metadata/CirrusIdentitySocialProviders-metadata.xml" backingFilePath="/<path to local file>/CirrusIdentitySocialProviders-metadata.xml" reloadInterval="86400">
<MetadataFilter type="RequireValidUntil" maxValidityInterval="1209600"/>
</MetadataProvider>
Replace <path to local file> with the actual path to a file on your server. This file must be writable by the Shibboleth process.

For details on all of the available configuration options, please see the Shibboleth NativeSPMetadataProvider documentation.
 
Metadata Configuration - SimpleSAMLphp Service Provider
 
Metadata for SimpleSAMLphp is best configured using the metarefresh module. An example configuration for the Gateway metadata bundle is as follows:
$config = array(
    'sets' => array(
        'incommon' => array(
            'cron'      => array('daily'),
            'sources'   => array(
                array(
                    'src' => 'https://md.cirrusidentity.com/metadata/CirrusIdentitySocialProviders-metadata.xml',
                ),
            ),
            'expireAfter'       => 60*60*24*4, // Maximum 4 days cache time.
            'outputDir'     => '<path to local directory>',
            'outputFormat' => 'serialize',
        ),
    )
);

Replace <path to local directory> with the actual path to a directory on your server. This directory must be writable by the web server process.

For details on using the metarefresh module, please see the SimpleSAMLphp documentation (https://simplesamlphp.org/docs/stable/index.html)

Configuration Information: Social IdP Integration

Initial Social Provider API integrations

This section contains instructions for setting the initial API key and secret to allow authentication to a Service Provider from one of the social login providers supported by the Cirrus Gateway.
 
Before starting, the Org or SP Admin will need a developer account for each social provider to be integrated. The detailed instructions for integrating each Social Provider are presented in the Cirrus Console along side where the API key and secret must be entered. For each enabled social provider, the following general steps will be required:
 
1) Navigate to the Social Provider developer console from the link provided in the Cirrus Console and define an application
 
2) If needed, perform steps to set permissions to access data from the Social Provider
 
3) If needed, perform necessary steps to establish your brand for the Social Provider integration including uploading a logo, and providing a link to terms-of-service or privacy policy
 
4) Create an API key value with the associated API secret, and copy those to the Cirrus Console
 
5)Set the redirect URI provided in the Cirrus Console for your new Social Provider integration
 
6) Set how eduPersonPrincipalName (ePPN) should be configured — for most integration patterns having it set to “Unique ID Scoped to…” is a good starting point
 
7) If the Social Provider is LinkedIn; setting if the email attribute should be requested
 
The following is a screenshot of the Cirrus Console API setup for Google (sensitive data has been redacted).

Adding additional Service Providers with same Social Provider API integrations

This section contains instructions for settings in the Cirrus Identity console that allow sharing an API key and secret with multiple Service Providers.

You may decide to use the same Social Identity Provider integration across multiple Service Providers for several reasons:

  • For a single service, you may have different dev, test, and production instances where you want to share the same API key and secret.
  • You may wish to have the same unique identifier for all users - LinkedIn generates a unique identifier which is tied to a particular API integration, similar to an eduPersonTargetedID.
  • Administratively, you may want to centralize the number of developer accounts used to manage API keys and secrets, in doing so you may have a consolidated number of key-secret pairs.

Regardless on the strategy, after setting an initial API key and secret for each Social Provider, you can share the key-secret pair across multiple Service Providers. You only need to add a new authorized redirect URI for each Service Provider to the social providers API settings.

To add a new Service Provider using the same API Key and Secret:

1) Log into the Cirrus Identity console and navigate under the MySPs tab to the Service Provider that has the existing API Key and Secret. Be sure you know the credentials for the user account at the Social Provider that was used with the initial API integration.

2) Copy and paste the API Key and Secret from the existing Service Provider to the configuration page for the new Service Provider.

3) While still at the top of the API Setup Guide, open the Social Provider’s developer console in a new window from the link provided.

4) In the API Setup Guide of the NEW Service Provider, scroll down until you find the Authorized redirect URI — this should be added to the authorized redirect URIs associated with the API key in the Social Provider’s console (see the screen shot below).

Adding Authorized Redirect URIs to Social Provider Developer Consoles

This section outlines the adding of additional Authorized redirect URIs in the different Social Provider developer consoles. See the section “Adding Additional Service Providers with Same Social Provider API integrations” for details on copying the API key-secret pairs between different service providers.

If you are sharing an API key-secret pair with more than one Service Provider, you will need to add an Authorized redirect URI for each Service Provider that shares the same API key-secret pair.
 
Google
 
Once in the Google console, select the project appropriate for your integration.
 
1) Choose the "APIs & services | Credentials from the left navigation bar"

2) Click on the name of the defined OAuth 2.0 client IDs.

3) Add the Authorized redirect URI you copied from the Cirrus console to the list of Authorized redirect URIs for the credential and click Save.

LinkedIn

Log in to the developer's console.

1) Choose the application that is already integrated (the one that matches the API Key).

2) Go to the Auth panel and edit the OAuth 2.0 settings.

3) Add the Authorized redirect URI you copied from the Cirrus console to the list of Redirect URIs for the credential and click Update.

 

Microsoft

Log in to the developer's console.

1) Choose the application that is already integrated (the one that matches the API Key).

2) Add the Authorized redirect URI you copied from the Cirrus console to the list of Redirect URLs under Platforms and click Save at the bottom.

Managing Social Provider Integrations

Your organization will need to set up the API integrations with each social identity provider. Because people and organization units come and go, you may want to consider the following options when deciding how to set up your API integrations:

1) Google and LinkedIn allow you to add more than one administrator for an application integration with their identities.

 

2) Microsoft allows only one account to administer the API integration

Record the account name used to set API integrations in the Cirrus Console

Document the accounts you use to set up integrations you integrations on the main setup page for your API Integrations:

We highly recommend you establish multiple administrators.

Below are instructions for setting more than one admin for each Social Login provider.

Remember that you can access the social provider API consoles by going to the Cirrus Console, choosing the social provider from the icons on the left, and then clicking the link on the right in the API integration instructions window.

 

Google

Log in to developers console.

1. From the Google Cloud Platform Dashboard, select the menu button in the far left

2. From the menu, choose "APIs & Services | IAM"

3. Then choose "Add"

4. Add another member with role of “Owner” and click “Save”

 

LinkedIn

Log in to the LinkedIn developers console.

1. From the LinkedIn developers console dashboard, select the application for which you're adding admins

2. Select the “Team members” panel

3. Click the “Add team member” option to add additional admins (you will need to have a first level LinkedIn connection to the admins you add)
 

Attribute Mappings

The Cirrus Gateway maps the attributes returned by each of the Social Providers to appropriate eduPerson attributes. The tables below outlines the current mapping.

Google
 
Attribute SAML/MACE Dir Attribute
given_name givenName
family_name sn
email mail
sub@google.com or email eduPersonPrincipalName
Microsoft
 
Attribute SAML/MACE Dir Attribute
first_name givenName
last_name sn
name cn
mail['account'] mail
id@live.com eduPersonPrincipalName

LinkedIn [2]

Attribute SAML/MACE Dir Attribute
firstName givenName
lastName sn
id@linkedin.com [1] eduPersonPrincipalName

Amazon

Attribute SAML/MACE Dir Attribute
name cn
mail mail
id@amazon.com eduPersonPrincipalName
 
 Notes:

1. LinkedIn IDs are tied to the API key used for integration. If a consistent ID is desired, the same API key must be used for each integration. A LinkedIn ID is mixed case, alphanumeric and can also contain '-','_' and possibly '='.

2. LinkedIn can be configured to return the primary email address. This however can be changed by the user at any time and should not be considered a persistent attribute.

© Copyright Cirrus Identity, Inc.
View full post