Office 365 Calendar Integration

Customer IT / SpaceIQ Onboarding Team

 

This article will cover the steps required to integrate SiQ with the Microsoft Office 365 calendar. When complete, this integration will let employees move meeting room bookings to their Office 365 calendar. This integration uses the Cronofy Enterprise Connector.

You must have admin capabilities within Microsoft Office 365 to set up this integration.

Office 365 Activities

Follow the steps in this process to create an account with the correct permissions to connect your calendar service to the software provider. This connection process is hosted by Cronofy and it allows the Cronofy calendar sync engine to access your calendar service and, in turn, broker that access out to your software provider.

The following diagram describes the system boundaries:

Boundaries-Cronofy__2_.png

 

Create a Service Account

First, create a new Service Account to use with Enterprise Connect. The Service Account will be used to impersonate rooms or users when managing events. Follow these steps:

 

Step 1

Create a service account by going to Office 365 admin center > USERS > Active Users:

Office-Exchange.png

 

Step 2

Click on the “+” icon and create a new user account

 

Step 3

Fill in the required information for the service account

  • Enter the first name, last name, display name, user name, and your email domain.
  • Select Type password and enter the password for the service account.
  • Deselect the “Make this person change their password the next time they sign in” check box.
  • Enter the email address of the recipient to whom the password must be sent.
  • Select Create.
  • Select Close.

Basics.png

 

Step 4

Select your service account from the Active users list.

 

Step 5

Select Edit next to the Assigned License. The Assigned License page appears:

Remove-License.png

 

Step 6

Deselect the check box for the assigned license. Select Save.

 

Configure the Service Account

There are three levels of access to an end-user’s Mailbox that can be applied to a Service Account:

  • Full
  • Restricted
  • Free-Busy

Note: In order to list resources, the Service Account must have a mailbox associated with it.

Full

Full access is configured by granting the ApplicationImpersonation role to the Service Account created in Step 1. This role allows the account to access a subset of users and/or the entire organization as desired. Help on how to do that can be found in the section below on configuring ApplicationImpersonation.

Restricted

This still requires the Service Account to be granted the ApplicationImpersonation role but that access is limited to specified folders in an end-user’s Mailbox.

Typically with Cronofy, this would be limited to Calendar folders only, thus explicitly preventing access to email data.

Whilst Cronofy doesn’t access any folders other than Calendar folders in a Mailbox, this gives confidence that Cronofy can’t access any other folders.

Free-busy

Granting the Service Account AvailabilityOnly -AccessRights permission on Mailboxes will ensure that only Free-busy data is available to Cronofy across Boundary B.

Using this level of access will prevent the Integrator’s application from creating events directly into end-user’s calendars. You should check with the Integrator that their application is able to operate with this level of access before configuring in this way.

Test Your Credentials

Next, we’d recommend you test your Service Account using the Microsoft Remote Connectivity Analyzer. You’ll need the credentials for the Service Account created in Step 1 above, as well as the email address of a user or resource mailbox configured for impersonation. If you don’t have Autodiscover configured for your domain then you will also need the public Exchange Server URL.

The Microsoft Remote Connectivity Analyzer provides a set of tools to test connectivity setup for a range of Microsoft servers and services. This includes the tests to confirm that the credentials and connectivity required for Enterprise Connect are correct and available.

Start by selecting the Service Account Access (Developers) test under the Exchange Server tab.

Testing.png

 

You’ll then be presented with the options required to enter credentials for both the Service Account and a user the Service Account is going to impersonate:

Test-Config.png

 

Once you have entered the required credentials. Make sure you choose Calendar in the Test predefined folder option. You can then click the Perform Test link to run through the required connectivity checks.

The test will tell you if it has passed or failed. If it passes, you can be confident that your customer’s Office 365 or Exchange service is ready for Enterprise Connect.

If it fails, then you can download the HTML version of the report and share that with us. The contents of the report can help us provide guidance around the cause of the failure:

Test-Report.png

 

Authorize Access

This corresponds to Boundary A in the diagram we showed before:

Boundaries-Cronofy.png

 

After going through the SpaceIQ Activities described above, an email will be sent to you with a link that takes you here:

Authorize.png

 

After selecting Office 365 you will see a screen similar to this:

Office-365-Connect.png

This will verify the Service Account credentials and use them to impersonate the user associated with the Impersonation email. Once complete you will be redirected back to your software vendor’s application and they will be able to synchronize your user/resource calendars.

Application Impersonation

Let’s set up the Application Impersonation role on the new service account, which will allow your service account, to manage events in your user's calendars.

 

Step 1

In the Office 365 Admin portal, go to Permissions:

Office-Permissions.png

 

Step 2

Go to admin roles and click the ‘+’ symbol:

Add-Role.png

 

Step 3

Enter the information required:

  • Role name: ApplicationImpersonation
  • Write scope: Default

Name-Role.png

 

Step 4

Click on the ‘+’ above Roles, and select ApplicationImpersonation from the list. Click Add, then OK:

Add-Role-Impreoaeuhoseu.png

 

Step 5

Click on the ‘+’ above Members. Select your service account from the list, click Add, then OK:

Add-Member.png

 

Step 6

Click on Save, and you’re done! More information on configuring Application Impersonation from Microsoft can be found here.

 

Access Only Calendar Folders

The Cronofy calendar sync engine does not access email folders in Mailboxes.

It is possible to prevent this explicitly by using the Add-MailboxFolderPermission to specify explicit permissions for the Service Account on the end-user’s Mailbox.

 

Providing access to private calendar folders

The Add-MailboxFolderPermission cmdlet in Powershell allows you to specify folder-level permissions for users, to a mailbox. Utilize this for more granular control over what users have access to.

