Documentation

Cirrus Bridge Documentation

Written by Cirrus Product Documentation | Jul 27, 2022 10:03:38 PM

Table of Contents

1. Overview

2. Planning Steps

3. Getting Started

4. Using Cirrus Bridge


Overview

Multilateral federated identity has become generally accepted practice for most higher education and research organizations in North America, Europe, Asia-Pacific, and increasingly the rest of the World. Unfortunately, many popular commercial solutions for managing identity don’t fully support the technologies for multilateral federation -- relying instead on bilateral registration of each Service Provider (SP) to the Identity Provider (IdP). Additionally many of these solutions don’t support the popular single sign-on (SSO) protocol CAS.

The Cirrus Bridge addresses common Identity Provider limitations such as:

    • Only supporting bilateral registration of SAML Service Providers
    • Not supporting specification of your own entityID in a domain that you control so that domain validation can be performed
    • Not supporting the CAS single sign-on protocol for authentication
    • Not supporting assertion of attributes as required by service provider(s) - specifically eduPerson attributes

The Bridge can also be used by an organization architecturally to address several federated identity use cases:

    • Participation in a trust federation such as InCommon or one of the other eduGAIN participating federations without needing to run a dedicated Identity Provider such as Shibboleth, SimpleSAMLphp, or SATOSA to support that participation. For example, smaller organizations may have a requirement to participate in a federation, but cannot dedicate resources to bridge between an existing Azure Active Directory environment and the federation.
    • Supporting a “Cloud First” strategy while still maintaining existing multilateral capabilities. Many organizations are migrating to commercial solutions. The Cirrus Bridge allows those organizations to maintain the capability they need to continue to participate in federations such as InCommon, one of the eduGAIN participating federations, regional, or industry specific federations.
      • Supporting CAS while still migrating to a commercial solution. The CAS protocol has been widely adopted by higher education and many large Higher Ed applications offer it as the only method for SSO integration. The Cirrus Bridge allows organizations to migrate to another solution while maintaining support for CAS. Likewise, there are instances were an application can act as a CAS Identity Provider -- The Cirrus Bridge can be used to present those identities to a SAML based federation.

 

The Bridge is also part of the Cirrus family of solutions and is fully integrated with:

    • Cirrus Discovery to enable the easy configuration of a user interface to select the identity provider for log in
    • Cirrus Gateway to enable both social login and organization IdP authentication to service providers
    • Cirrus Account Linking to enable linking organizational data to external identities asserted by either social login or federation identity providers
    • Cirrus Invitation to enable coarse grained authorization control to services based on sponsors associated with the institution
    • Cirrus External Identity Provider to enable organizations to offer a separate guest account with associated password that reflects the organization’s brand but as a SaaS solution
Like the Cirrus Proxy, The Bridge has at its foundation the well tested and widely adopted SimpleSAMLphp (SSP) open source project. Cirrus Identity is both an active participant, and contributor to the SSP community. We believe basing our solution on SSP allows us to both actively participate in the global academic identity management community, and focus on delivering effective solutions to our customers.
 

Planning Steps

The Cirrus Bridge solutions sit between your organization’s commercial identity management (IdM) solution (Azure AD, Okta, OneLogin, Google GSuite, or others) and the applications users need to access. A bit of planning before getting started will go a long way to reducing initial confusion. Consider the following questions:

 

1) Is your identity management (IdM) solution supported by the Cirrus Bridge? Cirrus Identity currently supports the following IdM solutions, and will consider supporting any other identity providers that support a bilateral SAML V2 or CAS connection (Cirrus professional services may apply):
  • Azure Active Directory
  • Okta
  • Google GSuite
  • Slate
  • Other authentication sources such as On-prem Active Directory, OneLogin, LDAP enabled directories, or RDMS based identity stores (Professional Services May Apply)
2) What are the Service Providers (SPs) that will be accessed using the Bridge?
  • What is the approximate number?
  • Are the SPs registered with InCommon or one of the other eduGAIN federations? -- If not, you will need to share the metadata with Cirrus Identity (we support a variety of options to accomplish this)?
  • Do these SPs all have the same attribute requirements?
  • Do any of the SPs have unique requirements? For example, do any of them us SAML v1 style inline scopes or expect assertions from an IdP with a SAML cert/key that is unique.
