Office 365 Calendar Integration

Customer IT / SpaceIQ Onboarding Team

 

This describes 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.

Contents

Office 365 - Set up the Customer's Calendar Server

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

 

Prerequisite

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

Step 1. Create a Service Account to use with Cronofy Enterprise Connect

Create a new Service Account to use with Enterprise Connect. The Service Account will be used to impersonate rooms or users when managing events. 

Step 1.1 Create a Service Account

  1. From https://admin.microsoft.com/

  2. Navigate to Users > Active Users.

Office-Exchange.png

Step 1.2 Create a New User Account

  1. Click on the + icon and create a new user account.

Step 1.3 Complete the Service Account details

The Set up the basics screen displays.

Basics.png

Complete the required information for the service account:

  • Enter the first namelast namedisplay nameuser name, and your email domain.

  • Select Type password and enter the password for the service account.

  • Uncheck 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.

 Click the Create button and then click the Close button.

Step 1.4 Select the Service Account

From the Active user's list, select your service account.

Step 1.5 Edit the Assigned License

For the Assigned License, select the Edit. The Assigned License screen displays.

Remove-License.png

Uncheck the check box for the assigned license.

Step 1.6 Save

Click the Save button. 

Step 2. Configure the Service Account

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

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

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

For more information, on how to set this up refer to Configure Application Impersonation below.

  • 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 cannot 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.

Step 3. Test Your Credentials

We recommend you test your Service Account using the Microsoft Remote Connectivity Analyzer (https://testconnectivity.microsoft.com/ )

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.

Step 3.1 Select the Service Account Access (Developers) test

  1. From the Exchange Server tab, select the Service Account Access (Developers) test.

Testing.png

The Service Account Access (Developers) screen displays.

Test-Config.png

2. Enter the credentials for both the Service Account and a user the Service Account is going to impersonate.

3. From the Test predefined folder drop-down, select Calendar.

4. 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 Office 365 service is ready for Enterprise Connect.

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

SiQ - Set up the Integrator Application

Step 4. Authorize Access to SiQ Integration

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

Boundaries-Cronofy.png

Step 4.1 Activate the integration in Serraview

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

3. Complete the following:

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

Step 4.2 Cronofy Enterprise Connect Email

Check your email and the activation email will contain an Activate Calendar link.

Step 4.3 Activate the Cronofy Enterprise Connect for Exchange

After you click on the activation link, you will be asked to give Cronofy Enterprise Connect permissions to manage certain resources.

The Cronofy screen displays.

Cronofy-Permissions.jpg

Click the Office 365 button. The Cronofy Exchange screen displays.

4f4ba036-4b70-48c6-8466-eb15b17a6888.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.

Additional Configuration

Configure Application Impersonation

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. Create a new Role Group

  1. In the https://outlook.office365.com/ecp/.

Office-Permissions.png

2. Under the permissions heading, click admin roles.

Add-Role.png

 

3. Click the + icon.

The new role group screen displays.

Name-Role.png

4. Complete the following:

  • In the Name field, enter the role name called ApplicationImpersonation.

  • From the Write scope, drop-down, select Default.

Step 2. Add the ApplicationImpersonation to the Roles

  1. Click on the + icon above Roles.

Add-Role-Impreoaeuhoseu.png

2. From the list, select ApplicationImpersonation.

3. Click the add -> button.

4. Click the OK button.

Step 3. Add the Service Account to Members

  1. Click on the + icon above Members.

Add-Member.png

2. From the list, select your service account.

3. Click the add -> button.

4. Click the OK button.

Step 4. Save

Click the Save button and you have finished.

For more information on how to configure Application Impersonation from Microsoft can be found in their Help Center (https://docs.microsoft.com/en-us/exchange/client-developer/exchange-web-services/impersonation-and-ews-in-exchange?redirectedfrom=MSDN )

Configure 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.

Provide 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.

Configure Multiple Accounts' Calendar Folder Permissions

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

When you have 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 can be found in the Microsoft Help Center (https://docs.microsoft.com/en-us/powershell/module/exchange/mailboxes/add-mailboxfolderpermission?view=exchange-ps )

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

Configure 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 section, 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.

Step 1. 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

Step 2. 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.

Step 3. Check and enable the RoomList flag

The next and last step necessary 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 Distribution Group and not the wider Organizational Unit.

For further reading on the Powershell commands mentioned in this article, refer to the Microsoft Help Center (https://docs.microsoft.com/en-us/exchange/client-developer/exchange-web-services/how-to-configure-impersonation )

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

Configure 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

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

Create a Room List

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

New-DistributionGroup -Name "Meeting Rooms" -RoomList

Add 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. (https://docs.cronofy.com/developers/api/enterprise-connect/list-resources/)

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