SAML/SSO

Setting up SAML authentication will allow you to achieve single sign on (SSO) for your users across the web. Your identity provider (iDP) will provide the authentication services for Schoolbox. Once your users are authenticated against the identity provider, they may proceed to Schoolbox and any other service providers that are registered.

The examples below use ADFS (Active Directory Federation Services) as the iDP, though the same process works well with many other iDP's such as SimpleSAML, StudentNet.

On this page, you will find the following information:

Identity Provider

Schoolbox SAML

Single Logout (SLO)

ADFS

Kerberos/WIA with SAML

Bypass SAML in Schoolbox

WebDav with SAML enabled

Google SAML

Azure SAML

NOTE: As the setup of SAML and SSO requires configuration to a specific URL, settings cannot be copied between your production and staging instance. It also means that each instance will require individual configuration if you wish to setup or test this method of logging in.

Important Steps

• Ensure ADFS is configured and HTTPS/SSL is enabled
• Ensure ADFS is available both internally and externally on the exact same URL
• Choose to either use the Identity Provider Metadata URL (if available) OR export the Token Signing Certificate manually.

Token Signing Certificate Export Steps (ADFS Example):

1. Browse to the certificates and export the Token-Signing certificate

2. Right-click the certificate and select 'View Certificate'.

3. Select the Details tab.

4. Click Copy to File -> The Certificate Export Wizard launches.

5. Select 'Next'.

6. Ensure No, do not export the private key is selected, and then click 'Next'. 

7. Select DER encoded binary X.509 (.cer), and then click 'Next'.

8. Select where you want to save the file and give it a name. Click 'Next'.

9. Select 'Finish'.

NOTE: Schoolbox requires that this certificate be in PEM format. You can convert this certificate using client tools or even online tools such as: SSL Shopper.

10. Use the DER/Binary certificate we just created and export it to Standard PEM format.

Important Steps

• Ensure Schoolbox is available both internally and externally on the exact same URL
• Configure the SAML Identity Provider information as below.

1. Navigate to Admin > Settings- > SAML

2. . Set the "Single Sign-On URL" for your identity provider - For example: https://samlserver.school.edu/adfs/ls

3. Set the "Single Sign-On Identity Provider Metadata URL". This allows Schoolbox to automatically determine the Token Signing Certificates and capabilities of your Identity Provider. For example: https://samlserver.school.edu/FederationMetadata/2007-06/FederationMetadata.xml

Alternatively, copy the manually exported contents of the PEM format token signing certificate from earlier into "Single Sign-On IDP certificate"

4. Select 'Save'.

Checking the Identity Provider Metadata:

1. Add the URL into "Single Sign-On Identity Provider Metadata URL" as above.

2. Navigate to: https://schoolbox.school.edu/saml/checkidpmetadata.php

3. This should output a list of certificates and their date validity.

1. Check that your Identity Provider (E.g.: ADFS) has performed a metadata update to ensure it accepts the Schoolbox signing keys.

2. Navigate to Admin > Settings > SAML

3. Enable Single Logout

4. If not using the "Single Sign-On Identity Provider Metadata URL" option, set the "Single Logout URL Endpoint"

    E.g.: https://samlserver.school.edu/adfs/ls/

5. Select 'Save'.

1. Open the ADFS 2.0 (or 3.0) Management console and select Relying Party Trusts.
2. Select add Relaying party Trust… from the top right corner of the window. -> The add wizard appears
3. Click 'Start'.
4. Select "Import data about the relying part published online or on a network".

5. Fill in the '' - E.g. https://schoolbox.mydomain.edu.au/saml/metadata.php
6. Click 'Next'.
7. Give it a display name such as 'Schoolbox' and enter any notes you want.
8. Click 'Next'.
9. Permit all users to access this relying party
10. Click 'Next'.
11. Click 'Next'.
12. Click OK -> the Edit Claims Rules window appears.
13. Click 'Add Rule'.

14. Set 'Claim rule template' to 'Send LDAP Attributes as Claims'.

15. Click 'Next'.

16. Set a claim rule name - E.g: "Idap-claims".

17 . Set attribute store to 'Active Directory'.
18. Add the following 2 attributes mappings

• SAM-Account-Name -> Name ID
• SAM-Account-Name -> Windows account name

19. Click 'Finish'.

20. Click 'Ok'.

Web Form based Authentication with ADFS 3.0

ADFS 3.0 disables by default Forms based authentication for Intranet users. This can cause Schoolbox errors mentioning "Multiple Assertions are not supported".

This can be enabled in ADFS 3.0 by following the instructions below, mostly sourced from https://blogs.msdn.microsoft.com/josrod/2014/10/15/enabled-forms-based-authentication-in-adfs-3-0/.

1. Open the ADFS 3.0 Management console (snap-in)
2. Click Authentication Policies from the left hand tree navigation
3. In the Authentication Policies section on the right panel, choose Edit Global Primary Authentication
4. Under the Intranet section, check the Forms Authentication option.
5. Click OK to save the changes

Chrome with ADFS 3.0 and Windows Authentication

To support Chrome with kerberos/WIA (auto sign on from a domain machine) you will need to add a Chrome user agent to ADFS 3.0's list of supported user agents for WIA (if you've not already done this).

You can check your current list of user agents in powershell with:

Get-AdfsProperties | select -ExpandProperty WIASupportedUserAgents

Defaults in ADFS 3.0:

• MSAuthHost/1.0/In-Domain
• MSIE 6.0
• MSIE 7.0 
• MSIE 8.0
• MSIE 9.0
• MSIE 10.0
• Trident/7.0
• MSIPC
• Windows Rights Management Client

To add WIA support for Chrome, Safari and Firefox you can add the agent "Mozilla/5.0".

You can set the list like below (which adds "Mozilla/5.0" to the list):

Set-ADFSProperties -WIASupportedUserAgents @("MSAuthHost/1.0/In-Domain", “MSIE 6.0", “MSIE 7.0", “MSIE 8.0", “MSIE 9.0", “MSIE 10.0", “Trident/7.0", “MSIPC”, “Windows Rights Management Client”, “Mozilla/5.0")

You will also need to disable ExtendedProtectionToken checking to make Chrome work with WIA. Here is the powershell command to disable it:​​​​​​​

Set-ADFSProperties –ExtendedProtectionTokenCheck None​​​​​​​​​​​​​​

Timing Issues

Some identity providers, including ADFS can support Kerberos/WIA (Windows Authentication/WIA) at the iDP. There are two options to enable this:

1. Control from the iDP (ADFS etc.) which clients should use Kerberos/WIA
2. Control from Schoolbox which clients should use Kerberos/WIA

To allow the iDP to control the authentication type (Option 1), you will need to set Schoolbox to send requests for web form or better authentication. The configuration at Administration -> System Settings- > SAML -> Single Sign-On Authentication Type Comparison (/adminv2/setting/SAML#saml_auth_comparison) will need to be changed from 'exact' to 'minimum'. You should also set the Requested Auth Context to "Unspecified"

For Option 2, Schoolbox is required to send the instruction to the client to use Kerberos/WIA to authenticate, instead of a web form, once it gets to the iDP.

As there are many devices that do not support Kerberos, and the Kerberos fallback is a basic authentication popup, we need to specify a limited set of clients that can use Kerberos.

You can do this by adding individual IP addresses (E.g. 192.168.1.115) or CIDR ranges (E.g. 192.168.1.0/24) to the 'Single Sign-On Kerberos Whitelist' option under Admin->Settings->Security in a comma separated list. The addresses listed here will be forced to use Kerberos as the authentication method.

As not all devices on the networks you specify in the whitelist may have kerberos support, we have limited kerberos use by default to the following platforms and browsers.

• Internet Explorer / Edge on Desktop/Laptops/Tablets

Google Chrome also supports kerberos authentication out of the box. If your iDP also supports Chrome for kerberos/WIA, this can be enabled from Schoolbox under Admin->Settings->Security:

• Single Sign-On Kerberos Chrome

Both Safari and Firefox (on Desktop/Laptop only) can support kerberos if configured correctly. If these are known to be configured correctly on your network you can optionally enable those browsers using the following options also under Admin->Settings->Security:

• Single Sign-On Kerberos Firefox
• Single Sign-On Kerberos Safari

All mobile devices will be forced to use the iDP's web form for authentication.

Once SAML is configured in Schoolbox, all authentication for Schoolbox is redirected to the SAML server.

If you need to login without SAML specifically you can use the following URL example:

• https://schoolbox.mydomain.edu.au/login/?samlAuth=0

To allow the WebDav access to the Schoolbox filesystem to still work with SAML enabled, navigate to Admin > Settings > Resources, and change 'WebDAV authentication type' from 'digest' to 'basic'.

As of Schoolbox v16.5.20 onwards, you are now able to use Google SAML as your identity provider.

Set up in Google:

1. Follow the "Set up your own SAML app" instructions here: https://support.google.com/a/answer/6087519?hl=en

2. Download the Certificate when given the option, and copy the provided values

3. Upload your Schoolbox Logo and set the "Application Name" to the name of your Schoolbox. E.g. Evi, iLearn, Schoolbox etc.

4. Set the Schoolbox SAML configuration in Google.

5. Ignore any additional mappings.

6. End result in Google should look like this:

7. In Schoolbox, under Admin > Settings > Security, set the "Single Sign On URL" to match "SSO URL" provided by Google

8. Set "Single Sign-On IDP certificate" to the content of the certificate you downloaded in (2).

9. Set "IDP Entity ID" to the Google IdP Entity ID in step 2

10. Set "Enable Single Sign-On"

11. Click "Save"

12. Single Sign On with Google SAML is now enabled

1. Authenticate into Azure: https://portal.azure.com#home

2. Open menu:

3. Navigate to Azure Active Directory

4. Click Enterprise Applications

5. Click new application

6. Click create your own application.

7. Name your application and choose integrate any other application you don't find in the gallery. Click Create.

8. Once the application has been created, you will get to the application screen.

9. Click Single sign-on.

10. Click SAML.

11. Edit Basic SAML configuration adding the following:

Both the Identifier (Entity ID) and Reply URL should contain the following, substituting in your School's domain to the following URL: https://yourschool.org/saml/consume.php

12. Generate a SAML signing certificate

13. Copy the App Federation Metadata URL

14. Paste into Schoolbox (Administration -> Settings -> SAML)

15. Click Save in Schoolbox. 

NOTE: You will still need to add appropriate users and groups to the application prior to using authentication. This can be done by clicking on Users and Groups in Azure Application as shown below.

16. Log in Schoolbox as a Superuser.

17. Go to Administration > Settings > SAML.

18. You will need the metadata url or the following: SSO URL, Certificate, Entity ID.