Setting up Retain with Office 365

Prerequisites

1. Check that autodiscover is enabled for your domain but running the O365, Outlook Autodiscover test with Microsoft's Remote Connectivity Analyzer
2. PowerShell 2.0 and Cmdlets installation links for Retain and Exchange configuration
3. Create DNS records at any DNS hosting provider for Office 365
4. Creating a DNS SRV record for Exchange / O365 to solve autodiscover errors

Create Two Unique User Accounts

O365 is a little different from On-Premise as it needs two users:

1. A user with Administrator rights for getting the user and group list via the sync365 script
2. A normal user with the Application Impersonation role to collect the messages via Retain which we will refer to as the Impersonation User

Administrator User
You may want to have a separate administrator user just for Retain to use for the sync365.ps1 powerscript.
Microsoft has a technical article on how to create an additional admin user.

Impersonation User
This is just like the normal Retain Impersonation User and is setup up as an ordinary default mailbox user in the Exchange Admin Center.

Create a Normal Exchange user (mailbox enabled) and make sure to give it Application Impersonation rights.

1. Log into the Office 365 admin center as the Administrator user.
2. Select Users/Active Users
3. Click the Plus sign to create a new user mailbox.
4. Fill in the appropriate information.
5. Give it a simple name like RetainWorker, and have it match the logon name.
6. Press Save.
7. Expect to reset the password every 6 months or you will see Invalid Password errors in the worker log. See this MS TechNote on setting a user's password to never expire

Adding Application Impersonation Role
Application Impersonation is not a default right for users so you will need to set up the permissions for that and assign them to a user.

In the Office 365 Admin Center choose Admin (near the bottom of the left navbar or from the dropdown menu at the top right) select Exchange to go to the ''Exchange admin center''.

1. Select Permissions from the left navbar, which should take you to ''admin roles'' by default
2. Click the Plus sign to create a new admin role.
3. Give it a name such as "Application Impersonation" or "Message Archive" and a description such as "Used by Retain to access messages".
4. Under Roles click the Plus sign to add a role.
5. Select the Display Name ApplicationImpersonation, click add->, then ok.
6. Under Members click the Plus sign to add a user.
7. Select the retain user, click add->, then ok.
8. Press Save.

Set Up the User/Group Synchronization Script

For Retain to authenticate users and access mailboxes for archiving, it needs to know what mailboxes are in Office365.  Microsoft does not allow direct access to their cloud, but we are allowed to use PowerShell to download the address book to gather that data. There are  scripts to do that both found under the Tools menu at the upper right of the Retain admin console.

In Retain 3.x: This script is found under tools/exchange/Office365 of the install package
In Retain 4.x: This scripts are found in the Retain web admin console under the Tools menu at the top right of the main page:  Tools | Plugins | Office 365 Archiving

The two scripts do the same thing: download the address book from Office365.

          PowerShell Sync Script 1.0 saves the username and password in plaintext in the script.

          PowerShell Sync Script 4.0 encrypts the password to a separate file.

This script needs to be modified for each system and requires an Administrator account user UPN and password. This script needs 3 items filled in:

1. The User Principal Name (UPN) of a user with Administrator rights.
2. The password of that user.
3. The path path to where the resulting exchangeuser.csv and exchangegroups.csv files will go should not include an ending backslash "\"; thus, it should look like this: 

Linux default:  /opt/beginfinite/retain/RetainServer/WEB-INF/cfg

Windows default:  [drive]:\Program Files\Beginfinite\Retain\RetainServer\WEB-INF\cfg

Note:

• In powershell, the backslashes ' \ ' need to be escaped by another backslash, so that you have two consecutive backslashes (e.g.,  ' \\ '.)
• If the path has spaces then the path needs to be quoted. For example, "C:\\Program Files\\Beginfinite\\Retain\\RetainServer\\WEB-INF\\cfg"
• TIP:  If the connection to O365 fails, the .csv files end up empty.  Once you have good files, back them up to another location in case of such a failure.

Automating sync365.ps1 to Run Every Night
To make sure that the user and group lists are fully up to date you will want to automate running sync365.ps1 with Task Scheduler.

Troubleshooting

• One of the more useful tools in this case is Microsoft's Remote Connectivity Analyzer
• Login as the admin user specified in the sync365.ps1 script
• You are looking for at least one good connection.