Chorus User Guide

Page tree

Please note that Third Light does not provide support for setting up products from other vendors and offer these instructions on an example basis only.

This guide is for how to integrate Shibboleth with Chorus using SAML2. If you're looking to integrate AD FS, then you should switch over to AD FS via SAML2. 

Shibboleth Installation

We recommend following the instructions in Shibboleth's IdP Install Documentation.

Chorus Configuration

Click Admin at the top of Chorus and sign in to elevate.

 2. Choose Settings > Site from the Admin menu. The Site Admin modal will open.
 3. Go to SAML2 settings.
 4. Use the Enable SAML2 switch to activate the functionality. Configuration options will appear.
 5. Select your method for loading IdP Metadata. This can be loaded directly from the IdP (URL), or manually supplied in XML.

Loading via a URL is preferred, as it can be kept up to date automatically. You can get the URL from your Shibboleth server.

The Metadata URL is normally the same as your Entity ID for Shibboleth IdP, e.g. "https://shibboleth.example.com/idp/shibboleth", where shibboleth.example.com is the host of your Shibboleth server.


Chorus will check the URL every 24 hours. If Chorus cannot access your AD FS server, Chorus will not automatically update the Metadata if you change your AD FS configuration. If you make any changes, then you may have to re-add the Metadata manually:

  • Select the "Load IdP Metadata from XML" radio option.
  • Paste the Metadata into the text field labelled "IdP Metadata XML" (see the info box at the top of this section).

 

 

6. Enter your IdP Metadata URL

7. If you are having problems configuring this URL, such as a message saying the XML is invalid, use the Test This URL button to see what data is being fetched by Chorus.

8. Use the Force Authentication switch to tell the IdP service to force users to re-authenticate when a sign in request is made.
9. View the SP Details to view the relying party details (SP Entity ID and SP Metadata URL). Note, you cannot edit these fields.
 

 

10. Click Save.

