Difference between revisions of "Exchange Module Office365"

Latest revision as of 15:02, 26 May 2016

Office 365 is Microsoft's cloud solution. It moves all the hard stuff to Microsoft and all you have to do is add users and call them when there is a problem. Retain lets you make sure you have a copy of your data where they can't lose it.

[edit] O365_Setup

Setting up Retain with Office 365

O365: How Retain Authenticates Users

[edit] Exchange Module Office365 Basics

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

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

Note: These accounts are based in O365 only. This is important if you are running a hybrid with On-Premise Active Directory and O365.

[edit] Administrator User

You may want to have a separate administrator user just for Retain to use for the sync365.ps1 powerscript.

• This requires Global Administrator rights.

Microsoft has a technical article on how to create an additional admin user. [1]

[edit] 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 and make sure to give it Application Impersonation rights.

• Log into the Office 365 admin center as the Administrator user.

[edit] Creating a User for Retain

• Select Users/Active Users
• Click the Plus sign to create a new user mailbox.
  • Fill in the appropriate information.
  • Give it a simple name like RetainWorker, and have it match the logon name.
• Press Save.
• Use this MS technote to set the password to never expire [2]

[edit] Adding Application Impersonation rights

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. Microsoft has a technical article on how to configure the system [3]

• 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.
• Select Permissions from the left navbar, which should take you to admin roles by default
• Click the Plus sign to create a new admin role.
• Give it a name such as "Application Impersonation" or "Message Archive" and a description such as "Used by Retain to access messages".
• Under Roles click the Plus sign to add a role.
  • Select the Display Name ApplicationImpersonation, click add->, then ok.
• Under Members click the Plus sign to add a user.
  • Select the retain user, click add->, then ok.
• Press save.

[edit] sync365.ps1

This script is found under tools/exchange/Office365 and needs to be modified for each system.

It needs 3 things:

• The User Principal Name (UPN) of a user with Administrator rights.
• The Password of that user.
• The Path path to where the resulting exchangeuser.csv and exchangegroups.csv files will go, there is no need of a finale backslash. This needs to end up in the ...\RetainServer\WEB-INF\cfg directory.
  • NOTE: In powershell the backslashes '\' need to be escaped by another backslash '\\'. For example, C:\\Temp
  • NOTE: if the path has spaces then the path needs to be quoted. For example, "C:\\Program Files\\Beginfinite\\Retain\\RetainServer\\WEB-INF\\cfg"

This requires an Administrator account user UPN and password.

Automating the Office365 sync365.ps1 script

Using a Linux-based Retain server with Office365

[edit] Troubleshooting

One of the more useful tools in this case is Microsoft's troubleshooting tool: Microsoft Remote Connectivity Analyzer

Use the admin user specified in the sync365.ps1 script and the Impersonation user. You are looking for at least one good connection.

[edit] How Retain Authenticates against O365

1. Retain looks up the username from the csv file to get the full user information.
2. with the given credentials it does an autodiscover call, which is an SSL secured call with the username and password provided by the user.
3. if the O365 autodiscover is successful, the user has logged into Retain successfully

Users Unable to Log Into Retain for the First Time

[edit] Address Book Synchronization and How Retain Determines User Uniqueness

There is an issue in 3.5.0 with the address book synchronization. In 3.5.0 and earlier, Retain would key off of the object GUID to determine record uniqueness. This worked for a long time; however, lately there have been a few accounts where their user object GUIDs changed but their Exchange mailbox GUIDs remained the same. This resulted in duplicate mailboxes.

This behavior has been changed in Retain 3.5.1 and 4.0. Retain now keys off of the Exchange mailbox GUID in the exchangeuser.csv file located in the .../beginfinite/retain/RetainServer/WEB-INF/cfg directory.

[edit] Database entries for user mailboxes in Retain 3.5.0:

• Object GUID in t_appuid.f_auid
• Mailbox GUID in t_exchobj.f_uid
• Object GUID also in t_exchobj.f_value

Retain would store the object GUID in the t_appuid.f_auid and compare that value with the "GUID" cell in the exchangeuser.csv file to determine user uniqueness.

MS changed how things were done in O365 and the Object GUID would change resulting in duplicate user entries, but the Exchange GUID would stay stable. So we changed our code to deal with that change. Jiri bug: RET-1988 added to Retain 3.5.1. The duplicate users can be resolved with mergeDuplicateUsers.jsp

[edit] Database entries for user mailboxes in Retain 3.5.1 and later:

• Exchange GUID in t_appuid.f_auid
• Mailbox GUID in t_exchobj.f_uid
• Object GUID also in t_exchobj.f_value

Now, in Retain 3.5.1 and later, Retain stores the Exchange mailbox GUID in t_appuid.f_auid and compares that value with the "Exchange GUID" cell in the exchangeuser.csv to determine user uniqueness.

NOTE: t_exchobj.f_type tells us what type of data is stored in the t_exchobj.f_value field, whether it is the object GUID (which it should be) or the mailbox GUID.