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. 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 Microsoft 365 groups in Microsoft Entra admin center, the first group is for all resources (Rooms, Desk, and Parking spaces) that we want to allow to be added to Humly Control Panel. The second group is for the account that is allowed to send email notifications related to Humly Control Panel functions. If you prefer to do everything from PowerShell, skip this section and head to PowerShell. 

1. Create a Resources Group: In Microsoft Entra Admin, go to groups, select all groups and click New Group

2. The group type should be Microsoft 365 and the membership type is Assigned, you can select any name and description as you prefer then click create.

3. Now you can add the resources you want to add to Humly Control Panel to this group, to do so, search for the name of the group you created in the previous step, click on the Members from the left blade, and click on Add Members, select the members you want from the right blade and click select

4. Now the group is created, and the resources has been added, click on the properties and copy the resource group Object ID. this object ID will be used later in the service principle creation section.

5. Create Senders Group: Repeat the previous 4 steps, instead of adding resources, add the user/s you want to use in Humly Control Panel for sending the email notifications. one user should be enough, but it is up to you if you want to add more. 

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 Microsoft 365 Groups: Checks if specified groups exist; if not, it creates them.
• Adds Members to Groups: Adds members from a distribution group to a Microsoft 365 group.
• 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 (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
   SenderAccount: The email address of the sender account that will be used.
   SenderGroup: The name of the group that will be created for the sender.
   M365Rooms: The name of the Microsoft 365 group for rooms  Example: M365-HCP-Rooms
   M365Desks: The name of the Microsoft 365 group for desks.  Example: M365-HCP-Desks
   M365Parking: The name of the Microsoft 365 group for parking. Example: M365-HCP-Parking
   Rooms-DistributionGroupSMTP: (Optional) The SMTP address of the distribution group for rooms (if any). the members of this group will be automatically added the the new M365Rooms group.
   Desks-DistributionGroupSMTP: (Optional) The SMTP address of the distribution group for desks (if any). the members of this group will be automatically added the the new M365Desks group.
   Parking-DistributionGroupSMTP: (Optional)The SMTP address of the distribution group for parking (if any). the members of this group will be automatically added the the new M365Parking group. 
2. 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

   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 .\BS-Prep-V1.1.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.
   
   

Humly - Office 365 preparation script

Configuration File Example