1. Knowledge Base
  2. Getting started!
  3. Step 1: Booking System Preparation

Booking System Preparation - Microsoft 365

This article will cover the process of preparing Office 365 for Humly Control Panel, HCP, integration. It will cover the steps required for Modern Authentication.

Modern Authentication, also called “OAuth”, and relies on the Global Administrator in your organization which grants permissions to the Humly Control Panel to access EWS application through an OAuth 2.0 flow in Azure Active Directory/Microsoft Entra. HCP application can then access EWS using a certificate-based authentication flow.

 

Microsoft has announced that the Basic/Legacy authentication will be out of support. 

We suggest you to have global administrator right to proceed with the steps below.

 

In this article you will find support in how to: 

  1. Create a Service Account 
  2. Grant Impersonation rights to the Service Account
  3. Create Room mailboxes 
  4. Create Room List Using PowerShell
  5. Modern Authentication / OAuth Preparation (Required for Modern Authentication only)

1. Create Service Account

The service account will be used for authenticating and carrying the requests between the Humly Control Panel and Office 365 via EWS. Therefore we recommend creating a dedicated account for this purpose.

To create the service account, follow the below steps, please note that you will need the Administrator permission to do these steps.

1. Go to https://admin.microsoft.com/ and login with your admin account.
From the menu, click Users, then add a Active user. Fill in the required fields and press Next
Sk_rmavbild_2021-09-20_kl._13.21.25.png
2. Select the location of the user and assign a product license for the use, then press Next.

The Service account needs a mailbox and therefore the lowest possible licens is either Exchange Online or Microsoft 365 Business Basic.

It does not work to have a Teams room account as the service account. Teams room implementation is done after the initial connection is made to Humly Control Panel and will be added as a normal resource room in Building and structures.

 

O365_Basics2.png
3. Leave the optional setting as default at this stage and click Next.

4. A summary window will appear showing the information about the created account, check the information and click "Finish adding".
Sk_rmavbild_2021-09-20_kl._13.19.21.png
5. Allow the process a few minutes, then the user is ready to be used.

2. Grant Impersonation rights to the Service Account

Impersonation rights can be granted via two options, either PowerShell or via Microsoft 365 Admin Center.

Having the service account granted with Impersonation permission is a requirement to successfully integrate Humly with your booking system Microsoft 365.

 

Option one: Using PowerShell

This method will grant the service account impersonation rights restricted only to resources (room and equipment mailboxes) by applying a “management scope”/“Write scope”.

If you are interested in restricting the impersonation scope to only allow X amount of resource rooms only, then please follow this guide.

1. Connect to your Exchange Online PowerShell via Windows PowerShell, for more details on how to connect to Exchange Online PowerShell, please refer to the below documents from Microsoft:
Connect to Exchange Online PowerShell
Connect to Exchange Online PowerShell using multi-factor authentication

Typically the below command can be used to connect to Microsoft 365 PowerShell, please open powershell as an administrator.
## On the "Execution Policy Change" question type "Y" and press "Enter".
Set-ExecutionPolicy RemoteSigned

## This will prompt a pop-up asking for credentials.

## Enter the username and password for your Office 365 admin account and click "Ok".
$UserCredential = Get-Credential

## Create session
$Session = New-PSSession -ConfigurationName Microsoft.Exchange -ConnectionUri https://outlook.office365.com/powershell-liveid/ -Credential $UserCredential -Authentication Basic -AllowRedirection

## Import session
Import-PSSession $Session

2. Create a management scope that will be used in the next step to restrict the impersonation right. The below command will limit the scope to resources (room and equipment mailboxes):
New-ManagementScope -Name "ResourceMailboxes" -RecipientRestrictionFilter { RecipientTypeDetails -eq "RoomMailbox" -or RecipientTypeDetails -eq "EquipmentMailbox" -or PrimarySmtpAddress -eq "service-account@domain.com"}

3. Grant the service account Impersonation rights using the management scope created in step 2
New-ManagementRoleAssignment -Name "ResourceImpersonation" -Role ApplicationImpersonation -User service-account@domain.com -CustomRecipientWriteScope "ResourceMailboxes"

4. Check that the Impersonation rights has been directly assigned to the service account
Get-ManagementRoleAssignment -Role "ApplicationImpersonation" -GetEffectiveUsers

Option two: Admin Center (without management scope)

Using the admin center without management scope will grant the service account Impersonation rights on all accounts.

1. Go to https://admin.exchange.microsoft.com/ and login with your admin account 

2. Select Roles from the left menu, then Admin roles and Add role group. 
3. Under Name enter Application Impersonation. The description is up to the user, and the Write scope can be kept at Default.

4. Under the roles, click and add the admin role ApplicationImpersonation.

5. Under the members, click and select your service account.
6. Press Next and Add role group.

3. Create Room mailboxes

A "Room mailbox" can also be called resource mailbox. It is the calendar that is being used to book the room, for example from Outlook.

Humly Control Panel will sync the data of the room mailboxes calendars so the meeting will be populated via HCP to the HRD devices outside the meeting rooms.

