ZIVVER Outlook Web Access Add-in - Installation manual

Introduction

Use the ZIVVER OWA add-in to securely send and receive messages directly from Outlook Web Access (OWA). This manual describes how to install the add-in in Exchange Online (part of Microsoft Office 365). The ZIVVER OWA add-in is currently not available for Exchange on-premise.

It is very important that you follow all the steps in this manual, both at Installation, and Additional required settings. Otherwise, the add-in does not work as expected and a data leak may occur.

Technical requirements

The OWA add-in is suitable to install in Exchange Online (part of Office 365). To use the OWA add-in, you should meet the following requirements:

  • Exchange supports at least Microsoft OWA API version 1.5.
  • You are not using a BETA version of OWA.
    If you are using a BETA version of OWA, you should disable it by issuing the following Powershell command:
    Set-OwaMailboxPolicy -OutlookBetaToggleEnabled $false
  • The users’ workstations (Windows or Mac) have one of the following modern browsers installed:
    • Microsoft Internet Explorer 11 or Edge
    • Google Chrome latest stable version
    • Mozilla Firefox v31 or higher
    • Apple Safari v9 or higher
  • Third-party cookies are set to allowed in browser settings. The OWA add-in uses cookies to store settings (called localStorage).

Installation

Install the OWA add-in in Exchange. Use this manifest file.

Changes in Exchange are not always implemented immediately. As a result, the add-in may not be immediately visible in the OWA mailbox after installation.

Exchange Admin Center

Follow the steps below to install the OWA add-in from the Exchange admin center:

  1. Log in to the Exchange admin center (Admin Center).
  2. Click Admin Centers.
  3. Click Exchange.
    You are now in the Exchange management center.
  4. Click organization.
  5. Click add-ins.
    You will now see an overview of all add-ins that are available for your organization.
  6. Click add to add a new add-in.
  7. Select Add from URL.
  8. Enter the following URL of the OWA add-in manifest: https://owa.zivver.com/v3/manifest.xml
  9. Click Install.
    The OWA add-in ZIVVER is now installed.
  10. Double-click ZIVVER.
  11. Select the option Make this add-in available for users in your organization.
  12. Select one of the options below. Choose option 2 if only a selected group of users within your organization uses the OWA add-in.
    1. Optional, enabled by default. - The OWA add-in is enabled for users by default. The user can manually disable the add-in.
    2. Optional, disabled by default. - The OWA add-in is disabled for users by default. The user can manually enable the add-in.
    3. Mandatory, always enabled. - Users can not disable this add-in. The OWA add-in is enabled for users by default.
  13. Click Save.
    The OWA add-in is now available to users.

Powershell

Follow the steps below to install the OWA add-in from Powershell:

  1. Open Powershell.
  2. Log in to Exchange.
  3. Use the following command to add the ZIVVER OWA add-in as a new add-in for your organization: New-App -OrganizationApp -Url https://owa.zivver.com/v3/manifest.xml.
    The OWA add-in ** ZIVVER ** is now installed.
  4. Use the following command to find out which AppID the ZIVVER OWA add-in has within your organization: Get-App -OrganizationApp | fl DisplayName, AppID
  5. Use one of the commands below to determine whether or not the OWA add-in is available to users. Choose option 2 if a select group of users within your organization uses the OWA add-in.
    1. Optional, enabled by default. Set-app -OrganizationApp -Enabled $true -DefaultStateForUser Enabled
    2. Optional, switched off by default. Set-app -OrganizationApp -Enabled $true -DefaultStateForUser AlwaysEnabled
    3. Mandatory, always enabled. Users can not disable this add-in. Set-app -OrganizationApp -Enabled $true -DefaultStateForUser AlwaysEnabled
      The OWA add-in is now available to users.

Additional required settings

Internet Explorer security zone

Add the following locations to the Trusted sites zone of Internet Explorer. This prevents a white screen during logging into the OWA add-in.

  1. Open the control panel.
  2. Click Network and Internet.
  3. Click Internet Options.
  4. Click the Security tab.
  5. Click Trusted websites.
  6. Click the Websites button.
  7. Add the following URLs as trusted websites:
    • ZIVVER OWA add-in: https://owa.zivver.com
    • ZIVVER web app: https://app.zivver.com
    • OWA, for example: https://outlook.office.com
  8. Click Close.
  9. Click OK.

Rule for ZIVVER messages

To prevent OWA from sending a ZIVVER message as a normal mail, the following rule must be set.

