Office 365 integration

The following configuration of Office 365 is needed to let GoBright communicate with the calendars in Office 365.

We assume you have the following already in your possession:

  • Administrator access to the Office 365 environment
  • Access to PowerShell

The configuration manual goes through the following steps:

  • Connect to Office 365 with PowerShell
  • Create a service account in Office 365
  • Create the room calendars in Office 365
  • Allow the Service account access to the room mailboxes
  • Create a ‘Roomlist’ in Office 365
  • Configure the user's default access to the room mailboxes
  • Configure the behavior of the room mailboxes
Connect to Office 365 with PowerShell

Connecting to Office 365 with PowerShell is the easiest way to execute several configuration commands.

For connecting to Office 365 with MFA support, Microsoft provides the EXO V2 module, published through the PowerShell gallery, which can be installed with the following steps:

  1. Start PowerShell as Administrator
  2. Install the PowerShell gallery PowerShell module:
    • Execute the following commands in PowerShell (running as administrator)
    • Install the NuGet PackageProvider:
      Install-PackageProvider -Name NuGet -MinimumVersion 2.8.5.201 -Force
    • Configure PowerShellGallery as a trusted source:
      Set-PSRepository -Name PSGallery -InstallationPolicy Trusted
    • Install the PowerShellGet module:
      Import-Module -Name PowerShellGet
  3. Install the EXO V2 (ExchangeOnlineManagement) module:
    Install-Module -Name ExchangeOnlineManagement -Force

    The '-Force' command makes sure that the latest version of the module is installed even when a previous installation exists. When the module was already installed, the PowerShell session will need to be restarted.

Now we can use the installed EXO V2 module to connect to Office 365:

  1. Start PowerShell as Administrator (make sure this is a new PowerShell session)
  2. Start connecting by logging in, use an account with the required permissions to manage your Office 365 environment:
    Connect-ExchangeOnline -UserPrincipalName you@yourdomain.com -ShowProgress $true
  3. When logged in, we are ready to proceed with the further configuration!
Create a service account in Office 365

Service account creation:

GoBright needs a service account to get access to the calendars, to be able to synchronize the room calendars.

Execute the following commands via the PowerShell session.

Now execute the following command to create the service account, please change the MicrosoftOnlineServicesID to your own name/domain and YourPasswordHere for the password you want to use for the service account:

New-Mailbox -MicrosoftOnlineServicesID gobright@yourdomain.com -Alias 'GoBright' -Name GoBright  -Password (ConvertTo-SecureString -String YourPasswordHere -AsPlainText -Force) -FirstName 'GoBright' -DisplayName 'GoBright' -ResetPasswordOnNextLogon $false

Note: now assign a regular license to the service account in the Office 365 portal, otherwise the service account will not work correctly. An 'Exchange Online (Plan 1)' license or higher is needed for the service account.

Now check if the service account is created correctly by executing the following command. The result of the command should show the mailbox of the newly created service account, if no mailbox shows up, you probably should link a license to the mailbox in the Office Admin Center. Execute the following command, replace the Identity parameter to the email address of the service account:

Get-Mailbox -Identity gobright@yourdomain.com

Authentication

The service account will need to authenticate with the GoBright platform. This is done through either basic or modern authentication within the integration. Depending on which is configured we'll discuss how it must be configured within Office 365.

Now set the service account to have a never-expiring password:

Install-Module MSOnline -Force
Connect-MsolService
Set-MsolUser -UserPrincipalName gobright@yourdomain.com -PasswordNeverExpires $true
Impersonation

Impersonation must be configured because of throttling quota configurations of Office365. There are two levels of doing configuring this, please read the two options below.

For more information on why impersonation is used, please refer to the following MSDN article.

Only room mailboxes - maximum restriction

For the room calendar integration to work, it is necessary to give ‘impersonation’ rights to the service account, as described above. The minimum level of access is to have impersonation access to the room mailboxes you want to integrate with. This way integration will be working correctly, and there will be no throttling limits from Office 365.