3) What capabilities of your IdM solution do you want to extend with the Bridge?
  • How will attributes be mapped across the Bridge?
  • Is affiliation or entitlement (for example eduPersonAffiliation or eduPersonEntitlement) being used for access control?
  • Will a multi-factor authentication (MFA) solution be integrated?

4) Will the Bridge be registered with InCommon or one of the other eduGAIN federations?

  • Will this be a new registration or will the Bridge take the place of an existing federated IdP?

5) Will the Bridge also function as a CAS identity provider?

  • What should ‘cas:user’ be set to?
  • What other attributes should be released with the CAS ticket?
  • What are the CAS service URLs?
  • Do any of the CAS services use proxy mode?
  • Do any of the CAS services rely on a static IP address -- said another way, are there firewall or other network policies that need to be considered?
Next you will want to look at Cirrus Bridge | Getting Started.
 

Getting Started

Unlike many of Cirrus Identity modules, the Cirrus Bridge is usually not provisioned before having a kickoff call, or at least a few email exchanges with customers. In most cases, Cirrus will need organizational information and to confer with you about integration decisions before the Bridge is set up. This does not imply the Bridge has more complexity -- quite the contrary. The Cirrus Bridge is often one of the quickest modules to deploy.
 
The following are the steps needed to get started using Cirrus Bridge:

1) Customers should plan out their Bridge deployment. Cirrus Identity can offer generally accepted practices, customer stories, and professional services to help. Reviewing the questions covered by the Cirrus Bridge | Planning Steps is a good first step:
  • Is the organization’s identity management (IdM) solution supported by the Cirrus Bridge?
  • What are the Service Providers (SPs) that will be accessed using the Bridge?
  • What capabilities of your IdM solution do you want to extend with the bridge?
  • Will the Bridge be registered with InCommon or one of the other eduGAIN federations?
  • Will the Bridge also function as a CAS identity provider?
2) If the Bridge will be registered in InCommon (or another trust federation), does your organization already have an IdP registered with InCommon or another trust federation?
  • If your organization doesn’t have a current registration, has your organization performed the needed administrative procedures to join the federation and has a site administrator been assigned?
  • If your organization does have a current registration, Cirrus Identity offers an add-on service that allows you to transition the existing federation registration to the Bridge. You will maintain your existing entityID and signing certificate in the process. A new TLS certificate will be requested. During setup, Cirrus will work with the organization to securely transfer the cryptographic material during setup of the Bridge.
3) If the Bridge will need to support Service Providers other than those in InCommon or one of the other eduGAIN federations, Cirrus Identity will need the metadata for those SPs.
  • Generally we ask organizations to provide the SP metadata in a local metadata aggregate that we can consume.
  • If organizations cannot provide an aggregate or there are only a handful of SPs, the metadata can be sent to the Cirrus Support Center.
4) If the Bridge is a migration from an existing IdP (for example Shibboleth or SimpleSAMLphp), the organization will need to provide certain configuration files to Cirrus Identity to support configuration of the Bridge. The files needed will depend on several factors related to the deployment and will be discussed during the initial kickoff call or email exchange.
  • If there are any SPs that require different SAML certs/keys, are looking for a different IdP entityId, or are looking for SAML V1 style inline scopes, we will configure the integration to accommodate those requirements.
5) Fairly early in the process, Cirrus Identity will ask the customer to create the needed integration in the organization’s identity management (IdM) solution. For example, both Azure Active Directory and Okta require the organization to create an “application” for the integration. Cirrus Identity will provide vendor specific instructions for the integration. See “Cirrus Bridge Setup in Authentication Source” for examples of this setup.
 
6) By default, the Cirrus Bridge is configured to comply with REFEDS Research and Scholarship basic attribute release. If a customer provides an attribute to map to eduPersonAffiliation, we will also include that. We work with customers to configure any additional SAML attribute mapping and release policies as needed and count against the caps defined by the Bridge subscription.
  • Attribute setup will also factor in older style attribute naming requirements specific to SPs.
7) If the organization is using a multi-factor authentication (MFA) solution, the Bridge can be configured to assert the AuthnContextClassRef as defined by REFEDS MFA standard. Depending on the organization’s IdM solution, some attribute configuration may be required.
 
