Cirrus Identity Provider Proxy Documentation

Table of Contents

1. Overview

2. Planning Steps

3. Getting Started

4. Using Cirrus Identity Provider Proxy

5. Configuration Resources: SAML Resources

6. Configuration Resources: Shibboleth Resources

Overview

One of our biggest goals at Cirrus Identity is to enable cross-organizational collaboration. Multilateral identity federation is a powerful tool to achieve this goal, but many vendor products don’t fully support the technologies for multilateral federation. Additionally, use cases such as protocol translation or account linking often require a proxy component.

The Cirrus Identity Provider Proxy is a solution that addresses Service Provider limitations such as:

• Only supporting one SAML identity provider

• Only supporting CAS for authentication but not SAML

• Not supporting the SAML discovery protocol

• Not supporting metadata from InCommon or one of the other eduGAIN participating federations

• Not supporting the attributes as asserted by identity provider(s)

• Not being able to require multi-factor authentication (MFA) because it is not supported by some or all identity providers

The Proxy can also be used by an organization architecturally to act as a single access point for audiences to access a group of Service Providers. Examples are:

• Applicants often need access to a subset of an organization’s services before they are fully admitted. For example, services to check application status, apply for scholarships, and pay fees can be deployed behind a Proxy for a uniform access experience.

• Alumni also need access to services such as transcript requesting, engagement platforms, career services. A centralized Proxy can streamline access to these services and improve engagement. The uniform and consistent experience for the end user is especially desirable for this audience.

infographic-identity-provider.png

The Proxy 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 liking 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

Cirrus Identity doesn’t believe in re-inventing the wheel. The Proxy has at its foundation the well tested and widely adopted SimpleSAMLphp open source project (SSP). 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

Proxy solutions like the Cirrus Identity Provider Proxy sit in the middle of things. A bit of planning before getting started will go a long way to reducing initial confusion. Consider the following questions:

1. Who is the target audience?

• What IdP(s) will the audience use?

• Does the audience vary based on the Service Provider being accessed?

2. What is/are the Service Providers that will be accessed?

• Do the Service Providers meet Cirrus Identity Provider Proxy requirements (support either SAML v2 or CAS)?

• Are the Service Providers registered with InCommon or one of the other eduGAIN federations? -- If not, you will need to share the metadata with Cirrus Identity (there are a few options for accomplishing this)?

• Do the Service Providers have an authorization process to control access that is separate from authenticating to the service?

3. Will the Proxy be required to provide access control?

• Does the Proxy need to ensure audience members have a sponsor using the Cirrus Invitation Service?

• Does the Proxy need to ensure audience members have an organizational attribute using the Cirrus Account Linking Service?

4. How will the end user “discover” which Identity Provider to use with the Proxy -- which is another way of saying what discovery configuration will the Proxy have?

• By default, the Proxy is configured to use the Cirrus Discovery Service and is the quickest to start. Both the Cirrus Proxy and the Cirrus Discovery Service are integrated with InCommon and eduGAIN metadata, and we can add your custom metadata to further lower the initial configuration effort.

• If the audience is being directed from another application such as a portal (and the service provider is reasonably well-behaved), discovery can be bypassed with a carefully constructing a URL. The URL can be used for links in portals or other web content to direct the audience to the service. See “Discovery Configuration with Cirrus Proxy | Bypass Proxy Discovery” for more details.

• The Proxy can also be configured to use any discovery service that is compatible with the OASIS IdP Discovery Service Protocol and Profile if an organization desires. See “Discovery Configuration with Cirrus Proxy | Configure my own Discovery Service for Proxy” for more details.

Next you will want to look at Cirrus Identity Provider Proxy | Getting Started.

Getting Started

Customers subscribing to Cirrus Identity Provider Proxy will have a UAT Proxy instance provisioned during customer on-boarding. Cirrus staff will also perform some initial configuration and, if appropriate, register the instance as an SP in the InCommon trust federation.

Customers will often subscribe to one or more additional Cirrus Identity modules to support desired implementations. In addition to provisioning the Proxy instance, we’ll also work with you to conduct some initial setup for Cirrus Gateway, Cirrus Account Linking, and/or Cirrus Invitation.

The following steps are needed to get started using Cirrus Identity Provider Proxy:

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