Execute the following command to be able to change the impersonation setting in Office 365:

Enable-OrganizationCustomization

First, create a management scope for the resource mailboxes by executing the following command:

New-ManagementScope -Name "GoBrightResourceMailboxes" -RecipientRestrictionFilter { RecipientTypeDetails -eq "RoomMailbox" -or RecipientTypeDetails -eq "EquipmentMailbox" }

Secondly, apply the following command which assigns the created management scope to the service account, change the User parameter to the email address of the service account you’ve created:

New-ManagementRoleAssignment –Name "ResourceImpersonation" –Role ApplicationImpersonation –User gobright@yourdomain.com –CustomRecipientWriteScope "GoBrightResourceMailboxes"

Execute the following command to check if the permissions are given, change the RoleAssignee to the email address of the service account you’ve created. The result of the command should show at least 1 line with the service account.

Get-ManagementRoleAssignment -RoleAssignee gobright@yourdomain.com -Role ApplicationImpersonation -RoleAssigneeType user
Full integration - maximum integration

To enable full integration with the calendar of the user (for integrated users in GoBright), it is necessary to give ‘impersonation’ rights to the service account.

This way a new booking on an integrated room will be done by creating an appointment in the calendar of the user and invite the room (when creating an appointment in GoBright). This way when the user can later on easily change the booking, as the user is the organizer and the booking of the room will change automatically.

Execute the following command to be able to change the impersonation setting in Office 365:

Enable-OrganizationCustomization

Execute the following command, change the User parameter to the email address of the service account you’ve created:

New-ManagementRoleAssignment –Name:GoBrightImpersonation –Role:ApplicationImpersonation –User:gobright@yourdomain.com

Execute the following command to check if the permissions are given, change the RoleAssignee to the email address of the service account you’ve created. The result of the command should show at least 1 line with the service account.

Get-ManagementRoleAssignment -RoleAssignee gobright@yourdomain.com -Role ApplicationImpersonation -RoleAssigneeType user
Finishing the service account creation

Finishing the service account creation

The service account is now created:

  • As an account with a mailbox
  • With a non-expiring password
  • With impersonation rights

Please write down the following, as you will need them later in the GoBright portal:

  • The login credentials of the service account (email address and password)
Create the room calendars in Office 365

With the steps below, you’re able to create rooms in your Office 365 environment. This will publish the rooms in Office 365, and give a calendar for each room.

If you already have room calendars in your Office 365 environment, then proceed with the next step, but make sure you have the e-mail addresses of the rooms, because you will need them later on.

Execute the following commands via the PowerShell session.

Execute the following command, change the MicrosoftOnlineServicesID to the room email address you would like, and supply a correct Name, DisplayName, and Password for this room:

New-Mailbox -EnableRoomMailboxAccount $true -Room -MicrosoftOnlineServicesID room1@yourdomain.com -Name Room1 -DisplayName 'Room 1' -RoomMailboxPassword (ConvertTo-SecureString -String YourPasswordHere -AsPlainText -Force)

If needed you can set the Organizational Unit via the -OrganizationalUnit parameter. The example command above presumes the default Organizational Unit.

Execute this command for each room you would like to create.

Allow the Service account access to the room mailboxes

The service account needs FullAccess rights to the room mailbox, so it can use the room mailbox.

Execute the following commands via the PowerShell session.

Execute the following command, change the Identity to the room email address and change User to the email address of the service account:

Get-User -Identity room1@yourdomain.com | Add-MailboxPermission -User gobright@yourdomain.com -AccessRights FullAccess

Execute this command for each room you would like to create.

Please note: Generally speaking it will take 15 to 30 minutes for this to be processed, but this can add up to 2 hours, Office 365 will not give you any indication of when this is processed. If you proceed when this is not active in Office 365, some functionality in GoBright will not work properly (e.g. changing/saving a room, extend/stop a meeting, etc.)

Create a ‘Roomlist’ in Office 365

To get the room mailboxes easily published, you should create one or more ‘Distribution Groups’ of the type ‘Roomlist’.
You might want to create multiple ‘roomlists’, for example per building, per floor, etc.

