Booking System Preparation - Office 365

This article will cover the process of preparing Office 365 for Humly Control Panel, HCP, integration. It will cover the steps required for both Modern and Basic/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 the Humly Control Panel.

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. HCP application can then access EWS using a certificate-based authentication flow.

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

This step is required for both Modern and Legacy Authentication. 

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://portal.office.com/adminportal/home and login with your admin account.
2. From the users menu, click active users, then add a user. Fill in the required fields and press "Next". 
   
3. 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 needs to be added as a resource room.

   
4. Leave the optional setting as default at this stage and click "Next".
5. A summary window will appear showing the information about the created account, check the information and click "Finish adding".
   
6. 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 Office 365 Admin Center.

Having the service account granted with Impersonation permission is a requirement to successfully integrate Humly with your bookingsystem 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”.

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

1. Go to https://portal.office.com/adminportal/home and login with your admin account 
2. Select Exchange from the left bar and select Permissions > admin roles > click add
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 add the service account
6. Save, and close the window.

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/#/homepage and login with your admin account
2. From the Exchange admin center, navigate to Recipient and then click on Resources
3. Select Add and choose Room mailbox
4. 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".
5. 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

6. 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 Office 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

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 Azure Admin Portal and open Azure Active Directory
   (click “More services” to show it if the menu is hidden).
   
   
2. This will open Azure Active Directory admin center Dashboard. You can also visit this dashboard by URL: https://aad.portal.azure.com 
3. To register HCP application in Azure, click on App Registration to open the application registration blade, then click New Registration
4. Select the name for your application and click Register 
   
5. Once the application is created, the summary page should appear, make a note of “Application ID” and "Tenant ID" as it will be needed later during connecting Humly Control Panel to Office 365 
   
6. Click on “Authentication” and then "Add a Platform" and select "Web" for the right blade.
   
   Add "URI" as https://CLOUDNUMBER.humly.cloud/oauth/redirect for cloud customers or if the Humly Control Panel is located on-premise then use https://that-machine-ip-or-fqdn:3002/oauth/redirect.
   
   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. 
   
   
7. 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 or https://that-machine-ip-or-fqdn:3002/oauth/redirect
   
   Single-page application:
   https://26364.humly.cloud/sso/redirect or https://that-machine-ip-or-fqdn:3002/sso/redirect 
   
8. 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 Microsoft- "Register an application with the Microsoft identity platform".

   
   The Authentication can be set as per the below screenshot if you still have the Legacy experience UI.
   
9. 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.
   
   Click Add and take note of the created secret. It is the "Value" you use later in HCP.
   
   
    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.
   
10. 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 permissions" button. 
    
11. The "Application permission" summary page should have been updated to include the newly added permission 
    
12. 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.