Gateway | Getting Started

Cirrus Gateway “Hello World”

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

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

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

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

  5. 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 to perform the social provider API integration.

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

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

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

Social Provider Considerations

Several factors go into the selection of which Social Providers to use (Step #2 above). While the target audience will play a significant factor in the selection, there are other aspects of each provider that should also be considered. The table below summarizes:

  1. The availability of an email address - many service providers 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 No Information Available Yahoo! is a mail provider and the returned ID will be a value with a scope of @yahoo.com. This ID and scope will be asserted by the Cirrus Gateway.
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.

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.

Configuring Attribute Release

Overview

Attribute release by the Cirrus Gateway is designed to be privacy-preserving. The Gateway will only release attributes requested by the Service Provider (SP). To accomplish this, the Gateway looks for a list of attributes in the SP's metadata. These attributes are listed in the AttributeConsumingService section of the metadata. If the Gateway finds attributes in this list that map to ones available to release, it will release them to the SP. If there are no attributes listed in the SP's AttributeConsumingService section of metadata (or it doesn’t exist), then the Gateway will release all attributes available from the social provider. See the Gateway Attribute Mappings for more details.

Configuring Attributes to Release

As mentioned above, the Gateway looks for the AttributeConsumingService section in the SP's metadata to determine which attributes to release. The code below shows what this looks like if you want to have givenNamesnmail, andeduPersonPrincipalName released to your SP by the Gateway:

<SPSSODescriptor>
    ....
    <AttributeConsumingService index="1" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">
        <RequestedAttribute FriendlyName="givenName" 
          Name="urn:oid:2.5.4.42" 
          NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"/>
        <RequestedAttribute FriendlyName="sn" 
          Name="urn:oid:2.5.4.4"
          NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"/>
        <RequestedAttribute FriendlyName="mail" 
          Name="urn:oid:0.9.2342.19200300.100.1.3"
          NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"/>
        <RequestedAttribute FriendlyName="eduPersonPrincipalName" 
          Name="urn:oid:1.3.6.1.4.1.5923.1.1.1.6" 
          NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"/>
    </AttributeConsumingService>
</SPSSODescriptor>

Set Attributes in the InCommon Federation Manager

If you are a member of the InCommon Federation, then set the Service Provider requested attributes using the InCommon Federation Manager (FM). If you do not have access to the InCommon FM, and you are not sure whom to contact, you can look up the contact information for your organization on the InCommon Service Categories page.

The image below shows the "Requested Attributes" (see red arrow) section of the Service Provider configuration page in the InCommon Federation Manager application. In the image, we have already selected the four attributes we want, and are displaying the popup list which shows other available attributes to select (but note, the Cirrus Gateway does not necessarily support them).

Metadate.png

Gateway | Social IdP Integration

Adding additional Service Providers with same social provider API integrations

You may decide to use the same Social Identity Provider integration across multiple Service Providers in your organization. For a single service, you may have different dev, test, and production instances where you want to share the same API Key and Secret. Or, you may wish to have the same unique identifier for all Facebook users (Facebook and LinkedIn generate a unique identifier which is tied to a particular API integration, similar to an eduPersonTargetedID).

This article contains instructions for settings in the Cirrus Identity console that allow sharing an API Key and Secret with multiple Service Providers. 

For each social provider, you must set an API Key and secret for the first SP. See Social Provider API Integrations for Your First Service Provider

You can share this API Key and Secret across multiple Service Providers, but you must add a new authorized redirect URI for each Service Provider to the social providers API settings. 

Important note: Twitter does not support the addition of authorized redirect URIs for more than one Service Provider.

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

  1. Be sure you know the credentials for the user account at the social provider that was used with the initial API integration. 

  2. Log into the Cirrus Identity console and navigate under the MySPs tab to the Service Provider that has the existing API Key and Secret.

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

Social IP.png

Then, still in the configuration page for the new Service Provider, on the right side of the screen, scroll down the API Setup Guide Window until you find the authorized redirect URI generate by the console for the new Service Provider.

Social IP 2.png

Copy the redirect URI for that provider. Then scroll back to the top of the API Setup Guide window and click the link to go to that provider's developer console.

Social IP 3.png

Adding Authorized Redirect URIs to social provider developer consoles

Now you'll need to scroll down the API Setup Guide in the Cirrus console for each social provider and copy the authorized redirect URI for the new Service Provider you are setting up, and then navigate to the place in the social provider developer console where you can paste that into the API settings.

Please refer to the article on setting redirect URIs for instructions on where to paste those links you copy from the Cirrus console.

Adding Authorized Redirect URLs to social provider API settings

If you are sharing an API Key and Secret with more than one Service Provider, you will need to add an Authorized redirect URI for each Service Provider that shares the API key and secret. See this article for details of why you may want to do this. This article contains instructions for adding the Authorized Redirect URIs for social providers where appropriate. 

Note: AOL and Yahoo use OpenID so you do not need to set an API Key and Secret or an authorized redirect URI.

Note: Twitter does not support more than one Authorized Redirect URL for an integration, so you cannot share a Twitter API Key and Secret with more than one Service Provider.

To add Authorized Redirect URIs for each social provider:

  1. Make sure you have the credentials to the social provider developer console handy as you will need to update the settings there.

  2. In the Cirrus Console, choose the Service Provider from the drop-down list under the MySPs tab.

  3. Choose the social provider icon from the left nav bar

  4. Go to the API Setup Guide window on the right

  5. Scroll down to the authorized redirect URI the console has generated for that Service Provider

  6. Copy the authorized redirect URI

  7. Scroll back to the top of the API setup guide and click the link to log into the developer console for that social provider

  8. Find the place where you can add authorized redirect URIs (see below for instructions), and paste in the authorized redirect URI generated by the Cirrus console.

Facebook

Once logged in to the Facebook developers console:

Choose the Service Provider that is already integrated (the one with the API Key and Secret you are going to share with the new application).

On the dashboard, choose "settings" from the left nav bar

Choose "advanced" from the middle panel

Adding Redirect URLs.png

Google

Once in the Google console, click "Enable APIs and Get Credentials Like Keys"

Choose the "Google + API"

Choose "Credentials" in the left nav bar

Choose the name of the integration in the middle panel

Paste the Authorized redirect URI you copied from the Cirrus console into the Google Cloud Platform console

Redirect URLs 2.png

LinkedIn

Log in to developer's console

Choose the application that is already integrated (the one with the API Key and Secret you are going to share with the new application).

Scroll down to field for adding redirect URIs

Redirect URLs 4.png

Twitter

Note for Twitter you can add only ONE redirect URI, so you cannot share the same API Key and Secret across multiple Service Providers when you integrate with Twitter  

Log in to developer's console

Choose settings from the top nav bar

Scroll down and paste the link into the "callback URL" box

Redirect URLs 5.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 developer's console

Navigate to settings

Choose the API settings tab

Scroll down and enter the "redirect URLs"

REMINDER: Yahoo use OpenID so you do not need to set an API Key and Secret or an authorized re-direct URL

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 provider and you don't need to set an API Key and Secret

Twitter, Weibo, and Microsoft

Document the accounts you use to set up integrations with Twitter, Weibo, and/or Microsoft. You can send Cirrus Identity the account names you used (but not the credentials) and we'll keep track of them in case you forget in the future.

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 "setting"

Adding multiple administrators for your API Integration with social identity providers

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 and Microsoft allow only one account to administer the API integration

  3. AOL and Yahoo are OpenID providers and you don't need to set an API Key and Secret

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

If you are integrating with Twitter or Microsoft, be sure to document the accounts you used to set up the initial integrations.  You can send Cirrus Identity the account names you used and we'll keep track of them in case you forget in the future.

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 "Permissions" 

  • Then choose "Add Users"

Google Cloud Platform 2.png
Google Cloud Platform 3.png
Google Cloud Platform 4.png

Facebook

  • Log in to 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"

Facebook.png
Facebook 2.png

LinkedIn

  • Log in to LinkedIn developers console

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

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

  • Then add developers to the input field (you will need to have a first level LinkedIn connection to the admins you add)

LinkedIn.png
LinkedIn 2.png

Gateway | Attribute Mappings

The Cirrus Gateway attempts to map 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.