This document describes the actions that need to be performed in Microsoft Exchange and Microsoft Azure to implement the Reservation Sync Interface for Spacewell Workplace Management.
1. Scope
This configuration guide is applicable for Microsoft 365 Exchange Online including hybrid* Exchange setups. This configuration guide is not applicable for on-premise Exchange servers.
2. Who is this document for?
Microsoft Exchange Administrator who will configure the Exchange Online environment for the Reservation Sync Interface.
Microsoft Azure Administrator who will configure access to the Reservation Sync Interface as a registered application in Azure Portal.
Information Security Official who will review the administrative actions performed on the customer’s side as part of the above two roles.
3. Pre-requisites - Exchange Administration
The following steps implement and/or validate settings in Microsoft Exchange Online that are required by the Reservation Sync Interface to establish connectivity with Spacewell Workplace.
The following steps require administrator access to Exchange Online, ensure your Microsoft account has the necessary access rights.
3.1 Pre-requisites
3.1.1 How to access Exchange Admin Center
Exchange Admin Center (EAC) is the Web Console to manage Microsoft Exchange Online and can be accessed via: https://admin.exchange.microsoft.com/
More information about EAC can be found here: https://learn.microsoft.com/en-us/exchange/exchange-admin-center.
3.1.2 How to access Exchange Admin Shell
Exchange Admin Shell is shell access (via command line) to a remote Exchange instance, in this case Exchange Online. To connect to Exchange Admin Shell, you will need PowerShell and internet access.
Launch (Windows) PowerShell as an Administrator and install Exchange Online PowerShell Module by executing the following command:
Set-ExecutionPolicy RemoteSigned
Confirm that the executed scripts come from a trusted source with [Y] Yes and then Enter.
Execute the next command:
Install-Module -Name ExchangeOnlineManagement
This command will download and install the Exchange Online PowerShell module. Confirm with [Y] Yes and then Enter.
Connect to Exchange Online via the following command, replace the UserPrincipalName with your own administrators UserPrincipalName:
Connect-ExchangeOnline -UserPrincipalName johnsmith@contoso.onmicrosoft.com
The Microsoft 'Sign in to your account' popup appears:
Enter the administrators password and confirm with Enter.
If 2FA is enabled, there is a confirmation required from the Microsoft Authenticator App.
In Powershell the following screen is visible and the user is logged in to Exchange Online PowerShell:
Verify the domain by executing the following command:
Get-AcceptedDomain
Logging out or disconnection the Exchange Online PowerShell via the following command and confirm with [Y] Yes and then Enter:
Disconnect-ExchangeOnline
More information about connecting to Exchange Online PowerShell can be found here: https://learn.microsoft.com/en-us/powershell/exchange/connect-to-exchange-online-powershell?view=exchange-ps&preserve-view=true
3.2 Room Mailboxes
Room mailboxes are key to setting up sync between Workplace and Exchange. For each room defined in Workplace which can be reserved, there must be a corresponding room mailbox defined in Exchange.
3.2.1 Creating Room Mailbox
Room mailboxes are resource mailboxes that can be created either via Exchange Admin Center or Exchange Admin Shell. Unlike user mailboxes, resource mailboxes are not linked to Microsoft 365 user licenses or incur any costs, they are bundled with all Microsoft 365 subscriptions and an unlimited number of such resource mailboxes can be created.
Room mailboxes can be created manually through the Exchange Admin Center or using PowerShell. Both options are described below. Please select the method that most adheres to your current workflow.
Create a Room Mailbox via Exchange Admin Center
Login to Exchange Admin Center, and select Resources from the left side menu under the Recipients menu:
This shows list of all available room mailboxes in your Exchange subscription. Click on Add a room resource:
This opens a dialog for new Room Mailbox parameters. Provide a suitable name and email address for the room mailbox and click Next:
The next screen allows you to configure some additional properties for the room mailbox. These are optional properties that are not required for Reservation Sync Interface so they can be skipped, however if you have a large number of rooms then these properties can help users find the right room for their purpose using Outlook Room Finder:
Onto the next section, Booking Options, these settings have great impact on the Reservation Sync Interface, it is recommended to leave these settings at default values or otherwise match the configuration of the rooms in Workplace Management. These settings are discussed in greater detail in the below section 3.2.2
On the next screen, we can review the configured properties for the room mailbox and then click on Create to finish creating the room mailbox:
Once the room mailbox is created, you can see the room mailbox in the list of Resources:
Create a Room Mailbox via Exchange PowerShell
Connect to Exchange Admin Shell and issue the below command to create a new Room Mailbox with the below command:
New-Mailbox -Name "Conference Room" -alias conf_room -Room
The parameter -Name is used to set the display name of the Room in Outlook and Teams
The parameter -alias is used to generate the email address, e.g. in the above case it will be conf_room@yourdomain.com
The parameter -Room is most important, which identifies it as a Room resource mailbox and not a User account.
Once, the room is created, you can verify it by using the below command:
Get-Mailbox -Identity conf_room
The -Identity parameter value is the same as the -alias used in the create command above.
3.2.2 Fine-tuning Room Mailbox properties
Room mailboxes in Exchange Online have an extensive set of properties that determine how they automatically deal with meeting requests from users (auto-accept/decline) for example. These properties also impact the Reservation Sync Interface as well. While some of these properties are controllable from the Exchange Admin Center, more advanced configuration can be achieved from Exchange Admin Shell using the CalendarProcessing command.
To retrieve the current values for a given room mailbox use the below command:
Get-CalendarProcessing -Identity conf_room | format-list
The -Identity parameter is the alias of the room mailbox, you can also use email address here (conf_room or conf_room@yourdomain.com).
The format-list option ensures that PowerShell displays the extensive list of properties for the room mailbox:
The settings mentioned below are important for the Reservation Sync:
It is important that the settings in Exchange are aligned with settings in Workplace Management. For example, if the BookingWindowInDays of the meeting room is set to 180 in Exchange, but in Workplace Management you can reserve up to 2 years into the future, the meetings created from Workplace Management will not be synced to Exchange.
AutomateProcessing
This parameter decides if the meeting requests from users are automatically accepted by the room mailbox or delegated to a user who is the room admin. If you have not specified any booking delegates in the room mailbox setting, then this should be set to AutoAccept.
BookingWindowInDays
This parameter decides how far ahead in future the room can be booked. This value is by default 180. Make sure this setting is in line with the meeting rooms setting in Spacewell Workplace.
ConflictPercentageAllowed
This parameter determines if the room is unavailable for a few occurrences of a recurring series, but is available for the majority of it then it should still accept the series as a whole or not. If this setting is set to 0%, a recurring reservation is declined, if at least 1 conflict occurs. Make sure this setting is set properly to prevent out-of-sync situations.
Delete Subject & AddOrganizerToSubject
By default, when a room mailbox receives a meeting, it removes the subject when saving the invite in its calendar. Consequently the meetings subject is also not synchronized to Spacewell and the Spacewell touchpoints display the Organizer’s name instead of the subject.
If it is so desirable that subjects be displayed in Spacewell Workplace, then both of these parameters must be set to False. To set these values you can use the below command:
Set-CalendarProcessing -Identity conf_room -DeleteSubject $False -AddOrganizerToSubject $False
Verify the change by running the Get-CalendarProcessing command of the particular meeting room again.
A complete list of Calendar Processing properties can be found here with more detailed explanation:
https://learn.microsoft.com/en-us/powershell/module/exchange/set-calendarprocessing?view=exchange-ps
3.3 Room Lists
Room lists are used for grouping Room mailboxes into logical groups. These are not same as distribution lists, shared mailboxes or security groups. Room lists can be created via the Exchange Admin Shell and are needed to link the Room lists room mailboxes to the corresponding reservable rooms in Workplace Management. Also the Room lists are used for grouping rooms for the Outlook Room Finder.
Reservation Sync Interface requires that the Exchange has at-least one room list and the room list is visible.
Reservation Sync Interface accesses the Rooms and Room Lists via Microsoft Graph API. Sometimes it may take 24-48 hours for room data created via Exchange Admin Shell to reflect in the API depending on the Azure cloud region / availability zone the data is being created in.
3.3.1 Creating Room List
To create a new Room List, use the below command:
New-DistributionGroup -Name "All Rooms" -Alias all_rooms -RoomList
The -Name parameter is used to specify the display name of the Room List as how it appears in Outlook Room Finder
The -Alias parameter is used to generate the email address which will later be used by the Reservation
Sync Interface
The -RoomList parameter is used to identify this group as a Room List
More informatioin about the Room Lists can be found here:
https://learn.microsoft.com/en-us/powershell/module/exchange/new-distributiongroup?view=exchange-ps
3.3.2 Adding Room Mailbox to Room List
Once you have created a Room List, you now need to add room mailboxes to this list via the below command:
Add-DistributionGroupMember -Identity all_rooms -Member conf_room
The -Identity parameter is the alias or email address of the room list
The -Member parameter is the alias or email address of the room mailbox. This can also be another room list
To verify the addition of the member, run the below command
Get-DistributionGroupMember -Identity all_rooms
3.3.3 Removing Room Mailbox from Room List
To remove a room mailbox from a Room List, use the below command:
Remove-DistributionGroupMember -Identity all_rooms -Member conf_room
The -Identity parameter is the alias or email address of the room list
The -Member parameter is the alias or email address of the room mailbox. This can also be another room list
3.3.4 Listing Room Lists
To get a list of all Room Lists in your organization, use the below command:
Get-DistributionGroup -ResultSize Unlimited | Where {$_.RecipientTypeDetails -eq "RoomList"} | Format-Table DisplayName,Identity,PrimarySmtpAddress –AutoSize
The -ResultSize Unlimited parameter ensures that all the room lists are returned
The Where clause filters the list to only Room lists and not other types of groups
The Format-Table formats the output to a table structure with 3 columns: DisplayName, Identity and Email address
The -AutoSize parameter resizes column widths in the output to match the data
3.3.5 Listing contents of a Room List
To view all the member rooms and room lists for a given room list, use the below command
Get-DistributionGroupMember -Identity all_rooms -ResultSize Unlimited | Format-Table DisplayName,Identity,PrimarySmtpAddress –AutoSize
The -Identity parameter is the alias of the room list whose members are to be fetched
4. Application Access - Azure Portal
The following steps grant access to the Reservation Sync Interface to interact with Microsoft Exchange Online using Microsoft Graph API. Graph is the standard interface provided by Microsoft for programatically managing Exchange Online and replaces the erstwhile Exchange Web Services (EWS). It uses OData REST APIs and OAuth 2.0 with Client Credentials
The following steps require administrative access to Azure AD, ensure your Microsoft account has the necessary administrative privileges
4.1 App Registration
You must register Spacewell Reservation Sync Interface as an App in Azure AD for API access.
To register an App login to Azure Portal. Then navigate to Azure AD in the menu on the left
Go to App registrations
On the App Registrations page, click on New registration
This will open a new page Register an Application.
Give a suitable Name for the App
In the Supported account types, leave it at the default option (single tenant). This is not relevant
Also leave the Redirect URI section blank, this is not relevant.
Click on Register to finish creating the App
Once the app is created, you will be redirected to the Overview screen of the App. Make a note of the Application ID and the Directory ID. These will be needed later
An app created in the above manner will (by default) not be visible to users in Office 365 portal or Teams in the My Apps section. This is a background app and not intended for end-users. There is no need to assign this app to any Users or Groups
4.2 Generate Client Secret
The next step is to generate a client secret for API access. Go to the overview of the App in App Registrations and click on Certificates and Secrets from the left side menu
On the center panel, click on New client secret
This will pop-up a panel on the right side, enter a suitable description and set an expiry value for the secret and click on Add below
The secret expiry duration can be set to any value as per your organizational policy. Spacewell recommends 12 months
- Ivor Grisel (Deactivated) Describe the process of what a client should do/who they should contact with the new secret
You can now see the newly created secret in the list of client secrets for the App. Make a note of the Value and Expires. These will be needed later
4.3 Grant API access
To grant access to Microsoft Graph API, go to the above registered app’s overview and select API permissions from the left side menu.
Then click on Add a permission in the center panel.
This will open a pop-up panel on the right side. Select Microsoft Graph
In the next screen select Application permissions. This will show a list of available APIs
Spacewell Reservation Sync only supports Application permissions. Application permissions were introduced by Microsoft in 2017 as part of the Microsoft Graph API service and it is the recommended approach for background applications where an end user is not participating. Delegated permission model is only appropriate for front-end application that interact with users and are counter-productive, both design and performance wise for background applications such as the Reservation Sync interface. Delegated permission do not necessarily provide increased security. Scope limitation for API is implemented in other ways for Application permissions, as is described in the below section 4.3.2. To know more about Application permissions refer https://learn.microsoft.com/en-us/graph/auth-v2-service
In the search box search for Calendars or scroll down to the Calendars section and expand it.
Select the permissions Calendars.ReadBasic.All, Calendars.ReadWrite and Place.Read.All and click on Add permissions
- Ivor Grisel (Deactivated) Update to Calendars.Read + update image
The above permissions grants access to basic details of a meeting such as meeting schedule, organizer, participants and subject. It does not grant access to other details such meeting body, attachments, free-busy information of users. It does not grant access to mailboxes. Additionally the subject of meeting is also suppressed by default, refer section 3.2.2
You can now see the applied permissions in the list of configured permissions for the app in the center panel.
4.3.1 User TimeZone preferences
This section is only if you are using Outlook 2013 or below
Reservation Sync creates/updates meetings in UTC timezone by default in Exchange. Normally all Outlook/Teams touchpoints automatically convert and display times to all participants in their own local timezone, however some legacy touchpoints such as Outlook 2013 and below are unable to do this and display the time in source timezone (UTC), leading to confusion.
Reservation Sync can optionally create meetings in the Organizer’s preferred timezone, but for that it needs to know the organizer’s timezone preference which is part of user’s mailbox preferences. To grant access to timezone preferences, search for MailboxSettings and expand it and grant access to MailboxSettings.Read
4.3.2 Restricting access to APIs
By default granting API access with Application permissions grants access to all User calendars in the organization. Consider limiting the scope of users
This section is required if you are using Reservation Sync in room-centric mode. For details about room-centric mode see section 1 above
- Ivor Grisel (Deactivated) Change this as this we are using room-centric anyway
The API access to the app can be restricted to a sub-set of users ex: you are using Spacewell Workplace is a specific region/geography, then consider limiting the API access to users in that region
If you are using Reservation Sync in Room-centric mode and do not want to grant access to User calendars then you must limit the API access to only room mailboxes
This is done by creating a security group and then adding the desired set of users to the security group and attaching the security group to the API in the form of an access policy. You can also use existing security groups.
What is added to this group will have access, what is not added will not have access
The following steps require that you have access to Exchange Admin Shell. Refer section 3.1.2 for details
Connect to Exchange Admin Shell and issue the below command
New-DistributionGroup -Name "Only Rooms Security Group" -Alias all_rooms_sg -Type security
The parameter -Type security defines this group as a mail enabled security group
The parameter -Alias defines the email address of the group
Add room mailboxes to the security group with the below command
Add-DistributionGroupMember -Identity all_rooms_sg -Member conf_room
The -Identity parameter is the alias of the mail-enabled security group
The -Member parameter is the alias of the room mailbox
Now create an Access Policy with the below command
New-ApplicationAccessPolicy -AppId 5002196d-7934-4f85-98ed-d65a0f249aff -PolicyScopeGroupId all_rooms_sg@spacewelltest.onmicrosoft.com -AccessRight RestrictAccess -Description "Restrict Reservation Sync Interface to Room mailboxes"
The parameter -AppId is the Application ID of the app as registered in 4.1
The parameter -PolicyScopeGroupId is the email of the mail-enabled security group we created above
The parameter -AccessRight RestrictAccess ensures that the access is restrictive and limited to the policy scope
The parameter -Description is description :)
Once you have created the Access Policy you can also test it against a given user’s email address to check if they have access or not with the below cmdlet
Test-ApplicationAccessPolicy -Identity pradeepg@spacewelltest.onmicrosoft.com -AppId 5002196d-7934-4f85-98ed-d65a0f249aff
More details about API access policy here
https://learn.microsoft.com/en-us/graph/auth-limit-mailbox-access
4.4 Grant Admin Consent
The calendar data processed by Reservation Sync using Graph API as identified in section 4.3 above, qualifies as Personal Identifiable Information (PII) data as hence processing such data requires User Consent under EU GDPR regulations. Since this is a background application it cannot seek user consent directly from the user hence an administrator must consent to data processing upfront on behalf of all users. This Admin Consent is facilitated and required by Microsoft Graph before API can be used.
Navigate to the API permissions screen for the app, and you will see two columns in the table of API permissions in the center panel, namely Admin consent required and the Status, this tells us that the APIs we are going to use contain PII and that the warning symbol indicates that consent must be granted before using the API
Select Grant admin constent for <orgname>
This will launch a confirmation dialog. Say Yes to confirm
Afterwards you can see the green tick in the status
4.5 Share Credentials
Upon completing the above steps, the credentials generated for the app must now be shared securely with Spacewell Technical team which will then be configured in the Reservation Sync interface for automated API access. The following details must be shared in the given format
Attribute | Value |
|---|---|
Application ID | |
Directory ID | |
Client Secret (one-time link) | |
Secret Expiry Date | |
Email Domains |
Application ID and Directory ID are generated in section 4.1 above
Client secret and its expiry is generated in section 4.2 above
It is recommended that the client secret be shared securely using a single-use expirable link.
You can create a one-time use link at https://onetimesecret.com/
Save the Client secret in the section which says Secret content goes here…
Specify a strong passphrase and click on Create a secret Link
Copy the link generated and include it in the above table.
Also share the passphrase set above in a 1-to-1 email to integration@spacewell.com indicating the Application ID in the subject
If we find that the link has been already used, we will ask you to delete the secret generated in section 4.2 above and repeat the process.
This is just a recommended approach to securely share credentials. You can alternately follow any other secure information transmission channel of your choice and policy
Appendix
* Hybrid means that the room mailboxes are cloud native and user mailboxes may be synchronized with an on-premise Exchange Server. Also see which scenario’s Microsoft supports in regards to Hybrid setups: https://techcommunity.microsoft.com/t5/exchange-team-blog/the-end-of-the-rest-api-for-on-premises-mailboxes-preview/ba-p/3221219
Exchange Admin Shell cmdlet reference documentation https://learn.microsoft.com/en-us/powershell/module/exchange/?view=exchange-ps
Microsoft Graph API reference https://learn.microsoft.com/en-us/graph/api/overview?view=graph-rest-1.0
Authentication and Authorization process of Microsoft Graph https://learn.microsoft.com/en-us/graph/auth/?context=graph%2Fapi%2F1.0&view=graph-rest-1.0