Identity Provider Proxy | Getting Started

Identity Provider Proxy | Using Cirrus Identity Provider Proxy

Sample Shibboleth configurations

Using with Cirrus Proxy

If you are using Cirrus's SAML proxy then you configure the SP to direct all logins to the proxy.

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

Using with Cirrus Gateway and Cirrus Discovery

If you are using your SP directly with the 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>

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>

Discovery Configuration with Cirrus Proxy

Standard Configuration

In most scenarios your 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 IdP and the proxy will send the user to that IdP to authenticate.

The IdP will respond to the proxy, the proxy will perform any configured business logic and then respond to your SP.

The most common way to configure a Shibboleth SP with a proxy can be found here.

The discovery UI and IdPs shown by the Cirrus Proxy can be configured in the console.

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 for the format 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 you 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.

Customer Metadata

Cirrus will generate customer specific SAML Metadata for certain services. 


Metadata

Cirrus will publish your metadata bundle at 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.

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

Software Configuration

Shibboleth SP

Add an additional MetadataProvider to your shibboleth2.xml

<!-- 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>

Cirrus Identity Provider Proxy Features

Overview

The Cirrus SAML Proxy makes it easier to perform SAML integrations. It will help in scenarios such as:

  • Service Providers that only support a single Identity Provider and you want to support serveral

  • Identity Providers that do not support federation

  • Performing additional authentication and authorization checks.

Features

Multi Factor Authentication

A service provider may want to require multi factor authentication from identity providers in its federation but run into an issue where not all identity providers are able to require multi factor for their users or assert that the user authenticated with multi factor. The Cirrus SAML proxy can prompt users for a second factor to ensure that all users, regardless of identity provider, have performed multi factor authentication to reach the service provider.


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

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 your 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 descoped attribute.

  • Change scope and descoped 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 disable by default. If enabled it can be applied to specific attributes, or to specific scopes or to a combination of the two.