Understanding SAML based SSO for CompliSpace Products

The following process explains how a user logs into the CompliSpace Products application through an organisation’s, SAML based SSO service. Figure 1, shown below, illustrates the process by which a user logs in to the CompliSpace PolicyPlus application through a SAML based SSO service. The numbered list that follows the image explains each step in more detail.

Figure 1: Logging in to CompliSpace PolicyPlus using SAML -

(click on image to enlarge)

This image illustrates the following steps:

1. The user attempts to reach the CompliSpace PolicyPlus application.
2. CompliSpace generates a SAML authentication request. The SAML request is encoded and embedded into the URL for the organisation’s SSO service. The RelayState parameter containing the encoded URL of the CompliSpace PolicyPlus site that the user is trying to reach is also embedded in the SSO URL. This RelayState parameter is meant to be an opaque identifier that is passed back without any modification or inspection.
3. CompliSpace sends a redirect to the user’s browser. The redirect URL includes the encoded SAML authentication request that should be submitted to the organisation’s SSO service.
4. The organisation decodes the SAML request and extracts the URL for both CompliSpace’s ACS (Assertion Consumer Service) and the user’s destination URL (RelayState parameter). The organisation then authenticates the user. Organisations could authenticate users by either asking for valid login credentials or by checking for valid session cookies.
5. The organisation generates a SAML response that contains the authenticated user’s username and other details. In accordance with the SAML 2.0 specification, this response is digitally signed with the organisations’s public and private DSA/RSA keys.
6. The organisation encodes the SAML response and the RelayState parameter and returns that information to the user’s browser. The organisation provides a mechanism so that the browser can forward that information to CompliSpace’s ACS. For example, the organisation could embed the SAML response and destination URL in a form and provide a button that the user can click to submit the form to CompliSpace. The organisation could also include JavaScript on the page that automatically submits the form to CompliSpace.
7. CompliSpace’s ACS verifies the SAML response using the organisation’s public key. If the response is successfully verified, ACS redirects the user to the destination URL.
8. The user has been redirected to the destination URL and is logged in to CompliSpace PolicyPlus.
   
   

Configuring Your IdP

 CompliSpace supports this single sign-on experience as the integration of a cloud service with an already installed and operational SAML 2.0 compliant Identity Provider. Your SAML 2.0 Identity Provider is a third-party product and therefore CompliSpace does not provide support for the deployment, configuration, troubleshooting, best practices, etc. issues and questions regarding your SAML 2.0 Identity Provider

Please contact your SAML 2.0 IdP vendor for installation and configuration support.

SP Federation Metadata

Your IdP will require the PolicyPlus SP metadata. CompliSpace will provide this to you during the integration process.

Required Assertions

Your IdP must be able to provide certain assertions that allow your PolicyPlus site to work. The following table shows the required attributes along with attribute keys we accept and map.

Working With Microsoft ADFS

Microsoft ADFS claims to be a SAML 2.0 compliant IdP, however it is a Microsoft solution for Microsoft products. It does not support the full SAML 2.0 specification, and does not support transient name identifiers.

When you import the PolicyPlus SP metadata into ADFS it will give you a warning that it skipped some of the metadata because it was unable to understand everything in the XML.

You can safely ignore this warning, we have a way to force ADFS to play nicer.

To make ADFS use transient identification you will need to setup some manual claim rules. You can find these rules as a GitHub gist, Microsoft ADFS Claim Rules For Connecting To CompliSpace PolicyPlus via SAML

c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", Issuer == "AD AUTHORITY"]
=> issue(store = "Active Directory", types = ("http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn"), query = ";userPrincipalName;{0}", param = c.Value);

c:[Type == "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn"]
=> issue(Type = "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier", Issuer = c.Issuer, OriginalIssuer = c.OriginalIssuer, Value = c.Value, ValueType = c.ValueType, Properties["http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/format"] = "urn:oasis:names:tc:SAML:2.0:nameid-format:transient");

c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", Issuer == "AD AUTHORITY"] 
=> issue(store = "Active Directory", types = ("givenName", "sn", "mail", "objectGUID", "memberOf"), query = ";givenName,sn,mail,ObjectSID,memberOf;{0}", param = c.Value);

Configuring Your Users Access to PolicyPlus

SAML is a protocol and agnostic about your backend user directory. It could be a flat file, an SQL or NO-SQL database and LDAP server or even Microsoft Active Directory.

In order to allow your users access to PolicyPlus, their permissions must be in the assertion using the memberOf attribute.

PolicyPlus Sections & Sitecode Example:

Need More Help?