Exchange and Azure configuration guide

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. Exchange configuration

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.

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/

Open

More information about EAC can be found here: Exchange admin center in Exchange Online.

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:

• Confirm that the executed scripts come from a trusted source with [Y] Yes and then Enter.

Open

• Execute the next command:

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

The Microsoft 'Sign in to your account' popup appears:

• Enter the administrators password and confirm with Enter.

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:

• Logging out or disconnection the Exchange Online PowerShell via the following command and confirm with [Y] Yes and then Enter:

More information about connecting to Exchange Online PowerShell can be found here: Connect to Exchange Online PowerShell

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 Admin Shell (PowerShell)

Connect to Exchange Admin Shell and issue the below command to create a new Room Mailbox with the below command:

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:

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:

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:

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:

Verify the change by running the Get-CalendarProcessing command of the particular meeting room again.

RemovePrivateProperty

This parameter determines if the meetings 'Private' flag is removed for incoming meetings. The default value in Exchange for every room mailbox is true. This means that the ‘Private’ flag of an incoming meeting is removed, making it not private (or confidential) anymore. This value needs to be set to false to have confidential meetings created in Workplace also Private in Outlook.

A complete list of Calendar Processing properties can be found here with more detailed explanation:

Set-CalendarProcessing (ExchangePowerShell)

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.

3.3.1 Creating Room List

To create a new Room List, use the below command:

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:

New-DistributionGroup (ExchangePowerShell)

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:

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

3.3.3 Removing Room Mailbox from Room List

To remove a room mailbox from a Room List, use the below command:

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:

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

The -Identity parameter is the alias of the room list whose members are to be fetched

4. Azure Portal configuration

The following steps grant access to the Microsoft Exchange Online environment using the Graph API, so Reservation Sync Interface can interact with it. 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

4.1 App Registration

You must register Spacewell Reservation Sync Interface as an App in Azure AD/Entra ID for API access.

To register an App, login to Azure Portal. Then navigate to Microsoft Entra ID in the menu on the left:

Go to App registrations:

On the App registrations page, click on New registration:

The Register an Application screen is presented.

• Enter a Name for this App

• Leave the default option Accounts in this organizational directory only under the header Supported account types as it is.

• Redirect URI can be left empty

Click on Register to finish creating the App:

Once the App is created, you will be redirected to the overview screen of the App.

Copy the Application (client) ID and the Directory (tenant) ID and keep them somewhere save. This information is needed later on in the configuration guide.

4.2 Generate a Client Secret

The next step is to generate a client secret for API access. Go to the overview of the App 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 Description and set an Expires value for the secret and click on Add below:

You can now see the newly created secret in the list of client secrets for the App. Copy the Expires and the Value and keep them somewhere save. This information is needed later on in the configuration guide.

4.3 Grant API access

To grant access to the App, 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:

Via the Select permissions search box, the relevant permissions can be found.

Add the following permissions:

• Calendars.Read

• Calendars.ReadBasic.All

• Calendars.ReadWrite

• MailboxSettings.Read

• Place.Read.All

Click on Add permissions when all permissions mentioned above are selected:

You can now see the added permissions in the list of Configured permissions for the App in the center panel:

More information about App permissions can be found here: Get access without a user - Microsoft Graph

4.3.1 User TimeZone preferences

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.

The MailboxSettings.Read permission makes sure the organizers preferred timezone can be accessed.

4.3.2 Restricting access to APIs

Connect to Exchange Admin Shell and enter the following command:

The -Type parameter security defines this group as a mail enabled security group

The -Alias parameter defines the email address of the group

Add room mailboxes to the security group with the below command:

The -Identity parameter is the alias of the security group

The -Member parameter is the alias of the room mailbox

Enter the above command for every Room in scope.

Now create an Access Policy with the below command:

The -AppId parameter is the Application (client) ID of the App as registered in chapter 4.1

The -PolicyScopeGroupId parameter is the email of the security group we created above

The -AccessRight parameter RestrictAccess ensures that the access is restrictive and limited to the policy scope

The -Description parameters is the description of the access policy

More details about API access policy here

Limiting application permissions to specific Exchange Online mailboxes - Microsoft Graph

4.4 Grant Admin Consent

Navigate to the API permissions screen of the App. There are two columns relevant: Admin consent required and Status (with the warning sign). These tell us that the permissions qualify as PII and there need to be an admin consent before the API can be used.

Select Grant admin constent for <organization name>

Confirm the grant admin consent by clicking Yes:

The Status and the sign now have changed for each of the permissions:

4.5 Share Credentials

Upon completing the above steps, the credentials generated for the App must now be shared securely with Spacewell Integration 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

It is recommended that the Client Secret is shared securely. A single-use expirable link can be a good way to share this information.

A secure link can be created via for example: Onetime Secret

• Enter the Client Secret in the Secret content goes here text box

• Enter a passphrase

• Enter a lifetime of the secret link

• Click on Create a secret link

• Share the link with Spacewell Integration Team

• Share the passphrase Spacewell Integration Team

Share the secret link, the passphrase and the other information mentioned above and mail it to integration@spacewell.com. Use your organization name and the Application ID in the email subject.

If we find that the link has been already used, we will ask you to delete the secret generated in chapter 4.2 and repeat the process of generating a new client secret.

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: The End of the REST API for On-Premises Mailboxes Preview

Exchange Admin Shell cmdlet reference documentation ExchangePowerShell Module

Microsoft Graph API reference Microsoft Graph REST API v1.0 endpoint reference - Microsoft Graph v1.0

Authentication and Authorization process of Microsoft Graph Microsoft Graph authentication and authorization overview