Configuring Office 365 for One-Touch Join

This service account should not be used for any other purpose other than One-Touch Join. You can however use the same service account for multiple One-Touch Join Exchange integrations.

You can create a new service account using either the Office 365 admin portal or PowerShell, as follows:

Set-ExecutionPolicy RemoteSigned

$UserCredential = Get-Credential

$Session = New-PSSession -ConfigurationName Microsoft.Exchange -ConnectionUri https://outlook.office365.com/powershell-liveid/ -Credential $UserCredential -Authentication Basic -AllowRedirection

Import-PSSession $Session

Import-Module MsOnline

Connect-MsolService -Credential $UserCredential

$password = Read-Host "Enter password" -AsSecureString

New-Mailbox -Name "<Account Name>" -MicrosoftOnlineServicesID "<UPN>" -Password $password -Alias "<Account Alias>" -FirstName "<Account First Name>" -LastName "<Account Last Name>" -DisplayName "<Account Name>"

Set-MsolUser -UserPrincipalName "<UPN>" -PasswordNeverExpires $true

Remove-PSSession $Session

New-Mailbox -Name "Pexip OTJ Service Account" -MicrosoftOnlineServicesID pexip-otj-svc@example.com -Password $password -Alias pexip-otj-svc -FirstName "Pexip OTJ" -LastName "Service Account" -DisplayName "Pexip OTJ Service Account"

Set-MsolUser -UserPrincipalName pexip-otj-svc@example.com -PasswordNeverExpires $true

Set-MsolUserLicense -UserPrincipalName "<UPN>" -AddLicenses "<license>"

Configuring Application Impersonation in this way means that when a room is added to the group, the service account will automatically be able to impersonate it. Likewise, when a room is removed, the service account will no longer be able to impersonate it.

Creating a new Distribution Group

1. Go to admin.microsoft.com and log in as the administrator.

2. From the menu on the left hand side, select Groups > Add a group.
3. For the Group Type, select Distribution List. Enter a name, email address and description and select Add.

4. Add as members of the Group the rooms to be used for One-Touch Join. These will be the rooms that the service account will impersonate.

   Note that the service account should not be added as a member of this distribution group. Instead, this step allows the service account to impersonate any member of this distribution group (i.e. any of the room resources).

5. Open up a remote PowerShell connection to Office 365 and import an Exchange session. For example see https://docs.microsoft.com/en-us/office365/enterprise/powershell/connect-to-all-office-365-services-in-a-single-windows-powershell-window

Configuring application impersonation

We recommend that you use combined PowerShell commands to configure application impersonation for the service account. This allows you to use variables, thus reducing possible copy and paste errors.

1. You may need to enable customization, if this has not already been done within your organization:

   Enable-OrganizationCustomization

2. Configure the following variables with the values you actually want to use:

   • otj_group_id: the email of the distribution list whose members you want to be impersonated.
   • otj_service_account: the email of the service account you want to grant impersonation to.
   • management_scope_to_create: the name you want the newly created management scope to have.
   • impersonation_role_name_to_create: the name you want the newly created impersonation role to have.

   For example:

   $otj_group_id = "otjrooms@example.com"
   $otj_service_account = "pexip-otj-svc@example.com"
   $management_scope_to_create = "OTJ Management Scope"
   $impersonation_role_name_to_create = "OTJ Impersonation"
   

3. Create the management scope:

   $otj_group = Get-DistributionGroup -Identity $otj_group_id
   $otj_group_dn = $otj_group.DistinguishedName
   $restriction_filter = "MemberOfGroup -eq ""$otj_group_dn"""
   New-ManagementScope -Name $management_scope_to_create -RecipientRestrictionFilter $restriction_filter
   

   Example output:

   Name                  ScopeRestrictionType Exclusive RecipientRoot RecipientFilter
   ----                  -------------------- --------- ------------- ---------------
   OTJ Management Scope  RecipientScope       False                   MemberOfGroup -eq 'CN=OTJ Rooms20190430164340,OU...

