Configuring Office 365 using EWS for One-Touch Join

This service account should only be used with One-Touch Join. However, you can use the same Exchange service account for multiple One-Touch Join integrations.

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

#If not installed, install Exchange Online Module
Install-Module ExchangeOnlineManagement

#If not installed, install Azure AD Module
Install-Module -Name AzureAD

#Connect to Exchange Online and AzureAD, works also with a MFA enabled account
Connect-ExchangeOnline

#Capture password for service account
$password = Read-Host "Enter password" -AsSecureString

# Create service account and mailbox
New-Mailbox -Name "<Account Name>" -MicrosoftOnlineServicesID "<UPN>" -Password $password -Alias "<Account Alias>" -FirstName "<Account First Name>" -LastName "<Account Last Name>" -DisplayName "<Account Name>"
							
#Connect to AzureAD
Connect-AzureAD

#Set password policy
Set-AzureADUser -ObjectId "<UPN>" -PasswordPolicies DisablePasswordExpiration

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-AzureADUser -ObjectId pexip-otj-svc@example.com -PasswordPolicies DisablePasswordExpiration

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/powershell/exchange/connect-to-exchange-online-powershell?view=exchange-ps

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 Rooms2111430164340,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

To take full advantage of the functionality offered by One-Touch Join, we recommend that, for One-Touch Join room resources, you change the following calendar processing options from the default:

1. The meeting invite body is deleted by default. If you want 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).

2. 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 this Microsoft article).

   Because One-Touch Join accesses the meeting invites through the resource mailboxes, this default behavior means it 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 and thus can be displayed on the meeting room endpoints.

3. The private flag is cleared by default. If you want 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.
4. Room resources created using PowerShell commands may by default have AutomateProcessing set to AutoUpdate. In these cases it should be changed to AutoAccept.
5. When the meeting room accepts the invitation, a response is sent to the original requester (including requesters external to your organization if you have allowed forwarding of external invitations). To avoid any confusion as to why they would be receiving a response from a room that may not have been included in their original invitation, you can configure additional text that is sent to the requester using the -AddAdditionalResponse flag and -AdditionalResponse setting.

PowerShell command

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

Set-CalendarProcessing -Identity <resource_email> -DeleteComments $False -DeleteSubject $False -AddOrganizerToSubject $False -RemovePrivateProperty $False -AutomateProcessing "AutoAccept" -AddAdditionalResponse $true -AdditionalResponse "Participants can join the meeting from this room using Pexip One Touch Join."

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 means 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 want to prevent this, you can use the following PowerShell command to restrict what users can see by default, without restricting what the 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 can view the room's availability, but nothing else.
• LimitedDetails: users can 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

Below is some recommended configuration to enable external invitations to be forwarded to your internal OTJ room resources so that the meetings can be joined from those endpoints. In all cases, we recommend that you consult your Exchange administrator to determine what is appropriate in your environment.

• 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. Note that this will allow any users external to your organization to invite the resource directly. To prevent this, you can use an Exchange transport rule similar to the example shown below so that only users internal to your organization can forward external invitations to OTJ meeting rooms.

  

• 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 ""
}

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 aad.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 must use 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 page on the Administrator interface to which the Pexip Infinity administrator will be returned after they have successfully signed in to the service account. Because it is a page on the Management Node, this URI is internal to your deployment and only needs to be accessible from the administrator's web browser; you do not need to make it externally accessible. This URI 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:

• the service account password has changed
• the service account uses multi-factor authentication (MFA) and the MFA is refreshed
• 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 are asked to permit the OTJ application to sign in as the service account, and to access the mailboxes that the service account has been granted access to. (The service account will only have access to the mailboxes of the OTJ room resources, if you completed the steps in Configuring Application Impersonation on the service accountIn this step, you create a new Distribution Group, and add the rooms to be used for One-Touch Join to the group. You then use PowerShell commands to make it so that the service account will only be able to impersonate members of that Group..)

   

   If there is an option to Consent on behalf of your organization, do not select this — consent only needs to be given to the service account.

5. Select Accept.

   You are returned to the Management Node.

6. You may be asked to sign in to the Management Node again. If so, you must sign in to the Management Node (using your Management Node credentials) to complete the process of signing in to the service account.

When complete, you are returned to the Sign in to service account page and see the message Successfully signed in.