Microsoft 365 Azure

Microsoft 365 authentication can be configured to authenticate users when logging into the HelpMaster web portal. This is done through a Microsoft App registration that is created in your Azure tenant (by you). HelpMaster will use this app to authenticate the user via OAuth using their Microsoft 365 (M365) account. Your Azure administrator will need to create this App registration and a Client secret (app password) to enable authentication with M365 accounts.

Once this has been created and configured, you will need to copy the app configuration details from your Azure tenant and copy them into the HelpMaster Desktop location, Web toolbar > Web Settings icon > Web logins tab > External Authentication Providers section, so that the HelpMaster web portal can use it to authenticate. Each web portal user will also have to enable the Microsoft External login option from their Account settings while logged into the web portal.

Step 1 - Create and configure your Microsoft HelpMaster Web Portal App

1. Log in to your Microsoft Azure Portal at portal.azure.com with an administrator account
2. Navigate to Azure Active Directory > App Registrations
3. Click New registration
4. Enter a name. eg. HelpMaster Web Authentication
5. Select the scope of the accounts that you would like to grant access to. To limit access only to your Azure tenant then select the first option, Accounts in this organizational directory only ([Your org] - Single tenant)
6. Under Redirect URI (optional), select the Web platform (Note that this is NOT optional for this configuration)
7. In the Redirect URIs box, type the base url to your HelpMaster web portal and add /signin-microsoft to the end of it
   
8. Click Register to create the app registration

Step 2 - Authentication (Preview)

1. From the navigation bar select Authentication (Preview)
2. Select the Settings tab at the top and you will be presented with the following screen
   
3. Ensure that ID tokens (used for implicit and hybrid flows) is selected
4. In the Front-channel logout URL box, enter your base url to your HelpMaster web portal and add /account/logout to the end of it. This will ensure that when logging out of Windows using a Cloud Only Entra ID login, you will also be logged out of the web portal and concurrent (floating) licenses will be instantly freed up for other users
5. You can also change the scope of Supported account types here if you wish
6. Leave the remaining default options and click Save

Step 3 - Create a Client Secret

In order to be able to use the app within HelpMaster, you need to configure a Client Secret for the app.

1. Click Certificates & secrets from the left-side menu
2. Click New client secret

3. A dialog box will appear prompting for a Description of the secret. This is a descriptive label only - it isn’t the secret. Enter the descriptive name and set the expiry to your preference. Note that if the secret expires, M365 authentication of the HelpMaster web portal will stop working. You will then need to create a new secret and re-enter this value into HelpMaster. Click Add
   
4. Copy the secret from the Value column - click on the copy icon, or select and copy it manually. Save the secret somewhere safe for pasting into HelpMaster in step 4 below
   

Step 4 - Token Configuration

Due to changes by Microsoft enforcing their new minimum OAuth2 2.0 endpoint enhanced security requirements in Microsoft Edge browser, to extract EntraID family_name and given_name as separate fields, optional claims must be manually added to achieve this.

1. From the navigation bar select Token configuration
   
2. Click + Add optional claim and select Token type as ID which will present a list
3. Select the Claim types family_name and given_name followed by Add
4. These additional tokens require OpenID Connect GraphAPI permissions so tick the checkbox “Turn on the Microsoft Graph profile permissions (required for claims to appear in token)” and click Add again as shown below
   

Step 5 - Grant API Permissions

Once the app has been created, you will need to configure what Graph API permissions it will have access to. The minimum permissions that the HelpMaster web portal requires is access to read user profiles (User.Read) information so as to find the user trying to authenticate.

1. Click View API Permissions (if you’re still on the initial screen, or API Permissions from the left-side menu)
2. Click Add a permission
3. From the Request API permissions panel, click the top panel Microsoft Graph
4. Click on Delegated permissions at the top and scroll down to the User section and expand it
5. Select (tick) User.Read (Sign in and read user profile)
6. If you skipped Step 4.4 above, also scroll to OpenId permissions (1) and select (tick) profile (Allows the app to see your users’ basic profile (e.g., name, picture, user name, email address))
7. Click Add permissions
   

Once the API permissions have been granted to the HelpMaster web portal app, you may also wish to grant admin consent for all users within your Azure tenant, so that they do not have to consent themselves. Granting admin consent is not required but each user will have to consent to using their own Microsoft account if admin consent is not granted.

8. To Grant admin consent for [Your Organization] click the option and Yes to the confirmation prompt
   

Step 6 - Copy the app details into HelpMaster

The final step is to copy the configuration details from your Azure portal app registration into the HelpMaster Desktop app at Administration toolbar > System Administration icon > System Integration section > Microsoft Azure navbar > Microsoft external authentication for the web portal section, so that the HelpMaster web portal can use it to authenticate.

1. Check (tick) the Allow Microsoft external authentication box to enable the provider
2. Copy the Application (client) ID from the app registration’s Overview page, to HelpMaster’s Application (client) ID field
3. Copy the Client secret saved in step 3 into the Client secret field
4. Select What type of Microsoft accounts are allowed to authenticate depending upon the scope you require
5. If Only Microsoft accounts within an Azure Active Directory (Tenant ID endpoint) is chosen then select the Microsoft Graph national cloud corresponding to your location
   a) Microsoft Graph global service (Default) for all countries except USA & China
   b) Microsoft Graph for US Government L4 for the US national cloud
   c) Microsoft Graph for US Government L5 (DOD) for the US DOD secure cloud
   d) Microsoft Graph China (operated by 21Vianet) for the Chinese national cloud
6. Click OK to save your configuration

If all is configured correctly, clicking the Microsoft button (from the web portal login screen) should now seamlessly log you into the web portal using your Microsoft 365 credentials as long as your Work or school account has been added to Windows.

Revoking Microsoft external login

1. Login to the HelpMaster web portal
2. From the My Account drop-down select Account settings followed by External logins
   
3. Click on the Remove button next to the Microsoft registered login

See also

Microsoft 365 web authentication for HelpMaster v21 & v22

Add work or school accounts to your PC

Register an application with the Microsoft identity platform

Create a new Microsoft 365 application access policy