Booking System Preparation - MS Graph

This article will cover the process of preparing Office 365 using Graph for Humly Control Panel integration.

If you have Humly Control Panel already configured with the old application impersonation and want to switch to GRAPH, please skip the steps of creating room mailboxes and start from Register a new app .

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.

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

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

Application Registration and API Permissions

In this section, we will prepare Microsoft Entra for Humly Control Panel, first, you need to register a custom application. This process can be done from Microsoft Entra admin center, and PowerShell as well, in the next steps below, we will go through the setup using Entra Admin center, if you prefer to do everything from PowerShell, skip everything and head to PowerShell.

Here is the process flow of creating the application, creating the needed groups, and assigning the required permissions
 

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. Go to Enterprise Apps section, search the app you created in the previous steps (Register an application), go to its properties and Object ID from there (this is different from the object id from “App Registration” page). 
Save this as “Object Id” for use with Exchange PowerShell in the coming steps. 

5. SSO Setup 

If you want to allow login using single sign on SSO, you should whitelist your Humly Control Panel URL in the application, you can do this by heading to Authentication, then click  Add a platform and select Single-page application. Type in your cloud URL or on prem URL followed by /sso/redirect, and click Configure. examples below 

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

7. Go to the App registration and select API permissions setting and click the Add a permission button, then select Microsoft Graph

8. In the permission selection page, select Application Permission, which will open the list of permissions for application access. Search for "User.Read" and check mark User.Read.All and click add permission.

Repeat the same step again, search for "Group.Read" and check mark Group.Read.All then click add permissions.

Resources and Senders Groups

In this section, we will create two Mail Enabled Security Groups or Microsoft 365 groups in the Microsoft Entra admin center. The first group is for all resources (Rooms, Desks, and Parking spaces) that we want to allow to be added to the Humly Control Panel. The second group is for the account that can send email notifications related to the Humly Control Panel functions. If you prefer to do everything from PowerShell, skip this section and head to PowerShell. 

1. Create a Resources Group: The example below shows how to create your Mail-Enabled Security Group.
In the Exchange Admin Center, select groups and click Add Group.

Choose Mail-Enabled Security for the group type, and click next.

Add a group name of your choice, and optionally add some description. Then click next.

Assign a group owner; the owner could be any account. Click next

Add members to the group, which could be a room, desk, and/or parking resources.

The group is created and ready to be used.

2. Now that the group is created and the resources have been added, go to Microsoft Entra

Find the group you created by searching for its name. Copy the resource group Object ID. This object ID will be used later in the service principle creation section.

3. Create Senders Group: Repeat the previous two steps, but instead of adding resources, add the users you want to use in the Humly Control Panel for sending email notifications. One user should be enough, but you can add more if you want. 

Collect the Object ID for the Senders group as well, it will be needed later in the service principle creation section.

Application Role Based Access Control

In this section, we will create a service principle and assign the permissions to the groups we have created in the previous section.

1. Connect to Exchange Online

Set-ExecutionPolicy RemoteSigned

Replace the <UPN> by the office global admin account, an example below:

Connect-ExchangeOnline -UserPrincipalName support@humly.dev

2. Create a service principle by doing the below cmdlet, replace the AppId by the application ID you have created in this step  . And replace the AppObjectId by the object ID from this step , the application name can be any name you prefer.

New-ServicePrincipal -AppId <<AppId>> -ObjectId <<AppObjectId>> -DisplayName "Some Display Name"

3. Create a management role assignment for the resources group, replace the AppId by the application ID you have created in this step . Replace the CalendarObjectID by the calendars group object ID which you have created in this step

New-ManagementRoleAssignment -App <<AppObjectId>> -Role "Application Calendars.ReadWrite"  -RecipientGroupScope <<CalendarObjectID>>

4. Create a management role assignment for the senders group, replace the AppId by the application ID you have created in this step . Replace the SenderObjectID by the senders group object ID you have created in this step.

New-ManagementRoleAssignment -App <<AppObjectId>> -Role "Application Mail.Send" -RecipientGroupScope <<SenderObjectID>>

Now you should be able to proceed to the next step of installing and configuring Humly Control Panel

Optional - Office 365 preparation via HCP-BS-Perpetration-Script using PowerShell 

In this section, we will cover preparing the booking system from using PowerShell only. The script will performs the following tasks:

• Checks and Installs Necessary Modules: Ensures that the required PowerShell modules are installed and updated, the installation will be done on the PC which you use to run the script
• Install PowerShell 7: The script will install or update PowerShell to version 7 if it is not already installed 
• Connects to Microsoft Services: Establishes connections to Exchange Online, and Microsoft Graph, please note that Microsoft Graph module installation might take up to 10 minutes.
• Creates and Registers a New Application: Registers a new application in Azure AD using the name provided in your configuration file.
• Creates a Service Principal and Client Secret: Sets up a service principal and generates a client secret for the application.
• Assigns Permissions to the Application: Grants the necessary permissions for the application to work with Microsoft Graph.
• Creates Mail-Security-Enabled Groups: Checks if specified groups exist; if not, it creates them.
• Logs Important Information: Collects and displays key information about the application and groups created.

How to Use

1. Prepare Configuration File: Ensure your configuration file (HCP-config.csv) is correctly filled out. The file should contain the below info, you can download the example we provided below and edit it as per your configurations
   ApplicationName: The name you want to give to the new application in Azure AD
   HCP-Sender: The email address of the sender account that will be used.
   HCP-Sender-Group: The group's name will be created for the sender accounts.
   HCP-Rooms: The name of the group for rooms  Example: M365-HCP-Rooms
   HCP-Desks: The name of the group for desks.  Example: M365-HCP-Desks
   HCP-Parkings: The name of the parking group. Example: M365-HCP-Parking
   Run the Script:
   a. Open PowerShell with administrative privileges. You can do this by right-clicking the Start menu, selecting "Windows PowerShell (Admin)".
   
   b. Right click the downloaded script file, go to properties, and check mark "unblock", alternatively you can do this cmdlet to allow the script to run

2. Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass -Force

   c. Navigate to the directory where the script is saved. Use the cd command to change directories (e.g., cd C:\Path\To\Script).
   
   d. Execute the script by typing .\HCPv3.5.ps1 and press Enter.
   
   
3. Follow the Instructions: The script will ask you about the config.csv location and guide you through each step, displaying messages to inform you of its progress.
4. Grant Admin Consent: At the end, you will receive a URL to grant admin consent for the new application. Copy and paste this URL into your browser, log in if necessary, and grant the required permissions.
5. Add Members: add the rooms, desks and parking as needed to the groups that has been created, please not it might take up to two hours for the permission to be applied after adding new members to each group

Humly - Office 365 preparation script

Configuration File Example