• Who is the target audience?

• What is/are the Service Providers that will be accessed?

• Do the Service Providers have an authorization process to control access that is separate from authenticating to the service?

• How will the end user “discover” which Identity Provider to use with the Proxy -- which is another way of saying what discovery configuration will the Proxy have?

2. As mentioned above, Cirrus Identity generally registers the SP side of the Proxy with the InCommon trust federation as part of the provisioning process. This allows identity providers to access metadata. Identity Providers will need to adjust attribute release to the Proxy for any attributes needed.

3. 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 External Identity Provider, and Cirrus Invitation each have associated setup. See the “Getting Started” for each module as appropriate:

4. If the Customer has subscribed to the Cirrus Account Linking solution, the customer will need to coordinate with Cirrus Identity on the details of the linking identifier to be used. Cirrus Identity will need these details to finish the configuration of the Proxy (See Cirrus Account Linking Getting Started).

5. If there is a Service Provider (SP) that will use the Proxy, but the metadata for the SP 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 (we support more automated metadata integration methods as well). Additionally, if there is an SP with special attribute requirements, regardless where the metadata is published, that also needs to be communicated to Cirrus Identity Support.

6. If there is an Identity Provider that is needed by the Proxy 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.

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

8. If the customer will be using the Cirrus Discovery Service (recommended at the start), an admin will configure the Cirrus Discovery Service for the Service Provider side of the Proxy using the Cirrus Console. The Discovery Service will be the interface users are redirected to when they attempt to log in to the Service Provider. Customers will configure all of the Identity Providers from which a user may choose (See Cirrus Discovery Getting Started).

9. Change the configuration for all Service Providers (SP) that will use the Proxy to trust the Identity Provider (IdP) side of the Proxy. Cirrus Identity will provide the path to the IdP metadata but it will generally be at a URL of the form https://NAME.proxy.cirrusidentity.com/saml2/idp/metadata.php (See Cirrus Proxy Documentation for further details).