After saving, the SP Entity ID and SP Metadata URL will be visible for the SP (e.g. https://chorus.example.com/samlconsume.tlx/1382115659/module.php/saml/sp/metadata.php/samlauth). Keep note of this as you will need it to configure the Relying Party in Shibboleth, below.

Shibboleth Configuration

Due to the flexible nature of Shibboleth and plethora of different possible configurations, it is impossible to give a single sequence of configuration steps which will work in all situations. Therefore, we supply a Technical Summary of the required configuration, as well as a set of Sample Configuration Files.

Technical Summary

  • A Relying Party needs configuring based on the SP Entity ID and Metadata URL from Chorus (see above).
  • Attribute Resolver and Filter configuration to provide the following attributes for the Chorus Relying Party.
    • A Name ID of type urn:oasis:names:tc:SAML:2.0:nameid-format:persistent returning a consistent identifier for the user as this is used by Chorus to associate the accounts.

    • The following attributes:

      AttributeEncoder "name"
      Purpose in Chorus
      		Updates
      http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddressEmail addressUpdated at login
      http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameNameUpdated at login
      http://schemas.xmlsoap.org/claims/CommonNameUsernameUsed as a basis for initial account creation only
      http://schemas.xmlsoap.org/claims/GroupConnecting SAML2 groups to Chorus SpacesUpdated at login

      http://schemas.microsoft.com/ws/2008/06/identity/claims/role

      		DescriptionUpdated at login

Sample Configuration Files


conf/relying-party.xml


<!-- The following alongside your other <rp:RelyingParty/> entries inside the <rp:RelyingPartyGroup/>: -->
<rp:RelyingParty id="https://chorus.example.com/samlconsume.tlx/1382115659/module.php/saml/sp/metadata.php/samlauth"
                 provider="https://shibboleth.example.com/idp/shibboleth"
                 defaultSigningCredentialRef="IdPCredential"
                 defaultAuthenticationMethod="urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport" >
   <rp:ProfileConfiguration xsi:type="saml:SAML2SSOProfile"
                            encryptNameIds="never"
                            encryptAssertions="never"
                            />
</rp:RelyingParty>
  
<!-- The following inside the top-level <metadata:MetadataProvider id="ShibbolethMetadata" xsi:type="metadata:ChainingMetadataProvider"/>: -->
<metadata:MetadataProvider id="IMSMD" xsi:type="metadata:FileBackedHTTPMetadataProvider"
                           metadataURL="https://chorus.example.com/samlconsume.tlx/1382115659/module.php/saml/sp/metadata.php/samlauth"
                           backingFile="/opt/shibboleth-idp/metadata/ims.xml"
                           />
conf/attribute-resolver.xml


<!-- The following attribute definitions (note you may want to change which fields are mapped to): -->
<resolver:AttributeDefinition id="imsNameID" xsi:type="ad:Simple" sourceAttributeID="uid">
    <resolver:Dependency ref="myLDAP" />
    <resolver:AttributeEncoder xsi:type="enc:SAML2StringNameID" nameFormat="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent"/>
</resolver:AttributeDefinition>

<resolver:AttributeDefinition xsi:type="ad:Simple" id="imsCn" sourceAttributeID="uid">
    <resolver:Dependency ref="myLDAP" />
    <resolver:AttributeEncoder xsi:type="enc:SAML2String" name="http://schemas.xmlsoap.org/claims/CommonName" friendlyName="uid" />
</resolver:AttributeDefinition>
<resolver:AttributeDefinition xsi:type="ad:Simple" id="imsEmail" sourceAttributeID="mail">
    <resolver:Dependency ref="myLDAP" />
    <resolver:AttributeEncoder xsi:type="enc:SAML2String" name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" friendlyName="Email" />
</resolver:AttributeDefinition>
<resolver:AttributeDefinition xsi:type="ad:Simple" id="imsName" sourceAttributeID="cn">
    <resolver:Dependency ref="myLDAP" />
    <resolver:AttributeEncoder xsi:type="enc:SAML2String" name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name" friendlyName="Name" />
</resolver:AttributeDefinition>
<resolver:AttributeDefinition xsi:type="ad:Simple" id="imsGroups" sourceAttributeID="cn">
    <resolver:Dependency ref="ldapGroups" />
    <resolver:AttributeEncoder xsi:type="enc:SAML2String" name="http://schemas.xmlsoap.org/claims/Group" friendlyName="Group" />
</resolver:AttributeDefinition>
  
<!-- The following Data Connectors (note: you will need to change the connection details) -->
<resolver:DataConnector id="myLDAP" xsi:type="dc:LDAPDirectory"
                        ldapURL="ldap://ldap.example.com"
                        baseDN="dc=example,dc=local"
                        principal="cn=shibmanager,dc=example,dc=com"
                        principalCredential="myPassword">
    <dc:FilterTemplate>
        <![CDATA[
            (uid=$requestContext.principalName)
        ]]>
    </dc:FilterTemplate>
</resolver:DataConnector>
<resolver:DataConnector id="ldapGroups" xsi:type="dc:LDAPDirectory"
                        ldapURL="ldap://shibboleth.thirdlight.local"
                        baseDN="ou=Groups,dc=example,dc=com"
                        principal="cn=shibmanager,dc=example,dc=com"
                        principalCredential="myPassword"
                        maxResultSize="500"
                        mergeResults="true">
     <dc:FilterTemplate>
         <![CDATA[
             (&(objectclass=groupOfNames)(member=uid=$requestContext.principalName,dc=example,dc=com))
         ]]>
     </dc:FilterTemplate>
     <dc:ReturnAttributes>cn</dc:ReturnAttributes>
</resolver:DataConnector>
conf/attribute-filter.xml


 <!-- Note you will need to change "http://ims.example.com/saml/sp" to the Entity ID for your IMS SP -->
<afp:AttributeFilterPolicy>
    <afp:PolicyRequirementRule xsi:type="basic:AttributeRequesterString" value="http://chorus.example.com/saml/sp" />
    <afp:AttributeRule attributeID="imsNameID">
        <afp:PermitValueRule xsi:type="basic:ANY"/>
    </afp:AttributeRule>
    <afp:AttributeRule attributeID="imsCn">
        <afp:PermitValueRule xsi:type="basic:ANY" />
    </afp:AttributeRule>
    <afp:AttributeRule attributeID="imsEmail">
        <afp:PermitValueRule xsi:type="basic:ANY" />
    </afp:AttributeRule>
    <afp:AttributeRule attributeID="imsName">
        <afp:PermitValueRule xsi:type="basic:ANY" />
    </afp:AttributeRule>
    <afp:AttributeRule attributeID="imsGroups">
        <afp:PermitValueRule xsi:type="basic:ANY" />
    </afp:AttributeRule>
</afp:AttributeFilterPolicy>

Testing the Configuration

Chorus and Shibboleth should now both be configured for Single-Sign-On. To quickly test:

  1. Open up Chorus in your browser (e.g. http://chorus.example.com)
  2. If you're logged in, then logout. 
  3. Click the "Single Sign-on" button.
  4. You should automatically be authenticated via Shibboleth.


You are here: