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

  1. The availability of an email address - many service providers or use cases require an email address to provision a user profile

  2. How an ePPN will be constructed - Cirrus Identity generally recommends using the Social Provider’s internal ID with a scope

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

  4. 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 of API 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”. See https://developers.google.com/+/web/api/rest/?hl=en_US#quota for more details. 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.
Facebook Available - user can change Unique ID scoped to the provider (@facebook.com)

ID tied to API Key
”Rate limiting in the Facebook Graph API should be encountered only in rare circumstances.” See https://developers.facebook.com/docs/graph-api/advanced/rate-limiting for more details. Facebook returns an "application scoped" ID, (i.e. a targeted ID). This means that each SP that has its own integration with Facebook, will get a different ID for the same user. If you are planning to use the Cirrus Identity Invitation Service, you must share the same API Key/Secret with each SP that will be integrated with Facebook
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.
Twitter Available - user can change Unique ID scoped to the provider (@twitter.com)

ID tied to user
A formula but generally 15 calls in 15 minutes per user token. See, https://dev.twitter.com/rest/public/rate-limiting for more details. Twitter provides an ID that is unique to the user and we recommend that you use this ID. The ID will be scoped to @twitter.com by the Cirrus Gateway.
Weibo Not available Unique ID scoped to the provider (@weibo.com)

ID tied to user
“...So the limit value is not fixed, different applications have different restrictions, depending on the application of their own quality.” From http://open.weibo.com/wiki/%E6%8E%A5%E5%8F%A3%E8%AE%BF%E9%97%AE%E9%A2%91%E6%AC%A1%E6%9D%83%E9%99%90 using Google Translate, see for more details. Weibo provides an ID that is unique to the user and we recommend that you use this ID. The ID will be scoped to @weibo.com by the Cirrus Gateway.
Instagram Instagram is deprecating their API and moving the functionality into Facebook's Graph API. There is no published migration path for Instagram Authentication. You can view Instgram's blog post (https://developers.facebook.com/blog/post/2018/01/30/instagram-graph-api-updates/).

Next, you will want to look at Cirrus Gateway | Getting Started.

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 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 Initial Social Provider API Integrations).

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

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

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

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

Provider
Metadata
Google https://md.cirrusidentity.com/metadata/CirrusIdentitySocialProviders-Google-metadata.xml
Facebook https://md.cirrusidentity.com/metadata/CirrusIdentitySocialProviders-Facebook-metadata.xml
Microsoft https://md.cirrusidentity.com/metadata/CirrusIdentitySocialProviders-Live-metadata.xml
LinkedIn https://md.cirrusidentity.com/metadata/CirrusIdentitySocialProviders-LinkedIn-metadata.xml
Yahoo! https://md.cirrusidentity.com/metadata/CirrusIdentitySocialProviders-Yahoo-metadata.xml
Twitter https://md.cirrusidentity.com/metadata/CirrusIdentitySocialProviders-Twitter-metadata.xml
Weibo https://md.cirrusidentity.com/metadata/CirrusIdentitySocialProviders-Weibo-metadata.xml

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 Automated Metadata Management documentation.

Gateway | 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 Facebook, LinkedIn, or Twitter; 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).

google_api_integration_redacted.png

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 - Both Facebook and LinkedIn generate a unique identifier which are 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.

google_api_copy_key_secret.png

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 .

google_api_redirect_uri.png

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.

Facebook

Once logged in to the Facebook developers console:

Choose the application that is already integrated (the one with the matching API Key).

On the dashboard, choose "Facebook Login | Settings" from the left navigation bar

Add the Authorized redirect URI you copied from the Cirrus console to the list of Valid OAuth Redirect URIs and click Save

fb_redirect_uri.png

Google

Once in the Google console, select the project appropriate for your integration

Choose the "APIs & services | Credentials from the left navigation bar"

Click on the name of the defined OAuth 2.0 client IDs

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

google_redirect_uri.png

LinkedIn

Log in to the developer's console

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

Go to the Auth panel and edit the OAuth 2.0 settings

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

linkedin_redirect_uri.png

Twitter

Log in to the developer's console

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

On the App details panel, click the “Edit” button to modify the list of Callback URLs

Add the Authorized redirect URI you copied from the Cirrus console to the list of Callback URLs for the application and click Save

twitter_redirect_uri.png

Weibo

Log in to Open Weibo site

Select the application under My Applications

Under the Application menu select Advanced

Click edit in the OAuth2.0 authorization settings and enter the link as the Authorization callback page

Redirect URLs 6.png

Microsoft

Log in to the developer's console

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

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 of the page

microsoft_redirect_uri.png

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, Facebook, and LinkedIn allow you to add more than one administrator for an application integration with their identities. 

  2. Twitter, Weibo, and Microsoft allow only one account to administer the API integration

  3. Yahoo in an OpenID v2 provider and you don't need to set an API Key and Secret

Record the account name used to set up 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:

Gateway - Record Account Used for Integration.png

We highly recommend you establish multiple administrators. Below are instructions for setting more than one admin for Google. 

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

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

  • From the menu, choose "APIs & Services | IAM"

  • Then choose "Add"

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

google_muliple_user_a.png
google_muliple_user_b.png
google_muliple_user_c.png

Facebook

  • Log in to the Facebook developers console

  • From the Facebook developers console, select the application for which you're adding admins

  • From the menu in the left nav bar, choose "Roles" 

  • Then choose "Add Administrators"

fb_multi_dev.png

LinkedIn

  • Log in to the LinkedIn developers console

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

  • Select the “Team members” panel 

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

linkedin_multi_dev.png

Gateway | 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

Facebook [3]

Attribute SAML/MACE Dir Attribute
first_name givenName
last_name sn
name cn
id@facebook.com [1] eduPersonPrincipalName

Microsoft

Attribute SAML/MACE Dir Attribute
first_name givenName
last_name sn
name cn
mail['account'] mail
id@live.com eduPersonPrincipalName

LinkedIn [3]

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

Yahoo!

Attribute SAML/MACE Dir Attribute
http://axschema.org/namePerson displayName
http://axschema.org/contact/email mail
http://axschema.org/contact/email eduPersonPrincipalName

Twitter [3]

Attribute SAML/MACE Dir Attribute
name cn
screen_name displayName
id@twitter.com eduPersonPrincipalName

Weibo

Attribute SAML/MACE Dir Attribute
name cn
screen_name displayName
id@weibo.com eduPersonPrincipalName

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

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

  3. Facebook, LinkedIn, and Twitter 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.