Discovery | Planning Steps

Step 1 - Determine your audience

The first planning step for Cirrus Discovery is to determine the audience and which identity providers that audience will need:

  • Will the audience primarily use social login options provided by Cirrus Gateway (Google, Facebook, Microsoft, LinkedIn, or others)?

  • Will the audience use the Cirrus External Identity Provider?

  • Will the audience use the organization’s primary/enterprise identity provider?

  • Will the audience use other organization identity providers?

  • Will the audience use identity providers from InCommon or other eduGain federations?

The answers to these questions will influence the style of Discovery you choose.

Step 2 - Determine the desired end user experience

The second planning step is to determine the desired experience for end users to discover the identity provider there are going to use for login:

  • Are end users going to be just directed to the Service Provider, and a discovery page should appear if needed?

  • Are end users going to be directed to a website page, and discovery should be embedded on that page?

  • Do we want to avoid discovery, and we know enough about each audience segment that we just want to embed static links on one or more website pages?

The answers to these questions will also influence the style of Discovery you choose.

Step 3 - Interactions with other Cirrus Modules / Features

Some Cirrus Modules have constraints that can influence how Discovery is configured:

Step 4 - Select the style of Discovery to implement

The most common choice is to use a SAML compliant discovery service, and the easiest is to use Cirrus Discovery integrated with the Cirrus Identity Products. Cirrus Discovery operates in two basic modes: “List Style” and “Button Style”. The following table providers a comparison between the two styles:

Discovery Style Button Style List Style
Recommended Number
of Identity Providers
Less than Ten Large Numbers
Supports Federated IdPs Yes Yes
Supports Social Login Yes Yes
Supports Custom IdPs Yes Yes
Control Display Order
of IdPs
Yes Yes
Add Header/Footer Text Yes Yes
Customize IdP Branding
(non-social IdPs only)
Yes No
Add Text Between IdPs Yes No
Put IdPs on Different Tabs No Yes
Search Box for IdPs No Yes
Supports iframe
Embdedding
No Yes

Customer can also choose to bypass discovery. This choice is useful in those cases where the navigation for an audience is well understood (for example going from a portal to an application). For more information, see “Cirrus Identity Provider Proxy discovery configuration” or contact Cirrus Support.

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

Discovery | Getting Started

Customers will often subscribe to one or more additional Cirrus Identity modules to support desired implementations. Cirrus Discovery is included with all Cirrus Identity subscriptions.

The following steps are needed to get started with Cirrus Discovery:

  1. Customers should take a moment and think about their Discovery Deployment. Cirrus Identity can offer generally accepted practices, customer stories, and professional services to help. Reviewing the questions covered by the Cirrus Discovery | Planning Steps is a good first step:

    1. Determine your audience

    2. Determine the desired end user experience

    3. Interactions with other Cirrus Modules / Features

    4. Select the style of Discovery to implement

  2. Depending on the customer, Cirrus will provision other modules based on the customer’s subscription (or trial/PoC agreement). Modules such as Cirrus Gateway, Cirrus Invitation, Cirrus Account Linking, Cirrus External Identity Provider, and Cirrus Identity Provider Proxy each have associated setup. See the “Getting Started” for each module as appropriate:

    1. Cirrus Gateway Getting Started

    2. Cirrus Account Linking Getting Started

    3. Cirrus Invitation Getting Started

    4. Cirrus Identity Provider Proxy Getting Started

    5. Cirrus External Identity Provider Getting Started

  3. If there is an identity provider that is needed by the Discovery audience, but the metadata for the IdP is not published to federation metadata (for example InCommon or eduGAIN), the metadata needs to be sent to Cirrus Identity Support (support@cirrusidentity.com) for configuration.

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

  5. If the SP (or SP side of a Cirrus Identity Provider Proxy) has not already been defined in the Console, an org admin will create the SP in the Console so it can be configured. At this point, the org admin may also designate an SP admin to complete the setup.

  6. From the Cirrus Console, an admin will start the Discovery configuration by picking the required identity providers -- social providers will automatically be included based on the Cirrus Gateway configuration (see Cirrus Gateway Getting Started).

  7. From the Cirrus Console, an admin will then:

    1. Adjust the ordering of the identity providers

    2. Choose either “Button Style” or “List Style”

    3. For “Button Style”; branding for the IdP buttons should be applied, and any text between the IdP buttons

    4. For “List Style”; configuration of separate tabs will be set, configuration for use with iframes, and configuration for search will be set

    5. Any desired header or footer text can be added

  8. From the Cirrus Console, the admin can save and preview the Discovery configuration

  9. Change the configuration for all SPs that will use Cirrus Discovery - the discovery URL is "https://apps.cirrusidentity.com/console/ds/index". Details for configuring a Shibboleth SP are available here.

Once these steps are complete, you are ready to use Discovery.

Discovery | Configuring Discovery on SP

How to configure your service provider to use discovery depends on what SAML aware software product you use, and if you are using the embedded or standalone discovery.

Below are sample configurations of the most common setups our customers use.

Using the Cirrus SAML Proxy?

If you are using your SP with Cirrus's SAML proxy then you do not need to configure discovery on your SP. You configure your SP to use the proxy for authentication and the proxy will take care of showing the correct discovery interface when a user logins. See Shibboleth Configuration Examples for how to use the proxy.

If you are trying to customize the user experience for discovery at your SP when using proxy then view your options.

Using the Gateway directly?

If you are using Cirrus gateway directly with your SP then you can configure your SP to use the Cirrus discovery service.

Shibboleth

Shibboleth supports configuring a discovery URL in the <SSO> block inside shibboleth2.xml

<SSO discoveryProtocol="SAMLDS" discoveryURL="https://apps.cirrusidentity.com/console/ds/index">
        SAML2 SAML1
</SSO>

You simply provide a URL to the Cirrus discovery service and Shibboleth will add on any required query parameters.


SimpleSAMLphp

SSP supports configuring a discovery URL in your SAML:SP authsource.

 

$config['my-sp'] = array(
    'saml:SP',
     // A bunch of your configuration
    'idp' => NULL,
    'discoURL' => 'https://apps.cirrusidentity.com/console/ds/index',
);

 

You set the 'discoURL' to the Cirrus discovery service and set 'idp' to null (or ensure it is not set)

Spring Security SAML

Spring security expects a non-standard query parameter name (idp instead of entityID )in the response from the discovery service. You will need to tell the discovery service to use this alternate name using the returnIDParam name.

https://apps.cirrusidentity.com/console/ds/index?returnIDParam=idp&otherSetting