It is possible to skip this step, but then you will need to manually create the rooms in GoBright , instead of synchronizing them.

Execute the following commands via the PowerShell session.

First, create the Roomlist, change the Name if you want to give a different name to the roomlist:

New-DistributionGroup -Name 'BrightBooking Rooms' –RoomList

Now add each room mailbox with the following command, change the Identity to the name of the list, and change the Member to the email address of the room:

Add-DistributionGroupMember -Identity 'BrightBooking Rooms' -Member room1@yourdomain.com

Execute this command for each room mailbox, so each room mailbox is added to the list.

Configure the user's default access to the room mailboxes

Now the access of the users to the room mailboxes should be configured.

Execute the following commands via the PowerShell session.

With the following command you set the default access for each room mailbox to ‘read only, with limited details’, this usually is best, so users cannot change directly in the room mailbox. Change the value of Identity to the email address of the room.

Set-MailboxFolderPermission -Identity room1@yourdomain.com:\Calendar -User Default -AccessRights LimitedDetails

Note: the folder name ‘Calendar’ is dependant to the culture settings of the room mailbox, so ‘Calendar’ also might be some translated value like ‘Agenda’. The command will fail with an error message if you’re using the wrong folder name.

Execute the following command to get the folder name (e.g. when the command above fails):

Get-MailboxFolderStatistics -Identity room1@yourdomain.com | Where-Object {$_.FolderType -eq "Calendar"} | Select Name,FolderType,Identity
Configure the behavior of the room mailboxes

The default behavior of a room mailbox changes the subject of the appointment and removes the private flag if it’s set. Via the following command, the room mailbox is configured to automatically process (accept/decline) meeting requests and keeps the data of the meeting in place.

Execute the following command via the PowerShell session.

Configure the behavior of the room mailbox, change the Identity parameter to the email address to the email address of the room:

Set-CalendarProcessing -Identity room1@yourdomain.com -AutomateProcessing AutoAccept -DeleteSubject $False -DeleteComments $False -AddOrganizerToSubject $False -RemovePrivateProperty $False

Execute this command for each room mailbox.

When needed, you can change this best-practice to get different behavior. The following parameters are the most important:

  • AutomateProcessing: AutoAccept will make the room mailbox process meetings automatically (accept/decline). It’s also possible to do this manually, via the value ‘None’ (more info), but this also means you will have to process cancellations manually.
  • DeleteSubject: By keeping the original subject, we’re able to show the subject in the portal, app, and displays. This is possible via the value $False. If you use the value $True, the subject will be deleted by the room mailbox.
  • DeleteComments: By keeping the comments, we’re able to show the subject in the portal and app. This is possible via the value $False. If you use the value $True, the comments will be deleted by the room mailbox.
  • AddOrganizerToSubject: The room mailbox is able to add the name of the organizer to the subject, but this can get confusing. By using the value $False this is disabled.
  • RemovePrivateProperty: The room mailbox removes the private property from the incoming meeting. By using the value $False, the meeting will keep its private flag.
Setting up the Integration in GoBright

Integrations are configured in the Admin center. Login to GoBright with your admin account and click on the switch button on the top right corner. 

mceclip3.png

Within the Admin center you can click on the 'Integrations' at the top.

2021-09-20_09_17.png

Here you can 'Add' a new integration. Enter a name and set the 'External system' to Office 365. For the link you need to use the GoBright service account you've setup earlier on.

2021-09-20_09_38.png

When 'Authentication type' is set to Basic Authentication, you need to enter the email address of the service account and password.

To use SSO and/or MFA you need to set the 'Authentication type' to 'Modern authentication'. Click on 'Link Office365'. You will be redirected to Microsoft to login with your service account. 

We strongly advice to use 'Modern authentication' due to stronger security and that Microsoft will soon disable Basic Authentication. Please read this article from Microsoft

This is part of the new login experience. Please click on this article to read more about it. 

6 out of 6 found this helpful