Azure: Configuring teacher logins

Using Azure for teacher logins makes it easy for administrators to manage access to applications across the organisation's suite of apps. the teachers themselves benefit from only needing to remember one password, use one familiar login page design, and consistent login sessions.

How are teachers matched?

Teachers are matched on their email address. The email address in Azure AD must match the email address listed on the system.

How does a teacher log in?

On browsing to the teacher login page of SchoolCloud a user is instantly redirected to Azure.
Azure will then either:

• Detect an existing login session and redirect the teacher straight into the matched account on SchoolCloud.
• Fail to detect an existing login session and direct the teacher to the Azure login page. When they enter their credentials:
  • If a teacher account exists for that user on SchoolCloud, the user is redirected straight into that account.
  • If no teacher account exists for that user on SchoolCloud, they will see an error message telling them this.

Requirements

In order to set up Azure sign-in you need to be able to create a "Non-gallery application" in Azure. These might also be referred to as enterprise apps. 
At the moment, Azure AD Premium P1 includes the relevant abilities. 

In addition, make sure that email addresses are set for the teachers in SchoolCloud and that they match the address assigned to their account in Azure. If there are any duplicate emails, these will need to be removed.

Azure AD Setup

Setting up the enterprise app

To setup the SAML IdP in Azure AD:

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 Create our own app section.
6. Type your desired application name (which can be whatever you wish) then click Create.
7. Assign a user to the application (so you can test authentication) by clicking Assign users and groups then Add user/group. 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

Having created the application and assigned a test user to it you now need to assign the single sign-on method to the application, so that Azure 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. Enter your system's details using the following table:
   
   
   

   Configuration Item	Item Value
   Identifier (Entity ID)	https://auth.parentseveningsystem.co.uk
   Reply URL (Assertion Consumer Service URL)	https://auth.parentseveningsystem.co.uk/Providers/Saml/Acs
   Sign on URL	https://auth.parentseveningsystem.co.uk/systemname/teacher replace systemname with the first part of your school's SchoolCloud system URL: e.g. if this is https://greenabbey.schoolcloud.co.uk use greenabbey

    Click Save. If prompted to test now, select No, I'll test later.
5. On the SAML-based sign-on configuration page, click the pencil icon in the Attributes & Claims section. 
6. Select your preferred name identifier value. We recommend using the user.userprincipalname attribute as email addresses could change (these may be identical in some cases)
7. Assuming your Azure usernames are school email addresses, edit the other attributes so that only one is present:
   

   Name	Value	Namespace
   emailaddress	user.userprincipalname	http://schemas.xmlsoap.org/ws/2005/05/identity/claims

   If you wish to use a different value in place of the UPN you can use it here. The only requirement is that the value you use matches an email address for a teacher on the system.
   
   When you look at the claim summary, you will still see the user.userprincipalname is also assigned as the Unique User Identifier (Name ID)too. This is unused but it's required for the authentication to be completed.

8. On the SAML-based sign-in configuration page, you should find that a SAML signing certificate has been created automatically.
   Copy the App Federation Metadata URL, it will be used on your SchoolCloud system.Also, make a note of the Azure AD Identifier which is your Entity ID. This should appear in Step 4 of the SAML-based sign-on page.

That concludes the Azure AD setup, now we need to setup SchoolCloud to utilise the newly created enterprise app.

Setting up SchoolCloud for Authentication

SchoolCloud requires a URL to query for the metadata XML. On SchoolCloud, go to  Settings > Teacher Authentication and Select SAML.

Fill the Metadata URL box with the URL you copied in step 8 of the last section.

The entity ID can either be found in the Azure AD Identifier section of the SAML-based sign-on section or in the app metadata on the first line of the file:
Click Save.

Testing

You can test the setup or troubleshoot a login issue by following the steps below:

1. Ensure a test user to which you have access is allowed to use the application in Azure.
   
   You can check who is assigned to the app by opening the Enterprise Applications > Parents' Evening System app > Users and groups. From there, you can view and edit the permissions assigned to users.
2. Once you have ensured you have access to a relevant user, go to the Single Sign-on section of the app then click Test under step 5.
   
   Click the relevant "sign in" button on depending on the user you've approved access for. A new tab should open attempting to connect to SchoolCloud. 
   
3. If the login is successful, you're good to go.
   
   Otherwise, the Azure tab should show the token claims, these show you the data which is being sent for each claim.
   If the email is not present in the emailaddress section, check your claim rules are setup exactly as described above.
   
   

Troubleshooting

Issue You are signed in but not as the expected teacher, or you don't see the expected appointments. Solution This suggests that your SAML app is setup perfectly but the email sent through is one that is duplicated on the system. To correct this, in SchoolCloud go to Data > Teachers. Find all teachers with the email address of the user you signed in as and make sure the email address is only assigned to one teacher.

Issue You see the following when you try to log in with a teacher. Solution Check the teacher has been the correct email assigned to the emailaddress claim setup in the Azure SAML app (Step 7 in the Azure setup above). Check your claim map within Azure (Step 7 of the Azure setup above) is all typed/copied correctly. You may have mis-configured the claim.

Issue Solution Check the teacher has been setup with the correct email address in SchoolCloud and Azure. Check your claim map within Azure.

Issue Solution As the error indicates, the user isn't assigned to the application. You can configure who has access in Azure by going to Azure Active Directory > Enterprise Applications > Parents' Evening System (or whatever name you provided for the app) > Users and Groups. Assign the user (or group) to the application.

Issue Solution The entity ID is incorrect. You can find out what this should be set to in step 4 of the Azure setup section above.

Issue Solution The ACS URL is incorrect. You can find out what this should be set to in step 4 of the Azure setup section above.

IssueSolution The Azure application has been disabled in the application's properties.

Issue Either of these errors appear after clicking the tile in the My Apps section of Azure: Solution IdP initiated logins are not currently supported.