Tables of Contents 1. Overview 2. Planning Steps 3. Getting Started 4. Using Cirrus Account Linking...
Cirrus Gateway Documentation
Table of Contents
1. Overview
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
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 |
|
OpenID Connect |
||
Microsoft |
OpenID Connect |
This includes Outlook, Hotmail, MSN, Skype, and Windows Live accounts; Office365 domain accounts can also be used if the API integration is properly configured. |
|
|
OpenID Connect |
||
Amazon |
OAuth2 |
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 |
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. |
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. |
|
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.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.
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.
<a data-preserve-html-node="true" href=https://md.cirrusidentity.com/metadata/CirrusIdentitySocialProviders-Google-metadata.xml>https://md.cirrusidentity.com/metadata/CirrusIdentitySocialProviders-Google-metadata.xml | |
Microsoft | <a data-preserve-html-node="true" href=https://md.cirrusidentity.com/metadata/CirrusIdentitySocialProviders-Live-metadata.xml>https://md.cirrusidentity.com/metadata/CirrusIdentitySocialProviders-Live-metadata.xml |
<a data-preserve-html-node="true" href=https://md.cirrusidentity.com/metadata/CirrusIdentitySocialProviders-LinkedIn-metadata.xml>https://md.cirrusidentity.com/metadata/CirrusIdentitySocialProviders-LinkedIn-metadata.xml |
<MetadataFilter type="RequireValidUntil" maxValidityInterval="1209600"/>
</MetadataProvider>
<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.
$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
Blog comments