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 to enlarge)
This image illustrates the following steps:
- The user attempts to reach the CompliSpace PolicyPlus application.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- The user has been redirected to the destination URL and is logged in to CompliSpace PolicyPlus.
Required Assertions
CompliSpace PolicyPlus requires several claims/assertions that your SAML IdP must provide in order to work correctly. These can be provided using either the short name
, url scheme
or urn oid
The claims in the short name
format include:
givenName
- The first name of the usersn
- The surname of the usermail
- The email address used by the userobjectGUID
- A unique identifer for the user that is persistent even if the user changes name or email addressmemberOf
- The list of groups the user belongs in the Distinguished Name (DN) format or as a simple string.
The full list of claim maps in all formats:
Short Name | URL Schema | OID | Purpose |
---|---|---|---|
givenName | http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname | urn:oid:2.5.4.42 | Display and record keeping |
sn | http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname | urn:oid:2.5.4.4 | Display and record keeping |
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress | urn:oid:0.9.2342.19200300.100.1.3 | Notifications | |
objectGUID | ? | urn:oid:1.2.840.113556.1.4.2 | Identifier for the user. This must NEVER change, even if the user changes name and email address |
memberOf | http://schemas.xmlsoap.org/claims/Group | urn:oid:1.2.840.113556.1.2.102 | Provides access to PolicyPlus secure sections. |
Working with Permissions and Groups
CompliSpace PolicyPlus has a rather thorough permissions system, but has been simplified for integration with SSO. First, if you want a user to have any kind of access to PolicyPlus they must belong to a group called Fundamentals
. This allows you to temporarily remove access to a user without having to remove and re-add all the detailed permissions.
PolicyPlus partitions content into sections such as Public (available to all staff), HR Admin (only available for your Human Resources staff), etc. Please contact your CompliSpace Consultant Team for details on sections available to your installation. A user with access to a section may have read only (RO) or read/write (RW) access.
Section access is granted by ensuring the user belongs to a group that is made by taking the section name
and appending either RO
or RW
as required for the access they require.
For example, if you wish for a user to have read only access to the Public section then they must belong to a group called Public RO
. Should the user require read/write access then they must belong to a group called Public RW
.
All characters in a group must match exactly. For example, the section called Human Resources (Admin Only)
can be granted read only access to a user by assigning them to a group called Human Resources (Admin Only) RO
Group Format
The format for the group name can be either a simple string or in the Distinguished Name (DN) format.
With the DN format, only the CN RDN component is used.
Example: CN=Human Resource (Admin Only) RO,OU=Fundamentals,OU=CompliSpace,OU=Vendors,DC=complispace,DC=net
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.
Short Name | URL Schema | OID | Purpose |
---|---|---|---|
givenName | http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname | urn:oid:2.5.4.42 | Display and record keeping |
sn | http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname | urn:oid:2.5.4.4 | Display and record keeping |
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress | urn:oid:0.9.2342.19200300.100.1.3 | Notifications and linking to already exsiting accounts | |
objectGUID | urn:oid:1.2.840.113556.1.4.2 | Identifier for the user. This must NEVER change, even if the user changes name and email address | |
memberOf | http://schemas.xmlsoap.org/claims/Group | urn:oid:1.2.840.113556.1.2.102 | Provides access to PolicyPlus secure sections. See documentation How do groups work for details |
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
Code Block | ||
---|---|---|
| ||
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); |
Code Block | ||
---|---|---|
| ||
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"); |
Code Block | ||
---|---|---|
| ||
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.
The following table show the sections and hence groups supported by your PolicyPlus site:
PolicyPlus Section | Group/Permission Name | Access Type |
---|---|---|
Site Access | Fundamentals | This permission is required to allow any kind of access. Without this permission, no access will be granted whatsoever regardless of other permisions. |
Public | Public RO | Read Only to the Public section. |
Public | Public RW | Read and Write to the Public section. |
Tools Admin | Tools Admin RO | Read Only to the Tools Admin section. |
Tools Admin | Tools Admin RW | Read and Write to the Tools Admin section. |
Archived Pages | Archived Pages RO | Read Only to the Archived Pages section. |
Archived Pages | Archived Pages RW | Read and Write to the Archived Pages section. |
HR Administration (Managers Only) | HR Administration (Managers Only) RO | Read Only to the HR Administration (Managers Only) section. |
HR Administration (Managers Only) | HR Administration (Managers Only) RW | Read and Write to the HR Administration (Managers Only) section. |
PolicyPlus Sections & Sitecode Example:
Access | Group/Permission Name | Access Type |
---|---|---|
Site Access | Fundamentals | This permission is required to allow any kind of access. Without this permission, no access will be granted whatsoever regardless of other permisions. |
Public | Public RO | Read Only to the Public section. |
Public | Public RW | Read and Write to the Public section. |
Tools Admin | Tools Admin RO | Read Only to the Tools Admin section. |
Tools Admin | Tools Admin RW | Read and Write to the Tools Admin section. |
Archived Pages | Archived Pages RO | Read Only to the Archived Pages section. |
Archived Pages | Archived Pages RW | Read and Write to the Archived Pages section. |
HR Administration (Managers Only) | HR Administration (Managers Only) RO | Read Only to the HR Administration (Managers Only) section. |
HR Administration (Managers Only) | HR Administration (Managers Only) RW | Read and Write to the HR Administration (Managers Only) section. |
Warning |
---|
|
Need more help?
Contact your CompliSpace Consultant Team
CompliSpace Help Desk
Phone: | 1300 132 030 |
---|---|
Email: | helpdesk@complispace.com |
Other resources
CompliSpace TV
Contains video tutorials on the administrator functions of the PolicyPlus and Assurance systems.
Requires a login to access (can be requested from the Help Desk)