If you do not set this rule, ZIVVER messages will be sent un-secured and a data leak may occur.

  1. Log in to the Exchange admin center (Admin Center).
  2. Click Admin centers
  3. Click Exchange.
    You are now in the Exchange management center.
  4. Go to mail flow.
  5. Check that the rules tab is selected
  6. Click add
  7. Select Create a new rule …
  8. Click More options… at the bottom of the window that appears
  9. Give the rule the name zivver-action: discard
  10. Under Apply this rule if… select the option A message header… matches these text patterns
  11. Click Enter text…
  12. Give the header the name zivver-action.
  13. Click Enter text patterns….
  14. Enter discard
  15. Click add
  16. Click OK.
  17. Select at Do the following… the option Block the message, and the sub-option delete the message without notifying anyone
  18. Set the priority to 0.
  19. Check the option Audit this rule with severity level:.
  20. Set the level to Low.
  21. Choose the mode for this rule to be Enforce.
  22. Check the option Stop processing more rules.
  23. At Match sender address in message select the Header option.
  24. Click Save.

The rule has now been created so that a ZIVVER message is not sent via normal (unsecured) mail.

Turn on the control panel for existing users

For the control screen, ZIVVER uses the so-called OnSend functionality in OWA. This functionality is standard in Exchange. By activating the OnSend functionality, you activate the control screen in the OWA plug-in. The user sees the control screen for each message sent, unless ZIVVER has already checked the message. ZIVVER can check the message by opening the ZIVVER side panel.

Messages are sent unsecured if you do not activate OnSend functionality! This can cause a data leak.

Follow the steps below to enable OnSend functionality via Powershell for one personal mailbox:

  1. Open Powershell with admin rights.
  2. Run the following command: Set-ExecutionPolicy RemoteSigned.
  3. Type Yes.
  4. Execute the following command: $UserCredential = Get-Credential.
  5. Log in with an account that has admin access to Exchange.
  6. Run the following command: $Session = New-PSSession -ConfigurationName Microsoft.Exchange -ConnectionUri https://outlook.office365.com/powershell-liveid/ -Credential $UserCredential -Authentication Basic -AllowRedirection.
  7. Run the following command: Import-PSSession $Session.
  8. Create a new OWA mailbox policy. The following example names the policy ** OWAOnSendAddinTestUserPolicy **, but you can give the policy its own name .
    New-OWAMailboxPolicy OWAOnSendAddinTestUserPolicy
  9. Enable the OnSend functionality for this policy. Get-OWAMailboxPolicy OWAOnSendAddinTestUserPolicy | Set-OWAMailboxPolicy -OnSendAddinsEnabled:$true -OutlookBetaToggleEnabled $false

    If you disable the toggle to stop people enabling the new OWA, anyone who has already switched the toggle to on won’t be able to revert to the older interface because the toggle disappears.
  10. Apply the policy for a personal mailbox:
    Get-CASMailbox roy@zivver.com | Set-CASMailbox -OwaMailboxPolicy OWAOnSendAddinTestUserPolicy.
    The On send functionality is now enabled for this mailbox. It may take some time for this adjustment to take effect through Exchange.

    This functionality is currently only available for personal mailboxes. Microsoft does not yet offer the OnSend functionality for shared mailboxes.

Follow the steps below to enable OnSend functionality via Powershell for all personal mailboxes:

  1. Open Powershell with admin rights.
  2. Run the following command: Set-ExecutionPolicy RemoteSigned.
  3. Type Yes.
  4. Execute the following command: $UserCredential = Get-Credential.
  5. Log in with an account that has admin access to Exchange.
  6. Run the following command: $Session = New-PSSession -ConfigurationName Microsoft.Exchange -ConnectionUri https://outlook.office365.com/powershell-liveid/ -Credential $UserCredential -Authentication Basic -AllowRedirection.
  7. Run the following command: Import-PSSession $Session.
  8. Create a new OWA mailbox policy. In this example the policy is called ** OWAOnSendAddinAllUserPolicy **, but you can give the policy its own name .
    New-OWAMailboxPolicy OWAOnSendAddinAllUserPolicy
  9. Enable the On send functionality for this policy. Get-OWAMailboxPolicy OWAOnSendAddinAllUserPolicy | Set-OWAMailboxPolicy -OnSendAddinsEnabled:$true -OutlookBetaToggleEnabled $false

    If you disable the toggle to stop people enabling the new OWA, anyone who has already switched the toggle to on won’t be able to revert to the older interface because the toggle disappears.
  10. Apply the policy for all personal mailboxes:
    Get-User -Filter {RecipientTypeDetails -eq 'UserMailbox'} -ResultSize Unlimited | Set-CASMailbox -OwaMailboxPolicy OWAOnSendAddinAllUserPolicy
    The OnSend functionality is now enabled for all personal mailboxes. It may take some time for this adjustment to take effect through Exchange.

    This functionality is currently only available for personal mailboxes. Microsoft does not yet offer the OnSend functionality for shared mailboxes.

OPTIONAL Turn off the monitoring panel

Follow the steps below to deactivate OnSend functionality via Powershell for a policy. In this example the policy is called OWAOnSendAddinTestUserPolicy.

This setting is not required, but explains how to undo the setting above.

  1. Open Powershell with admin rights.
  2. Run the following command: Set-ExecutionPolicy RemoteSigned.
  3. Type Yes at the prompt.
  4. Execute the following command: $UserCredential = Get-Credential.
  5. Log in with an account that has admin access to exchange.
  6. Run the following command: $Session = New-PSSession -ConfigurationName Microsoft.Exchange -ConnectionUri https://outlook.office365.com/powershell-liveid/ -Credential $UserCredential -Authentication Basic -AllowRedirection.
  7. Run the following command: Import-PSSession $Session.
  8. Turn off the On send functionality for this policy. Get-OWAMailboxPolicy OWAOnSendAddinTestUserPolicy | Set-OWAMailboxPolicy -OnSendAddinsEnabled: $false.
    The OnSend functionality is now disabled. It may take some time for this adjustment to take effect through Exchange.

Turn on the control panel for new users

The OwaMailboxPolicy can only apply on existing users. This can give extra work when new employees join your organisation. They don’t get the OwaMailboxPolicy automatically and can’t make optimal use of the ZIVVER OWA plugin. A PowerShell script can be used to automatically apply the policy. This script can run in by a scheduled task.

Preparations

The PowerShell script connects to Exchange. To be able to make this connection, the credentials should be saved in a secure way. Fill in the following variables in the script below:

  • $UserPath: The path where you want to save the username, including the filename. Example: C:\Users\j.jansen\Documents\USER.txt
  • $PasswordPath: The path where you want to save the (encrypted) password, including the filename. Example: C:\Users\j.jansen\Documents\SECRET.txt

    #Set-up de credential files
    #Path to write the username file
    $UserPath = ""
    #Path to write the password file
    $PasswordPath = ""
    
    #Write the credentials
    $Credentials = Get-Credential
    $Credentials.UserName | Out-File $UserPath
    $Credentials.Password | ConvertFrom-SecureString | Out-File $PasswordPath
    

Save the script and run it. The credentials are saved (encrypted).

Run the script as the same user that will run the scheduled task. This prevents authorization issues with accessing the credential files.

PowerShell script

The PowerShell script below searches for all UserMailboxes that are created the past x days. Then the OwaMailboxPolicy is applied to these UserMailboxes. This script can be executed daily by means of a scheduled task, so that new users are automatically assigned the correct OwaMailboxPolicy. Fill in the following variables in the script:

  • $UserPath: The path where you saved the username, including the filename. Example: C:\Users\j.jansen\Documents\USER.txt
  • $PasswordPath: The path where you saved the (encrypted) password, including the filename. Example: C:\Users\j.jansen\Documents\SECRET.txt
  • $DaysToLookBack: The number of days to look back. For example, fill in ‘1’ to find all users that are created the last 24 hours.
  • $ExchangeURL: https://outlook.office365.com/powershell-liveid/
  • $OwaMailboxPolicyName: The name of the OwaMailboxPolicy you want to apply for the users. Example: OWAOnSendAddinAllUserPolicy

    #Fill in the variables to use in your environment
    #Path to the username file
    $UserPath = ""
    #Path to the password file
    $PasswordPath = ""
    #The number of days to look back (1 for yesterday)
    $DaysToLookBack =
    #The URL to Exchange Online
    $ExchangeURL = "https://outlook.office365.com/powershell-liveid/"
    #The name of the OwaMailboxPolicy that contains the settings required for the ZIVVER OWA plugin
    $OwaMailboxPolicyName = ""
    
    # Set up the credential variables
    $Username = Get-Content $UserPath
    $Password = Get-Content $PasswordPath | ConvertTo-SecureString
    $LoginCredentials = New-Object -TypeName System.Management.Automation.PSCredential -ArgumentList $Username,$Password
    # Create session to Exchange
    $Session = New-PSSession -ConfigurationName Microsoft.Exchange -ConnectionUri $ExchangeURL -Credential $LoginCredentials -Authentication Basic -AllowRedirection
    #Start the session
    Import-PSSession $Session
    # Get all users of type UserMailbox that are created in the last $DaysToLookBack days and set the OwaMailboxPolicy
    Get-User -Filter {RecipientTypeDetails -eq 'UserMailbox'} -ResultSize Unlimited | Where-Object {$_.WhenCreated -ge ((Get-Date).AddDays(-$DaysToLookBack))}| Set-CASMailbox -OwaMailboxPolicy $OwaMailboxPolicyName
    Remove-PSSession $Session
    

