Single Sign On (SSO) with SAML 2 (Version 3)

Oct 7, 2018

Single Sign On (or SSO) is a fantastic option if you have the time and energy to implement it.  SSO allows your staff member to log in once and then access all your school based and web based applications without being prompted to login again.

Configuration

Firstly it is important to understand the configuration process for SSO.  There should be an IDP (provides the authentication of the staff member) and the SP (Service Provider) that is our Sobs website.

You should have some configuration information from your IDP ready to configure Sobs for your SSO to work.  There are at least 4 values required and then a number of optional values you can specify as required.

IMPORTANT: Also, before you go logging out to test the login process ensure you configure a non-SAML login.  This is step 9 below.

IMPORTANT: If you are configuring SAML with your own ADFS server, then download this PDF with instructions from our friends at Brigidine College – St Ives. Click to download

IMPORTANT: If you are configuring SAML with Office 365, then download this PDF with instructions from our friends at St Columba College. Click to download

IMPORTANT: The SAML interface relies on the URL https://sobs.com.au Do not use https://www.sobs.com.au

IMPORTANT: When using ADFS be sure to set SHA256

IMPORTANT: October 2018 we updated our SimpleSAMLphp library to the latest version.  There have been a number of changes / improvements with this update.  If you find something that doesn’t work quite how you expect please do get in touch – we will do our best to help.

IMPORTANT: We now have two methods of implementing a SAML connection.  1. SHARED SAML: If you are part of group of schools who are implementing a single SAML based authentication service then the SAML settings will be shared between you and several other schools.  We will need to talk to your IT department in regard to configuring this shared SAML setup, and allocate them an account from which they will be able to manage the shared SAML configuration.  2. SINGLE SCHOOL SAML: Your school has their own SAML based authentication service, it is not shared by any other schools, then the instructions below should be sufficient.  Do call if you would like to discuss this.

  1. Start by logging into Sobs and click on the school name at the bottom left of the screen
  2. Click the ‘School configuration’ entry
  3. Now click the ‘Authentication’ menu entry
  4. Your current authentication options are displayed, click the ‘Select’ button at the top of the page
  5. If you school has a single SAML authentication service not shared with other schools then select “SAML (Local)”.  If you are accessing a shared SAML service (for example, you are a catholic school and your IT department provides a SAML service to all of the catholic schools in your diocese)
  6. At this stage you are going to need to information from your iDP (your authentication service).  We tested this with miniOrange, a web-based SSO service, and when we added a SAML application a link to show the miniOrange “metadata” appeared.  Clicking this link we were given a list of URLs, most of which would be required within SOBS.
  7. Use the “Add” link to add SAML entries provided by your iDP
    1. The first entry you add will be your ‘BaseDomain’, this is normally the first URL provided.  In our miniOrange example it was called the “IdP Entity ID or Issuer”
    2. You will also add the SAML Login URL, the SAML Logout URL
    3. I copied the certificate content to a file and then uploaded this file to SOBS.  You could also use the ‘Download X.509 Certificate’ option and upload this to SOBS
    4. My miniOrange settings in SOBS looks like this
  8. You can use the ‘Generate metadata’ button to generate an XML document to supply back to your iDP.  The metadata will download as a file called “sobs-sp”, however it is an XML file, you may need to rename this file to “sobs-sp.xml” in order to upload it to your iDP.  And this assumes your iDP has an option for importing metadata via an XML file.    This completes the authentication circle (so the iDP will know this SOBS settings).  Here is an example of the metadata:
  9. The above is sufficient for authenticating the user, however we also want to update the authenticated users details in case they have changed, or if it is a new user. SAML calls the user attributes.  ADFS calls them ‘Claim rules’.  Essentially you are matching up some field names with values from the staff record.  Here is a list of the attributes that SOBS will use:
    1. User-Name : the authenticated login name
    2. Mail : the user’s email address
    3. Givenname : user’s first name
    4. Surname : user’s surname
    5. Shortname : an acronym or shortened name identifying this user
    6. Role : if role is one of these {faculty, staff, employee, teacher} then we will automatically set the user’s security to ‘Staff’. If role has any other value the authenticated user will be given a security of ‘Guest’I configured miniOrange to send these attributes:
  10. DO NOT logoff just yet!   If you were to logoff now and the settings were incorrect you and all staff will be immediately locked out of Sobs.
    1. Go to the ‘Staff’ list
    2. You might like to create a special ‘admin’ login (if you don’t already have one).  It should not be one of your network logins – it will be your back-door to SOBS administration in the event there are problems with SAML now or in the future (like when your certificate expires and needs to be replaced before you can login)
    3. On this ‘admin’ staff record you should be able to check a box called ‘non-SAML’
    4. It is probably worth writing down the username and password into a secure location.
    5. You should also record the URL to use this login (normally login requests will automatically redirect to the iDP authentication page)
      The URL will be: https://sobs.com.au/ui/login.php?schoolid=XXX&username=admin
      Replace “XXX” with your school id number (you can find this in the ‘School configuration’ page on the ‘Authentication’ menu entry)
      Replace “admin” with the username you are creating
    6. Even with SAML enabled this URL will take you to the normal SOBS login page where you can enter the password
  11. Finally you need a URL to login to Sobs (replace “XXX” with your Sobs school id)
    https://sobs.com.au/ui/login.php?schoolid=XXX
  12. There some other optional configurations:
    1. When a SAML session is completed and the user logs off, and that logoff happens from SOBS, you can configure a URL that the user will be redirected to.
      Go back to the SAML configuration entries (‘School configuration’ page and the ‘Authentication’ menu entry)
      Add another Key/Value pair to the SAML entries
      The key is “LogoffUrl”
      The value is the URL that the user will be redirected to at logoff