This guide is designed to make setting up your service provider/application in the Gateway Admin Console as smooth as possible.

The instructions below mention the InCommon Federation, but if your institution is a member of another federation or you need a custom metadata setup, send us an email and we will help you track down the appropriate information.

  1. Make sure your SP is registered in your federation’s metadata
  2. Make sure you have set up a SAML DiscoveryResponse endpoint in the metadata
  3. Figure out your "application response location"
  4. Make sure you have accounts with all of the social providers you plan to use with your SP
  5. Gather up the names of the Identity Providers you intend to include in the Discovery Service
  6. Make sure your institutional IdP trusts the Cirrus Gateway Console SP
  7. Login to the Cirrus Gateway Console

1. Register SP With Your Federation

The Cirrus Gateway is designed to work with the SPs from many different federations. The US Higher Education federation is InCommon, and the metadata for the various IdPs and SPs in the federation is managed via the Federation Manager App. If you are a member institution of InCommon (you can view the list on their Current InCommon Participants page), make sure your SP is registered with InCommon. If you are not sure, contact your campus/institution Identity Management group to verify (you can find your campus contact listed on theInCommon IdPs page). If you need a custom metadata setup, and you haven't already discussed that with us, send us email.

2. Set SAML DiscoveryResponse In Metadata

One of the pieces of information that can be supplied about your SP to the InCommon Federation Manager is something called the "Discovery Response Endpoint". This information is usually generated by your SP software, but since it is not mandatory in the Federation Manager App, sometimes the information is not entered. This SAMLDiscoveryResponse endpoint must be entered into the form for your SP. If you have questions about what this endpoint value is, contact your campus/institution Identity Management group, and they should be able to help you figure out what this is. If not, contact, and we can provide you with guidance.

3. Application Response Location

A SAML service provider needs to know where to send a user after he or she has authenticated and the service provider has handled the authentication request for the user. This location is the “application response location”, and it is a URL on your application which usually handles logging a user into the application itself.

4. Social Provider Accounts

In order to allow your application/service provider to use social providers with the Cirrus gateway, you need to establish an OAuth key and secret with each of the providers you wish to use. By doing this setup, you are setting up a trust relationship between your SP, Cirrus, the social provider, and the end-user. You do this by providing details about your application, like name, site URL, logo if you have one, etc., and in exchange the social provider gives you a key that is good only for your application. When this key is presented to the social provider, that is the clue for the social provider to present the user with information about your application.

This will make a lot more sense once you are in the process of setting up your OAuth key and secret (step-by-step instructions are provided for you in the Gateway Admin app itself), but in the mean time, make sure you can log into the following locations (if you are going to be using the provider). This will save you a lot of time later.

NOTE: Some providers allow you to add more than one person to manage the integration. Take advantage of the option when available and/or establish a dedicated administrative account for these integrations. Doing so will avoid relying on a single individual to maintain the integration.

There is a dedicated article with more information on managing social providers HERE.

5. Gather Identity Provider Names

Along with the social providers, the Cirrus Discovery Service allows you to include institutional identity providers (IdPs), like your home institution. Also, depending on the nature of the application, you may want to (or already do) allow people from other institutions to log into your application. So, this step is simply here to make sure you have a rough idea of the various IdPs you want to list in the Discovery Service.