Save the script as a .ps1 file. Example: C:\Users\j.jansen\Documents\Apply_OwaMailboxPolicy.ps1

Set up scheduled task

The PowerShell script should be run daily. A scheduled task can be set for this. Follow the steps below to create a scheduled task in the Windows Task Scheduler:

  1. Open Task Scheduler.
  2. Choose Create Basic Task…
  3. Fill in the Name:. Example Apply OwaMailboxPolicy.
  4. Optionally fill in a Description:.
  5. Click Next >.
  6. Choose a trigger, for example Daily to run the task every day.
  7. Click Next >.
  8. Fill in a start date and time.
  9. Optionally fill in a recur period. For example every 1 days.
  10. Click Next >.
  11. Choose Start a program.
  12. Click **Next > **
  13. Fill in powershell.exe for Program/script.
  14. Fill Add arguments (optional): with: -ExecutionPolicy Bypass . Example -ExecutionPolicy Bypass C:\Users\j.jansen\Documents\Apply_OwaMailboxPolicy.ps1
  15. Click Next >.
  16. Check Open the Properties dialog for this taks when I click Finish.
  17. Click Finish.
    A new window opens.
  18. Select Run wether user is logged in or not.
  19. Click OK.
  20. Enter the password for the user that will run the task.
  21. Click OK
    The task is successfully created.

Check the installation

Check the side panel

  1. Click New to create a new message.
  2. Set up a message as usual.
  3. Click the ZIVVER icon in the bottom of the message window. The ZIVVER side panel opens on the right side.
  4. Is the OWA add-in not visible to the user?
    1. Go to Settings.
    2. Click Manage Add-ins.
    3. Go to Admin-managed.
    4. Click Add to activate the plug-in.
  5. Click the ZIVVER icon in the bottom right corner.
  6. The OWA plug-in opens in the side panel.
    If the side panel opens on the right, the side panel works well.

The OWA plug-in is not installed properly if the side panel does not appear! Check the steps from the previous chapters.

Check the OnSend functionality

  1. Click New to create a new message.
  2. Set up a message as usual.
  3. Click the ZIVVER icon in the bottom right corner.
    The ZIVVER side panel opens on the right side.
  4. Turn on Secure mail.
  5. Click Recipient verification.
    A new screen listing all recipients opens.
  6. Complete the recipient verification where necessary.
    Learn more about Recipient verification
  7. Click Apply.
  8. Click Send to send the message.
    If the ZIVVER screen appears, the OnSend functionality is working.

The OWA plug-in is not installed properly if you do not see OnSend functionality of ZIVVER after sending! Check the steps from the previous chapters.


Removing the Installation

Exchange admin center

Follow the steps below to uninstall the OWA add-in from the Exchange admin center:

  1. Log in to the Exchange Admin Center.
  2. Click Admin Centers.
  3. Click Exchange.
    You are now in the Exchange management center.
  4. Click organization.
  5. Click add-ins.
    You will now see an overview of all add-ins that are available for your organization.
  6. Select ZIVVER and click the trash can icon.
  7. Click Yes.
    The OWA add-in has now been removed.

Powershell

Follow the steps below to uninstall the OWA add-in from Powershell:

  1. Open Powershell.
  2. Log in to Exchange.
  3. Use the following command to find out which AppID represents the ZIVVER OWA add-in within your organization:
    Get-App -OrganizationApp | fl DisplayName, AppID
  4. Use the following command to delete the ZIVVER OWA add-in:
    Remove-App -OrganizationApp -Identity
    The OWA add-in has now been removed.

Was this article helpful?

thumb_up thumb_down