The following feature requires a Microsoft Azure Administrator to perform App registrations in the Microsoft Azure portal!
You will need information from your domain’s Azure portal to complete this set up. Perform that set up first. As this relates to your own Office365/Azure domain, support for your domain is outside the scope of VETtrak support personnel. The following acts as a guide only with successful tests conducted on sandboxed environments providing this guide information.
Feature Summary
The external authentication provider allows the Student Portal, Trainer Portal and Progress Portal to authenticate users with an external authentication provider. The OpenId provider is used to authenticate a user with their Office365 account on your domain. This is achieved by authenticating in the external environment and then providing the relevant portal with an email claim* that is matched with a VETtrak client primary email record. The claim* (email) will need to be unique in order to provide a singular match. Any duplicate records on VETtrak used as claims will result in an unsuccessful VETtrak login, even if authenticated correctly in the external provider.
*In addition to using the primary email address for matching records, you may also match on an External System code or Client Code. This change will require the claim name from the external provider to be altered on the Authentication Provider wizard with the correct claim name field from the external provider. The default claim name for the primary email address is pre-populated:
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
The existing VETtrak username/password will continue to work alongside the external authentication option. You may optionally switch off the use of the VETtrak credential through the VETtrak Security manager, toggling the relevant portal's authentication provider "Login with VETtrak credentials" to the "Disabled" option:
VETtrak Security Manager set up
To use Office365 as an external provider:
- Use the Add authentication provider option from the context menu (right click button) against “Authentication providers” node under the relevant portal.
- This will bring up the Authentication provider wizard:
- In the Authentication provider type - select the “OpenID” selection for Office365 authentication.
- Changing to the OpenID selection will alter the Provider ID and Provider Key labels to the Azure terms Application ID and Authority:
- Enter the Application ID from your Azure portal:
- Enter the authority as the Azure login URL. It will be in the form:
https://login.microsoftonline.com/{Directory(tenant) ID}/v2.0 and contain your own tenant ID
eg:
will result in a url of https://login.microsoftonline.com/06def35b-a2f8-4749-bdbd-ae96fd671b17/v2.0 for this tenant - yours will be different! If you are not altering the claim type that will be sufficient to test the portal after saving the external authentication wizard.
The relevant portal will need to have its application pool restarted for the external authentication to take affect. Any portal user will be logged out when this recycle occurs.
Azure application registration
The following steps require your own system support personnel to peform operations on your Azure domain. These are provided as guides only and this work should be undertaken by staff with relevant expertise with understanding of any security implications. The following information has been conducted in a sandboxed development environment with successful outcome to providing external authentication to mutliple portals. Support for your own system is outside the scope of VETtrak support personnel.In order for Office365 to act as an external authentication provider some set up will be required on your Azure portal. This set up will feed in to the external authentication wizard and is demonstrating authentication using the email claim from your Office365 accounts.
Each portal that participates with external authentication will require its OWN App registration!
Add application registration step one
- Log onto your Azure portal:
Navigate to the App registraitons service node:
Use the New registration button:
Give the application a name on the Register an application page eg: Trainer portal
Choose the Accounts in this organizational directory only… option for the Supported account types.
For the Redirect URI choose the “Web” option from the dropdown and add your portal URL with the postfix “/account/ExternalLoginCallback”. Note: You will need to be running portal as HTTPS.
Hit the “Register” button at the bottom of the page.
API permissions grants
Now that you have an application you will have your relevant Application ID and Tenant ID appear on successfull addition of the registration. You will now need to grant relevant permissions to this application for the portal to interact with your Office365 account data. eg:
- Select the API permissions tab:
and select the “Add a permission” button. - Click on the “Microsoft Graph” button at the top of the permissions side bar:
- Select the “Delegated permissions” button:
- Select the email, openid and profile OpenId persmissions and Add permissions button:
- You will now see the permissions under the API permissions section:
At this point the system administrator could grant admin consent for the domain by using the Grant admin consent for {organisation}:
Authentication
Select the Authentication option from the Manage Left hand menu.
- Select the ID tokens option:
- Save the configuration.
Complete the VETtrak set up and test the relevant portal for external authentication.
There are other configuration options that may be used for the application registration in showing user consent if the Azure admin did not grant access to the organisation. This is not covered here.
Successful testing of the external authentication should occur at this point.