10. If the customer configured the Cirrus Discovery Service (see Step #8), change the configuration for all SPs that will use the Proxy to use the Cirrus Discovery Service - the discovery URL is "https://apps.cirrusidentity.com/console/ds/index" and details for different Service Provider platforms are available here).

Once these steps are complete, you are ready to use Proxy with your service provider.

Using Cirrus Identity Provider Proxy

Cirrus Identity Provider Proxy discovery configuration

Standard configuration

In most scenarios your Service Provider (SP) will send users to the Cirrus Proxy to authenticate. The Cirrus Proxy will show a discovery interface to users. The user will select an identity provider (IdP) and the Proxy will send the user to that IdP to authenticate.

If authentication is successful, the IdP will send the end user back to the Proxy, the Proxy will perform any configured business logic, and send the end user back to the SP.

Customers configure the Cirrus Discovery Service user interface and the list of Identity Providers from which a user can choose in the Cirrus Console.

For a Shibboleth Service Provider deployment, see the “Shibboleth Resources | Using a Shibboleth service provider with Cirrus Proxy” example configuration.

Bypass Proxy discovery

In some situations your SP may already know the upstream IdP that the proxy should use and you want the user to bypass the discovery normally performed by the proxy. This can be achieved by sending a carefully constructed request to the proxy that contains the following information:

1. The SP Entity ID

2. Relay State for the SP. This is often the path on the SP that the user should end up on after authenticating

3. The upstream IdP EntityID

URL encode these parameters and use them as query parameters to the SingleSignOnService HTTP-Redirect binding URL for the proxy. You'll have a URL of the format $bindingUrl?spentityid=$SPEntityID&RelayState=$RelayState&IDPList=$IdpEntityID

Sending a user to the below example will tell a Cirrus proxy to use Google as the upstream IdP and return the user to a Cirrus test SP that will display some attributes.

https://support.proxy.cirrusidentity.com/saml2/idp/SSOService.php?spentityid=https%3A%2F%2Fstandard.monitor.cirrusidentity.com&RelayState=%2Fmodule.php%2Fcore%2Fauthenticate.php%3Fas%3Dmonitor-standard&IDPList=https%3A%2F%2Fgoogle.cirrusidentity.com%2Fgateway

Perform discovery before AuthNRequest

In the standard flow the SP sends the user/browser to the proxy first (using a SAML AuthNRequest) and then discovery is performed. In some case you may want to perform discovery first and send the user to the proxy second AND bypass discovery on the proxy. This can be achieved by constructing two URLs with the necessary parameters: The discovery return URL and discovery URL

Discovery return URL

The discovery return URL is similar to the 'Bypass Proxy Discovery' URL. It initiates the login after discovery has been performed. It will get used when constructing the discovery URL. You'll need the following information:

1. The SP Entity ID

2. Relay State for the SP. This is often the path on the SP that the user should end up on after authenticating.

URL encode these parameters and use them as query parameters to the SingleSignOnService HTTP-Redirect binding URL for the proxy. You'll have a URL of the format $bindingUrl?spentityid=$SPEntityID&RelayState=$RelayState  

Example: https://support.proxy.cirrusidentity.com/saml2/idp/SSOService.php?spentityid=https%3A%2F%2Fstandard.monitor.cirrusidentity.com&RelayState=%2Fmodule.php%2Fcore%2Fauthenticate.php%3Fas%3Dmonitor-standard

Discovery URL

The discovery URL will load Cirrus's Discovery interface. Users can be sent here to pick an IdP and initiate a login. You'll need to know the following information:

1. The Proxy's SP entityId

2. The return URL from above

URL encode these parameters and use them as query parameters to the discovery URL. You'll have a URL of the form "https://apps.cirrusidentity.com/console/ds/index?returnIDParam=IDPList&entityID=$proxySpEntityId&return=$returnUrlEncoded"

Sending a user (or iframing) this example discovery URL will allow you to initiate discovery from your SP and have the response processed by the Proxy.  https://apps.cirrusidentity.com/console/ds/index?returnIDParam=IDPList&entityID=https%3A%2F%2Fsupport.proxy.cirrusidentity.com%2Fsp&return=https%3A%2F%2Fsupport.proxy.cirrusidentity.com%2Fsaml2%2Fidp%2FSSOService.php%3Fspentityid%3Dhttps%253A%252F%252Fstandard.monitor.cirrusidentity.com%26RelayState%3D%252Fmodule.php%252Fcore%252Fauthenticate.php%253Fas%253Dmonitor-standard

Configure my own Discovery Service for Proxy

The Proxy uses the Cirrus Discovery Service to perform discovery. If you have a Discovery Service that is compatible with OASIS IdP Discovery Service Protocol and Profile and want to use that with the Cirrus Proxy then contact support@cirrusidentity.com to have this enabled for your proxy.

Standard Flow with Custom Discovery for SP

In the standard flow the proxy displays the same discovery interface for all SPs making use of the proxy. If you want to customize the discovery interface shown by the proxy based on the SP using the proxy then contact support@cirrusidentity.com to discuss your options.

Cirrus Identity Provider Proxy and assertion scoping

Scopes

In an identity federation each Identity Provider has certain scopes that it can use when asserting user attributes to avoid name collisions. For example if two Identity Providers had a user called John they would need a way to distinguish which john is from which IdP.  Using scoping, the IdPs could assert the identifier as john@orgA.com and john@orgB.com, where orgA and orgB are the domain names for the organizations associated with each IdP.

The Cirrus SAML Proxy supports scopes in several fashions

Exact Scope Checking

The proxy will check that the scope asserted from an Identity Provider matches the allowed scope for the Identity Provider. If an IdP asserts a scope that it is not allowed to the proxy will remove that assertion.

This is enabled by default for these attributes: eduPersonPrincipalName, eduPersonScopedAffilitation

Ends with Scope Checking

In some scenarios a Service Provider uses email address as its internal identifier. The proxy can perform scope checking on the email address. In some organizations user's email addresses may contain subdomains. For example Example Edu may have a scope of example.edu but email address domains like org.example.edu. If it enabled this feature performs scope checking by ensuring the scope domain ends with the appropriate domain.

Ignore Scope Checking

If you intend to proxy an Identity Provider that does not have a fixed scope you may opt to disable scope checking for that Identity Provider. For example Google provides email for lots of enterprises. If you use the Cirrus Gateway as an IdP AND use email address for eduPersonPrincipalName then the Google gateway may assert a scope for any business that uses Google for email. In such a scenario you'll want to disable scope checking for a specific IdP, and continue checking other IdPs.

This is enabled by default for Cirrus Gateway IdPs that provide email service for multiple domains.

Scope Rewrite

Your use case may require you to re-write the scope of proxied attributes. This feature will have proxy change scoped attributes in one of two ways:

• Change scope: A scoped value of student@example.edu will be changed to student@newscope.com. This is useful if your SAML profile has specified the allowable values for the de-scoped attribute.

• Change scope and de-scoped value: A scoped value of user@example.edu will be changed to user+example.edu@newscope.com. This is useful when you want to preserve the old scope in some fashion during the rewrite.

The new scope is configurable. This feature is disabled by default. If enabled it can be applied to specific attributes, or to specific scopes or to a combination of the two.             

Configuration Resources: SAML Resources

Customer Metadata

Cirrus will generate customer specific SAML Metadata for certain services. 

Metadata

Cirrus will publish your metadata bundle at a URL of the form "https://md.cirrusidentity.com/metadata/_NAME_/cirrus-metadata-signed.xml" where _NAME_ is a customer specific identifier. Cirrus will provide the value to use for _NAME_

The metadata bundle can contains an EntitiesDescriptor element with multiple EntityDescriptor child elements. Not all SAML software can consume a bundle of metadata. If you need individual files, please contact Cirrus support.

For an example Shibboleth SP configuration to automatically consume the metadata bundle, see “Enabling Shibboleth service provider to consume Cirrus Proxy metadata”.

Signature Verification

Customer metadata is signed by Cirrus. If your SAML software supports signature verification, then you can use the public key to verify the download.

# Retrieve the certificate
$ /usr/bin/curl --silent \
https://md.cirrusidentity.com/metadata/metadata-signing.crt \
> /tmp/metadata-signing.crt
# Validate the certificates fingerprint
$ openssl x509 -noout -in /tmp/metadata-signing.crt  -fingerprint -sha1

    SHA1 Fingerprint=56:C4:D7:77:8D:9F:C8:03:40:E4:B4:9F:77:67:57:A1:F4:52:91:1D
             

Configuration Resources: Shibboleth Resources

Sample Shibboleth configurations

Enabling Shibboleth Service Provider to consume Cirrus Proxy metadata

To enable a Shibboleth service provider to access the Cirrus Proxy metadata, add an additional MetadataProvider to your shibboleth2.xml configuration file as follows:

<!-- Non-social IdP's managed by Cirrus -->
<!-- Replace _NAME_ with the organization name provided by Cirrus, and _YOUR_PATH_ with the path to the Cirrus metadata-signing public key -->
<MetadataProvider type="XML" url="https://md.cirrusidentity.com/metadata/_NAME_/cirrus-metadata-signed.xml"
backingFilePath="cirrus-metadata-signed.xml" reloadInterval="14400">
            <MetadataFilter type="Signature" certificate="/_YOUR_PATH_/metadata-signing.crt"/>
</MetadataProvider>

Using a Shibboleth Service Provider with Cirrus Gateway and Cirrus Discovery

If you are using your SP directly with the Cirrus Gateway and not through a proxy, then you may use Cirrus's Discovery Service with your SP

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

Using a Shibboleth Service Provider with Cirrus Proxy

If you are using the Cirrus Identity Provider Proxy then you configure the SP to direct all logins to the Proxy.

<SSO entityID="https://TENANT.proxy.cirrusidentity.com/idp">            
    SAML2 SAML1 
</SSO>

Scope Checking

Shibboleth SP performs scope checking for eduPersonPrincipalName and other scoped attributes. If you are using a Cirrus Proxy then scope checking is performed by the Proxy and the Proxy will pass through scoped attributes from the upstream IdP. If your Shibboleth SP also performs scope checking it may remove these scoped attributes that were asserted from the upstream IdP. You can adjust your shibboleth attribute-policy.xml configuration as shown below.

<afp:AttributeRule attributeID="eppn">
    <!-- Disabling default scope check because proxy may assert eppns from multiple upstream IdPs -->
    <!-- <afp:PermitValueRuleReference ref="ScopingRules"/> -->
    <afp:PermitValueRule xsi:type="ANY"/>
</afp:AttributeRule>

© Copyright Cirrus Identity, Inc.

Blog comments