To Create Room mailbox, follow the below steps

1. Go to https://admin.exchange.microsoft.com/and login with your admin account.

From the Exchange admin center, navigate to Recipient and then click on Resources. Press Add a room resource. 

2. Enter the Room Name and specify the resource account's Email address. You can add other room settings here as well. When finished press Create.

It is highly recommended to configure the resource rooms with the below cmdlet using PowerShell:

This command will remove organizer from being the subject/title of meetings, as well as making sure private meetings from M365 stays as private meetings in Humly.

Set-CalendarProcessing <room1@domain.com> -AddOrganizerToSubject $False -DeleteComments $False -DeleteSubject $False -RemovePrivateProperty $false

3. If you want to create more resources, repeat the above steps.

4. Create Room List Using PowerShell

Creating Room Lists is an optional step, however, it will enhance the experience for the outlook users and make it easier for them to find available rooms. In Addition, you can import a room list to HCP which might have many rooms.

The below commands will help you to create a single room list and then add rooms, or create a single room list that holds all existing rooms in one go in Microsoft 365 using Windows PowerShell:

1. Creates a new room list named “HCP Demo”:
New-DistributionGroup -Name "HCP Demo" -RoomList

2. Add the room mailbox we have created in the previous step “the-lab@certus.info” to the new room list “HCP Rooms”
Add-DistributionGroupMember -Identity "HCP Demo" -Member the-lab@certus.info

3. Steps one and two can be replaced based on the user need by one command to create the room list and add the members directly.
New-DistributionGroup -Name "Roomlist-name" -Members room1@domain.com,room2@domain.com,room3@domain.com

4. Now the Room mailbox is ready to be used, to get all room lists from PowerShell please use the below command.
Get-DistributionGroup | Where { $_.RecipientTypeDetails -eq "RoomList" } | Format-Table DisplayName, Identity, PrimarySmtpAddress

5. Modern Authentication / OAuth Preparation

This section has been updated on April 19th of 2021 to match the requirement for HCP v1.5 onwards, please go through the steps below and make sure you have adjusted your existing application settings in Azure AD for HCP to work properly after you upgrade from older version of HCP.

 

OAuth is the new method of authentication in Office 365, the Legacy/Basic authentication are going to get out of Microsoft support.

To Prepare your Azure Active Directory for HCP, you need to register a custom application, please follow the below steps:

1. Login to Microsoft Entra admin center.
To register HCP application in Azure, click on App Registration to open the application registration blade, then click New Registration.
2. Select the name for your application and click Register.

3. Once the application is created, the summary page should appear, make a note of Application (client) ID and Directory (tenant) ID as it will be needed later when connecting Humly Control Panel to Microsoft 365.

4. Click on Authentication and then Add a Platform and select Web for the right fly-in.

5. You need to whitelist your Humly control panel for the oAuth flow to go through. Please add your cloud or on-premise address that you use to access Humly control panel.

Add URI as https://CLOUDNUMBER.humly.cloud/oauth/redirect for cloud customers.

Add URI as https://that-machine-ip-or-fqdn:3002/oauth/redirect for on-premise customer.

The same goes for localhost - If you want to establish a connection to Microsoft from Humly Control Panel through localhost then it needs to be whitelisted by using:

https://localhost:3002/oauth/redirect




6. Now do the same for SSO by clicking Add a platform and select Single-page application. Type in the exact same URI as you did before but change out oauth to sso.

Example
Redirect URI:
https://26364.humly.cloud/oauth/redirect

Single-page application:
https://26364.humly.cloud/sso/redirect

The format for redirect URIs has changed. They're required to be associated with an app type, either web or public. For security reasons, wildcards and http:// schemes aren't supported, except for http://localhost.

For more information please refer to Microsoft- "Register an application with the Microsoft identity platform".7. Configure Client secret by clicking on Certificates &, secrets then click New client secret, enter the description you want in the newly opened blade, and set the expiry as per the policy you have. Please note that the secret should be valid for HCP to work, once expired, meetings from Microsoft to Humly control panel will stop syncing so you will have to replace the expired client secret with a new one and reauthenticate once again to Microsoft.

8
. Click Add and take note of the created secret. It is the Value you use later in HCP.

Only client secret Value is supported with Humly integration. Secret ID is not supported and will give you an error when trying to connect.

HCP will stop syncing with Microsoft 365 once the secret key is expired, make sure you select the correct expiry time and renew the key before it do expire.

9. Go to the API permissions setting and click the Add a permission button.

10. Select Microsoft Graph
11. In the permission selection page, select Delegated Permission, which will open the list of permissions for Delegated access. Expand EWS and select EWS.AccessAsUser.All. Click the Add permissions button. 

12. The "Application permission" summary page should have been updated to include the newly added permission. 
mceclip4.png
13. The application registration process is done and HCP is ready to connect to Microsoft 365 using Modern Authentication. As we mentioned, you will need the noted Tenant / Directory ID, The Application ID, The Client Secret, and the Service Account.

When the booking system has been prepared move on to Step 2: Humly Control Panel Installation