4. Set up application impersonation using the previously created management scope:

   New-ManagementRoleAssignment -Name $impersonation_role_name_to_create -Role ApplicationImpersonation -User $otj_service_account -CustomRecipientWriteScope $management_scope_to_create
   

   Example output:

   Name                Role              RoleAssigneeName  RoleAssigneeType  AssignmentMethod  EffectiveUserName
   ----                ----              ----------------  ----------------  ----------------  ----------------
   OTJ Impersonation   ApplicationImp... pexip-otj-svc     User              Direct
   

5. Verify that the above commands worked as expected. In the following command, replace <resource_email> with the email of the room resource mailbox you want to test. If it is a room which is a member of the distribution list, it should show the OTJ Impersonation in the returned roles. If it is anything else outside of the distribution list, it should not have the OTJ Impersonation listed, which means the OTJ service account does not have permission to impersonate that user.

   Get-ManagementRoleAssignment -Role ApplicationImpersonation -WritableRecipient "<resource_email>" | Format-List Name, Role, RoleAssignee, CustomRecipientWriteScope
   

   Expected output:

   Name                      : OTJ Impersonation
   Role                      : ApplicationImpersonation
   RoleAssignee              : pexip-otj-svc

Recommended configuration

In order to take full advantage of the functionality offered by Pexip Infinity One-Touch Join, we recommend that, for One-Touch Join room resources, you change three calendar processing options from the default.