8) If the Bridge is to support CAS services, we will set up an additional “CAS Bridge” for your environment (we offer this at a discounted price for campuses already using our SAML Bridge). You will need to define the “cas:user” value for services, and then send Cirrus Identity authorized service URLs.
  • Because the CAS protocol requires a back channel connection, Cirrus Identity will recommend an additional endpoint for the CAS services. This allows any critical services to be tested ahead of a production deployment.
  • If there are additional attributes to be included with the CAS response ticket, those will need to be mapped.
  • If the Bridge is taking over for an existing CAS installation, the existing configuration will need to be assessed much like the SAML IdP one outlined in Step 4.
9) Cirrus Identity will work with the organization to put together a testing plan before deployment. This will vary based on the migration needs, number of active service providers, and complexity of existing integrations.
 
10) If this Bridge deployment will be a new InCommon (or other federation registration), Cirrus Identity will provide the information and instructions needed for the customer to register their Bridge instance with the federation operator.
 
Once these steps are complete, you are ready to use Proxy with your service provider.
 

Using Cirrus Bridge

Overview

Because of how it works, the Cirrus Bridge is implemented between an Organization’s authentication source and SAML or CAS enabled Service Providers. The most common authentication sources are Azure Active Directory and Okta, but any of the following may be used:
  • Azure Active Directory (Licensed at the Free, Basic, Office365, or Premium P1/P2 levels)
  • Okta
  • Google GSuite
  • Slate
  • Other options we can support include: On-prem Active Directory, OneLogin, LDAP, RDMS (Cirrus professional services may apply)

Cirrus Bridge Setup in Authentication Source

To integrate the Cirrus Bridge with an authentication source, Cirrus Identity will provider customers will instructions depending on the authentication source (See Cirrus Bridge getting started for more details). At a high level, each side will need to exchange some information:
 
The Cirrus Bridge
The Authentication Source will need a handful of parameters from the Organization’s Bridge instance:
  • EntityID — https://<>/bridge
  • Reply URL — https://<>.proxy.cirrusidentity.com/module.php/saml/sp/saml2-acs.php/<>_proxy
There will also be a testing URL that can be used to test the connectivity between the authentication source and the Bridge:
  • Test URL — https://<>.proxy.cirrusidentity.com/module.php/core/authenticate.php?as=<>_proxy
The Cirrus Bridge will need metadata from the Authentication Source (see the next section).
 
The Authentication Source
As indicated above, Cirrus Identity will provide detailed instructions based on the Authentication Source. In most cases, the integration will involve defining some type of “application” or “service provider” in the Authentication Source. Examples of this for Azure AD and Okta are as follows:
 
Azure Active Directory Free / Basic / Office365
Azure Active Directory Premium P1/P2

 

Okta

 

To provide the metadata, each Authentication Source will have a slightly different procedure. The details will be covered in the instructions provided by Cirrus Identity. Examples of the metadata access for Azure AD and Okta are as follows:
 
Azure Active Directory Free / Basic / Office365
Azure Active Directory Premium P1 / P2
Okta

 

Cirrus Bridge and Federations

One of the primary uses of the Cirrus Bridge is to enable an Organization’s main authentication source to be registered in a multilateral trust federation such as InCommon or one of the other eduGAIN federations. Cirrus Identity supports both migrating a previously registered Identity Provider or registering your Bridge as a new federation IdP (see Cirrus Identity planning steps for more details).
 
If you will be registering as a new IdP, Cirrus Identity will provide you with some additional information so you have what you need to do the registration. For example, if you will be registering with InCommon, we will provide you with:
  • The IdP entityID
  • Attribute scope (this will generally be your organization’s domain)
  • Single Sign-On Service URL
  • Certificate
For InCommon registration, you will also need the following:
  • A logo URL
  • Contact information for an administrative, technical, and security contact
  • A privacy policy URL
You can access the InCommon Federation Manager from the main InCommon website.

 

Cirrus Bridge and Service Providers

By default, the Cirrus Bridge will be configured to release the REFEDS Research and Scholarship attribute bundle to any service provider properly marked in eduGAIN metadata (including InCommon metadata). If this is not the desired behavior for your Bridge and/or you need other attributes released, additional attribute policies can be configured by contacting Cirrus Support. If you need to have your Bridge access Service Providers that are local to your organization, or are not registered with InCommon or an eduGAIN federation, custom metadata can be configured by contacting Cirrus Support. See Cirrus Bridge getting started for an overview of this process.
 
© Copyright Cirrus Identity, Inc.
View full post