G Suite: How to set up authentication

This guide shows you how to configure G Suite with a SAML app, which can then be used in conjunction with Room Booking to facilitate G Suite logins.

Setting up G Suite for SAML authentication

1. Sign into your G Suite admin console by going to https://admin.google.com
2. Navigate into the Apps > SAML Apps section. If you don't see the Apps icon, you might need to follow this guide:
   
   https://support.google.com/a/answer/3052550
   
   
   
3. Click the "+" icon at the bottom right of the screen to add a new SAML App
4. Next, click the Setup my own custom app button at the bottom of the Enable SSO for SAML Application window
5. Click the IdP Metadata Download button (option 2) and save it somewhere on your computer. Make sure to keep a copy of the metadata, because there's no way to retrieve it from the Google Auth panel later. Click Continue once you've got that file.
   
6. On the next step, you'll need to provide some identification information for the application. This information will be shown to other users.
   
   If you would like to use our logo you can right click on the following image to save a copy: 
   Once you're done, click the Next button.
7. On the Service Provider Details step, there are a few things you need to set:
   
   
   NOTE: It's important that there be no forward slashes / on the end of these URLs and that any instances of  yoursystemaddress are replaced with your own system name - this is the part that comes before roombookingsystem.co.uk in the URL for your Room Booking. 
   1. Set the ACS URL to the following:
      
      https://yoursystemaddress.roombookingsystem.co.uk/saml/module.php/saml/sp/saml2-acs.php/yoursystemaddress.roombookingsystem.co.uk
   2. Set the Entity ID to the following:
      
      https://yoursystemaddress.roombookingsystem.co.uk
   3. Disable Signed Response.
   4. Set the Name ID category to Basic Information and the attribute to Primary Email
   5. Set the Name ID Format to Transient. After that, click Save.
8. In the Attribute Mapping step, you assign Google's LDAP attributes to the Room Booking's placeholder equivalents.
   
   Click the  Add New Mapping button on the dialog to build a list of attributes. The Attribute Names, Categories and User Field settings we recommend using are listed in the table below:
   

   Attribute Name	Category	User Field
   givenName	Basic Information	First Name
   sn	Basic Information	Last Name
   eduPersonPrincipalName	Basic Information	Primary Email
   email	Basic Information	Primary Email
   eduPersonAffiliation	Employee Details	Department

   The eduPersonAffiliation attribute sets the Department assigned to the user in Room Booking. While you can use any assigned attribute for the user, we recommend the Employee Details > Department permission because it must be a single setting for each user. When you're happy with the settings, click Finish.

9. You'll be shown a completion message informing you that you've completed setting up the SSO for Room Booking and that now you need to upload the Google IDP data to Room Booking. Click Ok.

This completes the setup of G Suite SAML authentication.
The SAML app now needs to be enabled.

Turning on the G Suite SAML App

There are two ways you can do this, but first you need to go into Google Auth and navigate to   Apps > SAML Apps. The icon looks like this:

Then select the Room Booking System app and follow one of the following steps, depending on how you set up your Google Auth users:

1. To turn the app on for all users on your Google Auth system. 
   Click the menu icon (the 3 dots in the top right of the grey box) then click   ON for everyoneWhen you turn the SAML app on, a message will appear telling you it will be turned on for everyone in your domain, and that any overridden setting will be changed to inherited. It also warns that the change will take up to 24 hours to propagate. Click Turn on for everyone, then allow 24 hours for the changes to propagate.
2. To turn the app on for specific users.To do this, you'll need to setup a Sub-Organisation. With it you can define the SAML app to be only accessible by users in that organisation. Setting up Sub-Organisations can be done in the Users section of Google by clicking the Organisation's menu icon and selecting Add sub organisation.
   
   Once the  Sub-Organisation has been setup, go back to the SAML Apps section and click the menu icon to the right of the Room Booking entry. Select ON for some organisations. You can then override the settings for particular organisations or sub-organisations on Google.

Once you've turned the app on for the users who need it, allow 24 hours for the change to propagate. When propagation has finished, the SAML app will be active and you can proceed to set up Room Booking to use it.

Setting up Room Booking for use with G Suite

1. Open a new tab in your browser (keep G Suite open as you will need access to it shortly) and log in as an admin to Room Booking. From the admin home page go to System Settings > Authentication and set the Authentication Type to SAML/ADFS Single Sign-on. 
2. On the same page, turn on the Enable SP Initiated Login option. This passes your users to your Google login page instead of the Room Booking login page - this will look more familiar to them and help avoid confusion.
3. You may turn on the Automatically Create New Users option if you wish. This means if a user doesn't exist on Room Booking with a matching username (the email address of the Google account) at the time of the login, a new account will be created for the user. You can also turn off this option later to stop new accounts being created.
4. Lastly you need to enter the IDP metadata for Google. Select Metadata File from the Configure using section. Open your Google Identity Provider (IdP) metadata file and copy the contents into the XML Metadata of the IdP box. Then click Update System Settings to make the changes live.

Testing G Suite Logins

If you go to your normal user login page you should see that, instead of the usual Room Booking username/password box, it now resembles your organisation's standard authentication page instead (if this is not the case, go to your admin home page System Settings > Authentication and make sure the Enable SP Initiated Login tick box is ticked).

When you see the G Suite login page, you can attempt to log in using one of the users the SAML app is enabled for. You will see three possible results:

• The user is logged in and a new account is created for them in Room Booking. 
  
  
  Note: If they already had a previous account on the system and you want them to log into that one instead, we can amend the usernames on your system to resemble the new format. Please disable Google Auth login functionality by going into the  System Settings > Authentication page and switching back to your previous login method. Then contact us on schoolcloud@tes.com. If you prefer that users should not being able to access the system while we convert the usernames, you can simply untick the  SAML Enabled box on the same page - in both cases remember to save your changes.
• The user is logged into the system on their existing account. In this case, the username of the user matched the previous authentication method and no more action is required other than to roll out the new login method to everyone.
• The user is not logged in. This will happen if either:
  • The SAML app is not turned on for the user
  • The user does not exist on the system and the Automatically create new users option in System Settings > Authentication on the admin panel for Room Booking is turned off.
  • The credentials used were incorrect.

If there are any problems with the authentication method itself, Google will display an error page. The code of that error (e.g. app_not_configured) will give you a hint as to what has gone wrong. 

Here are some Google help articles which may assist you:

https://support.google.com/a/answer/2463723?hl=en

https://support.google.com/a/answer/6301076?hl=en

If all your tests succeed then you may wish to import users onto the system in bulk, in which case please see the Importing Users from G Suite guide.