Start by adding a user as a calendar delegate to a calendar with access to private items via PowerShell. The example below adds service_account@example.com as a calendar delegate to professional@example.com with access to private items.

Add-MailboxFolderPermission -Identity professional@example.com:\Calendar -User service_account@example.com -AccessRights Editor -SharingPermissionFlags Delegate,CanViewPrivateItems

Editor is the access right necessary to allow a user to create, delete and read calendar items. If you wanted the user to be able to create calendars, change Editor to PublishingEditor.

 

Configuration for multiple accounts

It is also possible to add calendar folder permissions for multiple users. Start by creating a csv file with users listed within it. The csv should be in the following format…

alias
professional.example1@cronofy.com
professional.example2@cronofy.com
professional.example3@cronofy.com

Once you’ve created and saved the csv, run the following query against it. In the example below, the file is called cronofy.csv.

Import-Csv cronofy.csv | foreach { add-MailboxFolderPermission -Identity "professional@example.com" -User $_.alias -AccessRights Editor -SharingPermissionFlags Delegate,CanViewPrivateItems

This will set the required permissions for each of the accounts listed within your csv file to the specified level.

Further information on the the Add-MailboxFolderPermission and additional parameters is available from Microsoft.

If you require any further assistance, feel free to contact us at support@spaceiq.com.

 

Impersonation Control with Distribution Groups

With some additional configuration in Exchange, you can limit the access of a Service Account to only members of a distribution group, as opposed to an entire organizational unit.

In this guide we will set up a Service Account (serviceaccount@example.com) and restrict access to impersonating members of a single Distribution Group (distgroup@example.com) and that group only.

If you’ve not set up a Service Account or a Distribution Group yet, you should do that before going any further.

 

Set up permissions

To start, provide the Service Account (in this example, serviceaccount@example.com) the permission to impersonate members/rooms in a distribution group (distgroup@example.com).

$DistGroupDN = $(Get-DistributionGroup distgroup@example.com).DistinguishedName New-ManagementScope -Name CronofyImpersonationScope -RecipientRestrictionFilter "MemberOfGroup -eq '$DistGroupDN'"
New-ManagementRoleAssignment -Name CronofyImpersonationAssignment -User serviceaccount@example.com -Role ApplicationImpersonation -CustomRecipientWriteScope CronofyImpersonationScope

 

Test your configuration

It’s a good idea after setting up the role, to test that access was correctly provisioned. The below will return a list of all members of the Distribution Group.

$DistGroupDN = $(Get-DistributionGroup distgroup@example.com).DistinguishedName
Get-Mailbox -Filter "MemberOfGroup -eq '$DistGroupDN'"

If Step 1 worked, all members of the distribution group to which the filter applies will be returned.

 

Check and enable the RoomList flag

The next and last step neccesary is to set the RoomList flag on the DistributionGroup. The RoomList flag will set up Exchange’s room finder, which is what the Service Account will use to find rooms within Exchange.

Start by getting all mailboxes in a Distribution List.

Get-DistributionGroup distgroup@example.com | Format-List RecipientTypeDetails

This command returns the room list Distribution Groups. Your results should look similar to below.

RecipientTypeDetails : RoomList

If the results returned do not show your distribution group, you need to set the RoomList flag manually for it.

Set-DistributionGroup distgroup@example.com -RoomList

Now, your Service Account will be able to Impersonate members of a specific Disribution Group, and not the wider Organizational Unit.

For further reading on the Powershell commands mentioned in this article, please see this documentation from Microsoft.

If you require any further assistance, feel free to contact us at support@spaceiq.com.

 

Resources and Room Lists

In order for applications to be able to access lists or resources and/or rooms, there is a specific configuration requirement for Office 365 and Exchange.

To create a Room or Resource you can use the Admin Web Interface for Office 365: https://portal.office.com/adminportal/home#/ResourceMailbox

Exchange users can add Resources to Distribution Lists but unfortunately Office 365 does not give the option to do this via the Admin Web Interface.

It is, however, possible via Powershell. You will first need to connect to your Office 365 instance as detailed here: https://technet.microsoft.com/en-us/library/jj984289(v=exchg.160).aspx

Once you have done that you can issue the Powershell commands required to create a Room List and add your Resource to it.

 

Creating a Room List

To create a collection of rooms called “Meeting Rooms” issue the following Powershell command:

New-DistributionGroup -Name "Meeting Rooms" -RoomList

 

Adding an existing Resource to a Room List

For an existing Room named “Board room” and an existing Room List named “Meeting Rooms” issue the following Powershell command:

Add-DistributionGroupMember –Identity "Meeting Rooms" -Member "Board room"

After you have added your Resource to a Room List you should be able to see it appear when calling the Listing Resources endpoint with an Enterprise Connect account.

 

SiQ Activities

You will need to enable this integration in SiQ.

From the SiQ Web App, complete the following:

  1. Click your Profile Name in the top right corner.
  2. Click Settings. The Settings screen displays.
  3. From the left menu, click Integrations.
  4. From the Third Party Integrations area, click the READ MORE link. The Integrations screen displays.

You can either search for Office365 Calendar in the Search field or navigate to Office365 Calendar tile. To navigate complete the following:

  1. From the left menu, click Meeting Rooms.
  2. For Office365 Calendar, click the Activate button.

The Office365 Calendar dialog displays.

office365_calandar1.png

In the Office365 Domain Name field, enter in your company's Office 365 domain name. Then click the  Activate button.

Check your email for an activation link. When you click on it, you will be asked to give Cronofy Enterprise Connect permissions to manage certain resources.

Cronofy-Permissions.jpg

0 out of 0 found this helpful
Have more questions? Submit a request