...
...
...
...
| Info |
|---|
This article is part of the complete 'External calendar integration (Outlook/Google Calendar)' documentation. For a complete overview, see: External calendar integration (Outlook/Google Calendar) |
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.
| Table of Contents | |
|---|---|
| minLevel | 1 |
| 6 | |
| outline | false |
| type | list |
| printable | false |
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.
...
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.
...
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:
...
| Note |
|---|
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.
...
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
...
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.
| Code Block |
|---|
Set-CalendarProcessing -Identity conf_room -RemovePrivateProperty $False |
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 rooms for the Outlook Room Finder.
...
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.
| Info |
|---|
Reservation Sync Interface requires that the Exchange has at-least one room list and the room list is visible. |
...
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 Reservation Sync Interface to interact with Microsoft Exchange Online environment using Microsoft 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
...
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 Azure AD Microsoft Entra ID in the menu on the left:
...
Go to App registrations:
...
On the App Registrations registrations page, click on New registration:
...
The Register an Application screen is presented.Give
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 App is created, you will be redirected to the Overview overview screen of the App. Make a note of
Copy the Application (client) ID and the Directory (tenant) ID. These will be needed later
...
and keep them somewhere save. This information is needed later on in the configuration guide.
...
| Info |
|---|
An app App created in via the above manner steps will be (by default) not be visible to users in the Office 365 portal or Teams in under the My Apps section. This is a background app App and is not intended for end-users. There is no need to assign this app to any Users or Groups |
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 in App Registrations and click on Certificates and Secretssecrets 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 Description and set an expiry Expires value for the secret and click on Add below:
...
| Info |
|---|
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 Copy the Expires and the Value and Expires. These will be needed laterkeep them somewhere save. This information is needed later on in the configuration guide.
...
4.3 Grant API access
To grant access to Microsoft Graph API, go to the above registered app’s overview and 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. This will show a list of available APIs
...
| Info |
|---|
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
...
| Info |
|---|
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
| Info |
|---|
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
| Note |
|---|
By default granting API access with Application permissions grants access to all User calendars in the organization. Consider limiting the scope of users |
| Warning |
|---|
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.
| Note |
|---|
What is added to this group will have access, what is not added will not have access |
| Info |
|---|
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:
...
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:
...
| Info |
|---|
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. |
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: https://learn.microsoft.com/en-us/graph/auth-v2-service
4.3.1 User TimeZone preferences
| Info |
|---|
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.
The MailboxSettings.Read permission makes sure the organizers preferred timezone can be accessed.
4.3.2 Restricting access to APIs
| Note |
|---|
A Security Group can be used to limit the access to the users and recources. For the Reservation Sync Interface it is necesarry to create a security group and add all the room recources to this group. |
Connect to Exchange Admin Shell and enter the following command:
| Code Block | ||
|---|---|---|
| ||
New-DistributionGroup -Name "Only Rooms Security Group" -Alias all_rooms_sg -Type security |
The parameter -Type parameter security defines this group as a mail enabled security group
The parameter -Alias parameter defines the email address of the group
...
Add room mailboxes to the security group with the below command:
| Code Block | ||
|---|---|---|
| ||
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
...
Enter the above command for every Room in scope.
Now create an Access Policy with the below command:
| Code Block | ||
|---|---|---|
| ||
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 parameter is the Application (client) ID of the app App as registered in chapter 4.1
The parameter -PolicyScopeGroupId parameter is the email of the mail-enabled security group we created above
The parameter -AccessRight parameter RestrictAccess ensures that the access is restrictive and limited to the policy scope
The parameter -Description parameters 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
| Code Block |
|---|
Test-ApplicationAccessPolicy -Identity pradeepg@spacewelltest.onmicrosoft.com -AppId 5002196d-7934-4f85-98ed-d65a0f249aff |
...
the description of the access policy
...
More details about API access policy here
https://learn.microsoft.com/en-us/graph/auth-limit-mailbox-access
4.4 Grant Admin Consent
| Info |
|---|
The calendar data processed by Reservation Sync using Graph API as identified in |
...
chapter 4.3 |
...
, 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, namelyof the App. There are two columns relevant: 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 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 <orgname>
This will launch a confirmation dialog. Say Yes to confirm
...
Afterwards you can see the green tick in the status<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 App must now be shared securely with Spacewell Technical 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
Attribute | Value | Application Value | |
|---|---|---|---|
Application ID | Application (client) ID (obtained in chapter 4.1) | ||
Directory ID | Directory (tenant) ID (obtained in chapter 4.1) | ||
Client Secret (one-time link | Client secret (obtained in chapter 4.2) | ||
Client Secret Expiry DateEmail Domains |
Application ID and Directory ID are generated in section 4.1 above
Client secret |
...
expiry date (obtained in chapter 4.2) | |
Email Domains | Email domains (e.g. spacewell.com) |
It is recommended that the client secret be Client Secret is shared securely using a . A single-use expirable link can be a good way to share this information.
You can create a one-time use link at A secure link can be created via for example: https://onetimesecret.com/?locale=en Save
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
...
Copy the link generated and include it in the above table.
...
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 section chapter 4.2 above and repeat the process of generating a new client secret.
| Info |
|---|
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
| Anchor | ||||
|---|---|---|---|---|
|
...