• Firstly, when a meeting invite is received by a resource mailbox, by default the meeting subject is deleted and is replaced with the name of the organizer (for more information, see https://support.microsoft.com/en-gb/help/2842288/resource-mailbox-s-calendar-shows-the-organizer-s-name-instead-of-the).

  Because One-Touch Join accesses the meeting invites through the resource mailboxes, this default behavior means One-Touch Join won't have access to the original subject. You can choose to leave the default behavior for privacy reasons, or you can modify the calendar processing options for each mailbox so that the meeting subject is available to One-Touch Join and can be displayed on the meeting room endpoints.

• Secondly, by default the meeting invite body is deleted. If you wish One-Touch Join to parse meeting details from the body then you must set the DeleteComments property to False. If you leave this set to True, only those rules that process information in the calendar headers can be used (because the body will be deleted).
• Thirdly, by default the private flag is cleared. If you wish meetings that are marked as private by the organizer to remain marked as private in the room mailbox, you must set the RemovePrivateProperty flag to False.

PowerShell command

To modify the calendar processing on a room from the default settings to those we recommend for One-Touch Join, use the following PowerShell command (replacing resource_email with the address of the room resource whose processing you wish to change):

Set-CalendarProcessing -Identity <resource_email> `
-DeleteSubject $False `
-AddOrganizerToSubject $False `
-DeleteComments $False `
-RemovePrivateProperty $False

Optional configuration

Hiding invitation details from other users

In order for One-Touch Join to function fully, the service account must be able to access the body of the invitation (which is why we recommend that you set the DeleteComments property to False). However, this does mean that all other users in your deployment with access to the room resource calendar may also be able to view the body of the invitation (depending on your deployment's other policies). If you wish to prevent this, you can use the following PowerShell command to restrict what users can see by default, without restricting what the service account can access.

In the following command, replace resource_name with the name of the room resource, and replace role with one of the following roles:

• AvailabilityOnly: users will be able to view the room's availability, but nothing else
• LimitedDetails: users will be able to view the room's availability and the meeting subject and location, but not the body of the invitation.

Set-MailboxFolderPermission "resource_name:\Calendar" -User Default -AccessRights role

Allowing forwarding of external invitations

If you want to enable users to forward invitations from other organizations to your OTJ room resources, you must set the ProcessExternalMeetingMessages flag to True. This also allows users external to your organization to invite the resource directly; you should therefore consult your Exchange administrator to determine whether this is appropriate in your environment.

If your Microsoft Exchange environment uses a security application (such as Office 365 ATP, or Mimecast) to re-write URLs, this may prevent OTJ from being used to join external Microsoft Teams meetings (for example, when a user inside your organization forwards an external Microsoft Teams meeting invitation to an OTJ room resource in order to join the meeting from that endpoint). To enable users to join these meetings using OTJ, you must ensure that the security application's URL re-write rules include an exception for any URL starting with the domain https:\\teams.microsoft.com\

Checking calendar processing settings

The following PowerShell command can be used to check calendar processing settings on all of the rooms in the Distribution Group that was created for One-Touch Join.

We recommend copying and saving this as a file and running it from within PowerShell.

Before running, ensure that you edit $otj_group_id = "otjrooms@example.com" to use the email of the Distribution Group used in your own deployment.

$deleted_subjects = @()
$organizer_added = @()
$deleted_bodies = @()
$private_flag_reset = @()
$not_auto_accept = @()
$process_external = @()
$otj_group_id = "otjrooms@example.com"

Get-DistributionGroupMember -Identity $otj_group_id -ResultSize Unlimited | ForEach-Object {
Write-Host "Checking room '$($_.name)'"
$processing = Get-CalendarProcessing -Identity $_.name
$pass = $true
if ($processing.DeleteSubject) {
Write-Host "WARNING: The room '$($_.name)' is deleting the meeting subject" -ForegroundColor Red
$deleted_subjects += $_.name
$pass = $false
	}
if ($processing.AddOrganizerToSubject) {
Write-Host "WARNING: The room '$($_.name)' is adding the organizer to the meeting subject" -ForegroundColor Red
$organizer_added += $_.name
$pass = $false
	}
if ($processing.DeleteComments) {
Write-Host "WARNING: The room '$($_.name)' is deleting the meeting body" -ForegroundColor Red
$deleted_bodies += $_.name
$pass = $false
	}
if ($processing.RemovePrivateProperty) {
Write-Host "WARNING: The room '$($_.name)' is clearing the private flag on meetings" -ForegroundColor Red
$private_flag_reset += $_.name
$pass = $false
	}
if ($processing.AutomateProcessing -ne "AutoAccept") {
Write-Host "WARNING: The room '$($_.name)' is not configured to Auto Accept. Processing='$($processing.AutomateProcessing)'" -ForegroundColor Red
$not_auto_accept += $_.name
$pass = $false
	}
# Optional permission for allowing the external invites:
if ($processing.ProcessExternalMeetingMessages) {
Write-Host "The room '$($_.name)' is configured to process external (forwarded) meetings"
$process_external += $_.name
	}
if ($pass) {
Write-Host "INFO: All checks passed for room '$($_.name)'" -ForegroundColor Green
	}
}

Write-Host "Summary:"
Write-Host "There are $($deleted_subjects.count) rooms deleting the meeting subject"
if ($deleted_subjects) {
Write-Host $deleted_subjects -Separator ", "
Write-Host ""
}
Write-Host "There are $($organizer_added.count) rooms adding the organizer to the meeting subject"
if ($organizer_added) {
Write-Host $organizer_added -Separator ", "
Write-Host ""
}
Write-Host "There are $($deleted_bodies.count) rooms deleting the meeting body"
if ($deleted_bodies) {
Write-Host $deleted_bodies -Separator ", "
Write-Host ""
}
Write-Host "There are $($private_flag_reset.count) rooms clearing the private flag on meetings"
if ($private_flag_reset) {
Write-Host $private_flag_reset -Separator ", "
Write-Host ""
}
Write-Host "There are $($not_auto_accept.count) rooms not configured to Auto Accept"
if ($not_auto_accept) {
Write-Host $not_auto_accept -Separator ", "
Write-Host ""
}
Write-Host "There are $($process_external.count) rooms configured to process external (forwarded) meetings"
if ($process_external) {
Write-Host $process_external -Separator ", "
Write-Host ""
}

As of H2 2021, Microsoft will stop supporting and fully decommission Basic Authentication for EWS to access Exchange Online (for more information, see Microsoft's announcement). We therefore strongly recommend that for Office 365, all new deployments authenticate the service account using OAuth 2.0, and all existing deployments are updated to enable this option as soon as possible.

To use OAuth for the service account, you must create an app registration in Azure and then use the settings from this app registration when enabling and configuring the OAuth options within the One-Touch Join Exchange integration.

Create a new App Registration in Azure

1. Log into the Azure portal at portal.azure.com.
2. From the main panel on the left, select Azure Active Directory.

3. Select App Registrations and then New registration:

   

4. In the Register an application panel, enter the following options:
   1. Name: this can be anything you wish. In our example we have used Pexip OTJ App.
   2. Supported account types: select Accounts in this organizational directory only.

   3. Redirect URI: from the drop-down menu, select Public client/native (mobile and desktop). The URI should be the IP address or FQDN of the Management Node, in the format
      https://<Management Node Address>/admin/platform/mjxexchangedeployment/oauth_redirect/
      In our example we have used https://infinity.example.com/admin/platform/mjxexchangedeployment/oauth_redirect/

      You will need to enter this as the OAuth redirect URI when configuring a One-Touch Join Exchange integration.

      The OAuth redirect URI is the URI to which you will be returned after you have successfully signed in to the service account. It must be the same on Azure and Pexip Infinity in order for Azure to validate the sign-in request.

   

5. Select Register.

   A new panel will open where you can configure your application.

6. From the panel on the left, select API permissions.
7. Select Add a permission.

8. From the Request API permissions panel, select APIs my organization uses, search for Office 365 Exchange Online and select it:

   

9. Select Delegated permissions, and from the Select permissions list, expand EWS and select Access mailboxes as the signed-in user via Exchange Web Services, and then select Add permissions:

   

Taking note of configuration

When you Configure the One-Touch Join Exchange integration and enable OAuth authentication for the service account, you'll need to provide the following information from Azure:

• Application (client) ID: this was generated for you by Azure when you saved the App Registration:

  

  You can find this again in Azure under Azure Active Directory > App registrations, under the Application (client) ID column.

  You will need to enter this as the OAuth client ID when configuring the One-Touch Join Exchange integration.

• Redirect URI: this is the URI you entered when creating the App Registration.

  You can find this again in Azure under Azure Active Directory > App registrations, clicking on the app registration, and then clicking Redirect URIs.

  You will need to enter this as the OAuth redirect URI when configuring the One-Touch Join Exchange integration.

You will also need to know the OAuth Endpoints to use. To find this information:

1. In the Azure Portal, select Overview > Endpoints.

2. Copy the URL of the OAuth 2.0 authorization endpoint (v1).

   Ensure that you use the URL for ... endpoint (v1), not ... endpoint (v2).

   You will need to enter this as the OAuth authorization endpoint when configuring the One-Touch Join Exchange integration.

3. Copy the URL of the OAuth 2.0 token endpoint (v1)

   Ensure that you use the URL for ... endpoint (v1), not ... endpoint (v2).

   You will need to enter this as the OAuth token endpoint when configuring the One-Touch Join Exchange integration.

Configuring the Exchange integration

From the Pexip Infinity Administrator interface, go to One-Touch Join > OTJ Exchange integrations.

When you have completed the above fields, select Save. You will be returned to the main OTJ Exchange Integration page. You must now sign in to the Exchange integration using the service account details you have just created.

Signing in to the service account

If you have enabled OAuth for the first time, you must sign in to the service account after saving the configuration of the One-Touch Join Exchange integration.

You may also need to re-sign in to the service account if:

• you disable and then subsequently re-enable OAuth
• you update any of the following configuration for the One-Touch Join Exchange integration:
  • Service account username
  • OAuth client ID
  • OAuth token endpoint
• the Management Node has been offline for more than 90 days.

To sign in to the service account:

1. Ensure you have signed out of all Microsoft accounts on your device, including the Microsoft Azure portal.

2. From the Management Node, go to One-touch join > OTJ Exchange Integrations, select the Exchange integration you have just created. At the bottom of the Change OTJ Exchange integration page, select Sign in to service account:

   

   You will be taken to the Sign in to service account page.:

   

3. Copy the Sign in link and paste it into a new browser tab.

4. Sign in as the service account.

   You will be asked to permit the Application registration to access the service account:

   

5. Select Accept.

You should be returned to the Sign in to service account page and see the message Successfully signed in.