Office 365

This article will cover the process of preparing office 365 for HCP integration, it will cover the steps required for both Modern and Legacy Authentication

Basic Authentication also called “Legacy Authentication” depends on using username and password for the service account, These credentials are used to connect to Exchange Web Services (EWS) to access data in Exchange and then synchronize the data from and to Humly Control Panel

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

The Legacy / Basic authentication will be out of support on October 13th 2020 as Microsoft announced. That's why we strongly recommend using Modern Authentication over Legacy.

Create a Service Account (Required for both Modern and Legacy Authentication)
Grant Impersonation rights to the Service Account (Required for both Modern and Legacy Authentication)
Create Room mailboxes (Required for both Modern and Legacy Authentication)
Create Room List (Optional)
Modern Authentication / OAuth Preparation (Required for Modern Authentication only)

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.

Go to https://portal.office.com/adminportal/home and login with your admin account
From the users menu, click active users, then add a user, fill in the required fields and press next
Select the location of the user and assign a product license for the use, then press next
Leave the optional setting as default at this stage and press next
Summary window will appear showing the information about the created account, check the information and click finish adding
Allow the process few minutes, then the user is ready to be used.

Grant Impersonation rights to the Service Account

Impersonation rights can be granted via either PowerShell or via Office 365 Admin Center.

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”.

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 Office 365 PowerShell, please open powershell as 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

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"}

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"

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

Go to https://portal.office.com/adminportal/home and login with your admin account
Select exchange from the left bar and select permissions > admin roles > click add
Under "Name" enter “Application Impersonation". The "Description" is up to the user, and the "Write scope" can be kept at "Default".
Under the roles, click and add the admin role "ApplicationImpersonation"
Under the members, click and add the service account
Save, and close the window.

Create Room mailboxes

Room mailbox also can be called resource mailbox, 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

Go to https://portal.office.com/adminportal/home and login with your admin account
From the Exchange admin center, navigate to Recipient and then click on Resources
Select Add and choose Room mailbox
Enter the "Room Name" and specify the resource account's "Email address". Optionally add a "Location" and enter the "Capacity" and continue by clicking "Save".

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

Set-CalendarProcessing room1@domain.com -AutomateProcessing AutoAccept -AddOrganizerToSubject $False -DeleteComments $False -DeleteSubject $False -RemovePrivateProperty $false

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

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 Office 365 using Windows PowerShell:

Creates a new room list named “HCP Demo”:

New-DistributionGroup -Name "HCP Demo" -RoomList

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
```
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" -RoomList -Members room1@domain.com,room2@domain.com,room3@domain.com
```

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

Modern Authentication / OAuth Preparation

Note: 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 will be out of Microsoft support on October 13th, 2020 as Microsoft announced (postponed till new notice)

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

Login to Office 365 Admin Portal and open Azure AD Admin Portal by clicking “Azure Active Directory” under Admin Centers (click “Show All” to show Admin Centers if the menu is hidden).
This will open Azure Active Directory admin center Dashboard. You can also visit this dashboard by URL: https://aad.portal.azure.com
Click Azure Active Directory in the left panel and click “Properties” under the “Manage” section
Make a note of “Tenant ID”. This is “Office 365 Azure AD Tenant ID”
An alternative way is to use the unique name you used when you signed up to Office 365, usually it is the “<customer id>.onmicrosoft.com”
To register HCP application in Azure, click on App Registration to open the application registration blade, then click New Registration
Select the name for your application, and fill in the URI “https://localhost” and click Register
Once the application is created, the summary page should appear, make a note of “Application ID” as it will be needed later during connecting HCP to Office 365
Click on “Authentication”. if the "Web Platform" is already added for you as per the screenshot below, set the "URI" to https://localhost:3002/oauth/redirect
If you are using Humly Cloud service, then the URI should be
https://yourid.humly.cloud/oauth/redirect
Note: the URI should match the FQDN of the machine you are using to configure HCP for the first time, you can have multiple URIs if you have more than one management workstation, the above URI value assumes you will use the same HCP server browser for the initial configuration of HCP.

If you could not find the Web Platform, click on "Add Platform" and select "Web" for the right blade, then add "URI" as https://localhost:3002/oauth/redirect
Configure single page application redirection for the SSO to work properly, from the Authentication tab, click on Add Platform and select Single-page application

Use the following URI if you have on-premise installation https://localhost:3002/sso/redirect and https://yourid.humly.cloud/sso/redirect if you are using Humly Cloud service (Change "yourid" with the assigned cloud ID you got from Humly). and click Configure

Note: you can have more than one URI based on your need, localhost can be replaced with the FQDN of the machine you will be using SSO to log in as Global Admin to HCP.
Scroll down the Advanced Setting section, make sure to set "Allow public client flows" to "Yes" and press save

Note: In the legacy experience UI, an app had a Reply URLs page. In the new experience, reply URLs can be found on an app's Authentication page. They're now referred to as Redirect URIs.
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 https://docs.microsoft.com/en-gb/azure/active-directory/develop/app-registrations-training-guide-for-app-registrations-legacy-users#reply-urlsredirect-urls

The Authentication can be set as per the below screen shot if you still have the Legacy experience UI
Configure Client secret by clicking on Certificates & secrets then click New client secret, enter the description you want in the newly opened blad, and set the expiry as per the policy you have, please note that the secret should be valid for HCP to work, once expired you can add a new one and replace the old from HCP global settings.

Click add and take a note of the created secret
Note: HCP will stop syncing with M365 once the secret key is expired, make sure you select the correct expiry time and renew the key before it do expire.
Go to the “API permissions” setting and click the “Add Permission” button, Select "APIs my organization uses" and search for "Office 365 Exchange Online" and click on it
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 permission button.
The Application permission summary page should have been updated to include the new added permission
The application registration process is done, HCP is ready to connect to Microsoft 365 using Modern Authentication, as we mentioned you will need the noted The Tenant / Directory ID, The Application ID, The Client Secret, and the Service Account