Azure AD (SAML): Setting up Azure Active Directory Authentication

SchoolCloud Room Booking supports the SAML framework as a service provider (SP). This means that Azure, which provides a valid identity provider (IdP) can be used with it (this is the method used by Office 365, for example). Users signed in with Azure are signed into the Room Booking account via a matching username. Please note that Administrators cannot be authenticated via Azure and should bookmark the direct link to the admin login instead.

Prerequisites for using Azure AD as authentication

You will need to be able to create an "enterprise app" in Azure (specifically a "Non-gallery application" for single sign-on). At the time of writing, this means that you must have an Azure AD Premium P1 subscription, or higher. Please contact Microsoft if you aren't sure which packages support this.

Azure AD configuration

Add Room Booking as a new enterprise app:
  1. Open https://portal.azure.com/ and log in to an account with Global Administrator access.
  2. On the left panel, click the Azure AD icon.
  3. Click Enterprise Applications.
  4. Click New Application 
  5. Select Non-gallery application under the Add your own app section.
  6. Type your desired application name then click Add.
  7. Then assign a user to the application (so you can test authentication) by clicking Users and Groups then Add user. Remember to click the Assign button to add the user to the authentication method. You should see them appear in the Users and groups box.
Configuring single sign-on for the enterprise app

Now that you have created the application and assigned a user to it you need to assign the single sign-on method to the application, so that Azure AD knows how to handle the logins.

  1. On the application overview page, click Single Sign-On.
  2. Select SAML from the single sign-on method list.
  3. Click the pencil icon next to Basic SAML Configuration.
  4. Perform one of the following:
    • Either download the metadata from the Settings > Authentication > SAML/ADFS Single Sign-On section of the Room Booking admin panel, then click Upload metadata file in Azure and select the metadata you downloaded from Room Booking. 
    • Or enter your system's details using the following table, replacing systemname with the first part of your Room Booking URL:
      Configuration Item Item Value
      Identifier (Entity ID) https://systemname.roombookingsystem.co.uk
      Reply URL (Assertion Consumer Service URL)
      		https://systemname.roombookingsystem.co.uk/saml/module.php/saml/sp/saml2-acs.php/systemname.roombookingsystem.co.uk


      and click save when done.

  5. Click the pencil icon in the User Attributes and Claims section and set it up per the following table:
    Claim Name Namespace Attribute Notes
    nameidentifier http://schemas.xmlsoap.org/ws/2005/05/identity/claims user.userprincipalname Unused but cannot be deleted in Azure AD.
    eduPersonAffiliation none user.department Used to update the department on the Room Booking user account.
    eduPersonPrincipalName none user.userprincipalname Checked against the usernames which exist on Room Booking.
    email none user.mail Used to update the assigned email address on the Room Booking user account.
    givenName none user.givenname Used to update the forename on the Room Booking user account.
    sn none user.surname Used to update the assigned surname on the Room Booking user account.
    NOTE: The claim name should be exactly as above, for example no namespace used for the majority of the claim names.

    The resulting table should look as follows:

  6. In the SAML Signing Certificate section, note down the App Federation Metadata URL. This will be used in Room Booking configuration.

Note that no one is assigned to the authentication method at the moment, so no one is able to use it. You will need to setup some users to access the application by clicking  Users and Groups on the left and choosing users to log in. Once you have set up Azure you need to configure Room Booking to use the new authentication method.

Room Booking configuration

  1. Log into your school or business' Room Booking as an administrator and go to Settings > Authentication > SAML/ADFS Single Sign-on.
  2. Enable the SAML Enabled and Enable SP Initiated Login options.
  3. We recommend enabling Automatically Create New Users for testing purposes during this setup, even if you don't intend on using it in practice. Generally, once you've tested sign-in, we recommend you to have this turned on.

    Whether you wish to use the Update User Department Upon Login option depends on if you use departments in Azure - some organisations don't use them.
  4. Select the Metadata File (auto-refresh) radio button in the Configure using area.

    Paste the Metadata URL from step 6 of the last section. The entity ID can be found at the top of the metadata XML if you were to open the Metadata URL in a web browser.

    Alternatively, to get the Entity ID, start with the Metadata URL and remove everything from the start of "federationmetadata" to the end. You should end up with something like the following (note it's important you keep the forward slash at the end):
    Replace login.microsoftonline.com with sts.windows.net.

    You should now have something which looks like the following, this is your Entity ID:


    https://sts.windows.net/9758266b-fe3b-4e6c-87de-92dc6ab4c18e/

  5. Test a login by going to your school or business' Room Booking user login page.

    If the usernames on Room Booking match whatever attribute you assigned to the eduPersonPrincipalName token in step 5 of the last section, you will be logged into the matching account.

    If the usernames don't match, you may be logged into a brand new user account, or told that there was no matching account - depending on whether or not you enabled the Automatically create new users option earlier. If you believe there is a problem matching the accounts, or your test doesn't work, please get in touch with us and we'll investigate it with you.

Testing the setup

Azure is currently set to be accessible to whatever users were added in the testing section. To test the login, please open a browser you don't normally use (this is because Azure can tell if a user logged in even if they choose to remove all login cookies from the site) and navigate to your user login page (i.e. https://[system link].roombookingsystem.co.uk ).

You should see the login page for your Azure instance, for example:

Type in the test user's email/username and password to log in. 

Assuming the credentials were correct, you may be asked if you want to be remembered on the system. After that, you should be logged straight into Room Booking. If this doesn't work, please check the Troubleshooting section below.

Enabling the application for all users

If your tests worked, you can deploy the application to all of your users when needed. Access control is configured through the Users and Groups section of the Azure setup.

In Azure, open Azure Active Directory > Enterprise Applications > All Applications > Select the application you have setup previously > Users and Groups and assign those users and groups to whom you want to grant access. They will be able to log in instantly.

Troubleshooting

When a user logs in, they see an error saying "Could not auto-login as your username wasn't found on the system" This happens when the Automatically Create New Users option is turned off and the user trying to log in doesn't already exist.
You can either:
  • Turn on the option to Automatically Create New Users in the System Settings > Authentication section of the administration panel
  • Create the user in the Users tab, making sure the new user's Username matches the username attribute of the user. 
When a user logs in, they see a "bad request" error.
If you see this error there's usually more information at the bottom right of the page.

The most common reason for this is a typo in the entity ID of the Azure enterprise app.

The problem may also occur if the certificate for the application has expired, or the ACS URL is incorrect.

Temporarily Disabling Azure Logins

You can disable Azure logins in Room Booking by performing one of the below:

  • Going into Settings > Authentication on Room Booking then de-selecting the SAML Enabled option. This will present users with an error when they try to log in. 
  • Removing the users or groups from the enterprise application in Azure.

This does not affect user accounts on Room Booking, which must be removed manually, if required.

If you want to change to a different authentication method, you can do so in the same section by selecting the radio button of the authentication method you wish to use. Note that if you are changing to using LDAP logins, please get in touch with us as we will need to change a setting on your user accounts.

Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.