Office 365: How to scope impersonation when migrating to and from Exchange Online

When you’re migrating to or from a Microsoft Exchange system, using an awesome tool like the BitTitan MigrationWiz, that leverages the Exchange Web Services (EWS) for the migration, you have 2 main options for administrator access to the mailboxes you’re migrating to and/or from: Impersonation and Delegation.

The best option depends on if the Exchange server is the online version (Office 365 multi tenant) or on premises. For Exchange on premises you should use delegation and for Exchange Online you should use impersonation. Why? Because you can’t create throttling policies in Exchange Online and impersonation is much less subject to throttling, when compared with delegation.

It’s important to understand that impersonation will also be subject to throttling, just not as much as delegation. When you’re migrating with delegation, all actions are done on behalf of the admin account, as opposed to when you’re migrating with impersonation, where actions are made on behalf of the account that is being migrated and impersonated.

Now that we can all agree that impersonation is the best authentication method for Exchange multi tenant systems (by the way this also applies to hosted Exchange systems outside of Office 365, but setting up impersonation on those systems might be somethings Hosters won’t do, unless they scope it, which they usually don’t), lets discuss the topic of this post: How can you scope impersonation? What exactly does that mean? And when will this be useful?

The answer for the first question is that you can scope impersonation by using management scopes and management role assignments.

As for the second question, scoping the impersonation rights means basically that the admin account will only be able to impersonate the accounts you define within that scope filter.

Finally the third question: this is useful when, for security reasons, you (or someone from the security team of the source or destination tenant) don’t want the admin account, that will perform the migration, to have access to impersonate all users in the tenant. This is a very common scenario in mergers, acquisitions and divestitures, where the admin user doesn’t need access to users that are not part of the migration.

Now lets translate all of this into a step by step guide of what you need to do, in order to scope impersonation in your Office 365 tenant.

Step 1: Create a distribution group

There are many different ways to apply a filter into a scope, and limit a management role assignment such as Application Impersonation, to a specific scope. I will teach you a simple way: via group membership.

You can create the group via the 365 management console or via the PowerShell. I recommend that you create a simple @tenantname.onmicrosoft.com group as shown below (apologies, my current Office 365 tenant is in Portuguese, but I guess you can all recognize and understand the UI 🙂 ):

Group1

TIP: If you create this group just for the purpose of scoping impersonation, I recommend that you hide the group from the Global address list.

Now that the group is created, lets retrieve its DistinguishedName property:

Get-DistributionGroup -Identity AllowImpersonationDistributionGroup |fl name, dist*

group2

Note: In the command above use your own Distribution group name, as you created it, or just run the Get-DistributionGroup without specifying the identity, and grab the DistinguishedName from the correct group (all will be listed).

Step 2: Create a Management Scope

Create a new management scope, use the “RecipientRestrictionFilter” parameter and the “MemberOfGroup” filter:

New-ManagementScope RestrictedMigrationScope -RecipientRestrictionFilter {MemberOfGroup -eq ‘CN=AllowImpersonationDistributionGroup,OU=tenantname.onmicrosoft.com,OU=Microsoft Exchange Hosted Organizations,DC=EU
RP193A002,DC=PROD,DC=OUTLOOK,DC=COM’}

group3

Note: To run the command above you might need to enable the Organization customization in your Office 365 tenant.

Step 3: Create the Management Role Assignment

Now that we have the scope created the last step is to create the management role assignment and associate it with the admin migration account:

New-ManagementRoleAssignment -Name:MyMigration -Role:ApplicationImpersonation -User:user10@
myexchlab.com -CustomRecipientWriteScope:RestrictedMigrationScope

group4.JPG

Note: In the command above use the scope name and the admin account that you are using for the migration. For my migration the admin is user10@myexchlab.com

And that is it, job done. Lets do some testing.

Below you can see users 1 to 5, that I will be migrating, and user10 that I will use as an admin.

group5

Now looking at the group membership you can see that only user1, user3 and user5 are withing the scope, which means that user10 won’t be able to impersonate users 2 and 4.

group6

Finally the result in MigrationWiz, in a project configured to use impersonation and with user10 as the source admin.

group7

As you can see above, users 2 and 4 failed, and here’s the detailed error.

group8

Bingo… MigrationWiz failed to impersonate at the source. Of course now that you read this that error will never happen to you!! 🙂

Happy migrations and as usual if you have any questions let me know.

 

Advertisements

Office 365: Script to export to CSV mailboxes without the onmicrosoft.com smtp address

Just recently and when helping drive a Google Suite to Office 365 e-mail migration, I was faced with a problem that affected my mail routing capabilities between the 2 systems: Not all mailboxes in Office 365 had the @tenantid.onmicrosoft.com domain.

Now that can be a problem, specifically because in many coexistence scenarios (including the one I mentioned above), that “tenant.onmicrosoft.com” or the “tenant.mail.onmicrosoft.com” address is used as the forwarding address on the e-mail system coexisting with Office 365.

Here are a couple of articles describing cases where the service or mail routing domain were missing:

“Target mailbox doesn’t have an SMTP proxy matching ‘.mail.onmicrosoft.com'” error when you try to move mailboxes to Exchange Online

User@Domain.onmicrosoft.com disappeared

The main problem in this cases is that you can find that some users don’t have that address, as an additional smtp address, the hard way, which basically is getting an NDR on the source system when it tries to forward that email to Office 365. So to be on the safe side, and because this happened to me a few times, I decided to create a script that identifies all users that don’t have an address from a specific email domain.

Some bullet point instructions for the script:

  • you can download the script here
  • The file you downloaded contains 2 scripts: Export-UsersNoOnMicrosoftAddress.ps1 and Log_Functions.ps1. Copy both into the same folder
  • Open a PowerShell window and run .\Export-UsersNoOnMicrosoftAddress.ps1
  • The script will prompt you to enter your Office 365 credentials
  • The script will prompt you for an email domain (i.e tenant.onmicrosoft.com)
  • All users that don’t have an address with that email domain will be exported to a file called UsersNoOnmicrosoftAddress.csv located in the same folder
  • A log file called ExportUsersOnmicrosoft.log is also created in the same folder, where you can check for any errors after running the script

See screenshot below with the output of the script on the console:

UsersNoOnmicrosoft1

Of course that, if you look at the code, you will easily realize that the script can export users that don’t have an address from any domain you chose. That being said use it as you see fit. To me it helped me a lot on detecting the users with the problem described above.

Just a quick note before I finish this post: there are 2 reasons for this script not to fix the problem, adding those addresses:

  1. AD Connect: blocks you from adding the addresses directly in 365, meaning you will need to resolve the problem on premises and force a sync of the new addresses to 365
  2. Email address policies: it’s ultimately the best way of resolving email address problems in bulk, so that’s the route you so use

As always if you have any questions let me know. Enjoy.

Understanding the admin authentication options when using the EWS API in your migration project

One of the major concerns of the consultant or the project manager, on a migration project, is how long will it take to migrate the mailboxes, and what timelines can they define as reasonable for the migration (or the migration batch) to be finished.

Having that in mind, the conversation around it needs to focus on two major factors:

  • What authentication method should we use
  • How can we minimize (or avoid) throttling

So let’s start by talking about the authentication method.

What are the available authentication methods?

Bittitan MigrationWiz, which of course leverages the Exchange Web Services (EWS) as the API to migrate to and from Exchange 2010+, allows you to use two type of admin authentication methods:

  • Delegation
  • Impersonation

Note: MigrationWiz also allows non admin authentication methods, which we will not discuss on this blog post.

What is delegation and how do I configure it?

Delegation is the authentication method in which the entire migration will be done from the calling account (admin account), that needs to have full access to all of the mailboxes that are being migrated. The requirements for delegation are:

  • admin account needs to be mailbox enabled
  • full access is required to all of the mailboxes being migrated (explicit permissions)
  • a throttling policy should be created and associated with the admin account

In the Bittitan community website you will be able to find instructions on how to configure delegation on the source and target Exchange systems. You can also find there how to create the throttling policy.

By default the MigrationWiz project will try and use delegation, so there’s no other change needed.

What is impersonation and how do I configure it?

Impersonation is the authentication method in which the migration will be done on behalf of the user account, that is being impersonated by the calling account (admin account). For this to happen the admin account needs to be granted rights to impersonate the user accounts being migrated. the requirements for impersonation are:

  • the admin account does not need a mailbox
  • impersonation rights need to be granted to the admin account, over all of the users being migrated
  • a throttling policy is not required but highly recommended

In the Bittitan community website, you will also find instructions on how to configure impersonation on the source and target Exchange systems. The instructions to create the throttling policy are the same you can find on the section above.

The default behavior from MigrationWiz is not to use impersonation, so please make sure you follow the MigrationWiz steps of the article above, to configure impersonation at the project level.

Should I use Delegation or Impersonation?

Now that I described what is Delegation and what is Impersonation, let’s discuss which one should you use for each scenario.

In my professional opinion, that I will detail below and explain why, this is what you should do:

  • If the Exchange system is Exchange Online (Office 365) use Impersonation
  • If the Exchange system is Hosted Exchange (online but not in Office 365) use Delegation
  • If the Exchange system is on premises use Delegation

So now let’s break it down per system.

Exchange Online (Office 365)

The main reason that you should use Impersonation when authenticating against Exchange Online is simple: You cannot create a throttling policy in Office 365 and impersonation is less subject to throttling than delegation. 

I don’t think I need to explain why you can’t create a throttling policy in Office 365, but why is impersonation less subject to throttling? Well the explanation is logic: The subscriptions will be charged against the throttling budget of the target mailbox and not the calling account (admin account), which in other words means that the admin account is doing the migration impersonating each target account and the throttling is being charged to the target accounts, making the limits much more flexible and the migration faster.

Another good thing about Exchange Online is that when you set the impersonation rights, you are of course setting them within the boundaries of your tenant, which is not necessarily true for hosted Exchange systems, as you’ll see below.

Hosted Exchange (not in Office 365)

Now when we look at a hosted Exchange and what admin authentication methods we can have, the main thing you need to keep in mind is that, we will have what the Hoster is willing to configure. And what might that be? Short answer will be Delegation.

Don’t get me wrong, if you manage to get a Hoster (or if you are part of a Hoster Exchange management team and you’re also driving the migration) to either create a throttling policy or configure impersonation associated with a management scope, then what I recommend is:

  1. If you can create a throttling policy then use Delegation and associate that throttling policy to the admin account
  2. If you can’t create a throttling policy but you can enable impersonation with a scope (explanation below) than enable and use Impersonation
  3. If none of the above is possible, then use Delegation

Note: when you set impersonation, if you don’t use a management scope, that will allow the admin account to impersonate any account on that hosted Exchange. That might (and should) be considered a security breach by the Hoster and therefore not possible to configure. Although possible, many Hosters might not be willing to configure impersonation with a management scope, or configure impersonation at all.

On Premises Exchange

Finally when the system is on premises Exchange, you will be able to do all necessary tasks, so why use delegation?

To be able to reach maximum speeds you will still have to create a throttling policy (if you can), so between impersonating and using delegation I do think that delegation and a throttling policy is the best way to go.

Remember when I said “Impersonation is the authentication method in which the migration will be done on behalf of the user account, that is being impersonated by the calling account (admin account).”? Well that’s not 100% true in all cases. Depending on your Exchange version, the subscription might be charged to the calling account, which in essence makes impersonation as effective as delegation in terms of throttling. See the table below:

Exchange version EWSMaxSubscriptions throttling budget accounting
Exchange Online Charged against the target mailbox.
Exchange 2013 Charged against the target mailbox.
Exchange 2010 SP3 Charged against the target mailbox.
Exchange 2010 SP2 Charged against the calling account. Starting with Exchange 2010 SP2 RU4, the budget is charged against the target mailbox.
Exchange 2010 SP1 Charged against the calling account.
Exchange 2010 Charged against the calling account.

Source: EWS throttling in Exchange

From the above table you will see that if you have an Exchange system older than Exchange 2010 SP2 RU4, impersonation and delegation will have the same impact from the throttling perspective. We know that Exchange Online does have a version newer than the one just mentioned, but that is not necessarily true for Hosted Exchange or Exchange On Premises, so have that in mind when planning the authentication methods.

So let me outline the reasons that should make you choose delegation when migrating from an on premises Exchange:

  • the speed of the migration will be highly dependent on the throttling policy, that you can and should create, as well as monitor the Exchange performance during the migration
  • Implementing delegation is easier, specially in cases where you want the admin account to just have rights over a subset of the mailboxes. It’s much easier to just give full access to some mailboxes when compared to give impersonation rights to just some users
  • the way throttling reacts when using impersonation and delegation is different. In my opinion when using impersonation you’re more likely face ErrorServerBusy errors (if you go over the limit of concurrent migrations) and that causes normally more migrations to fail. When using delegation the failures are more likely to happen on the accounts that caused the admin account to over the maximum subscriptions allowed

I know that the explanation above might be a little confusing, specially the last bullet point, but I do highly recommend that you read the EWS throttling in Exchange article, and if you have another idea on what method to use feel free to share it.

I do think that impersonation makes sense only on those scenarios where you cannot fully implement proper delegation, with throttling policies and processes defined to monitor the Exchange server resources during the migration window.

Some useful articles around this subject

The importance of EWS impersonation while using an application account: you will can read the author outline how impersonation is better from an application perspective, and delegation is more oriented towards user access. I also mentions that user access can be controlled and revoked by the end user, which can be true. But on a migration project MigrationWiz will use user access to get into the mailbox and move the data to a destination mailbox, which is exactly what delegation provides you. He also outlines how less complex and global the impersonation setting can be, which is true, but on a project when you only need to migrate a subset of the mailboxes, and where you don’t want to give global access, impersonation will be significantly more complex. In essence this article is a good read that outlines the positives of impersonation and why it’s a good option for application level access and not user level access.

Impersonation and EWS in Exchange: This is an excellent article and a must read, that details how application level impersonation works in Exchange.

So what is the bottom line? At the end of the day it’s still your decision of whether to use delegation or impersonation. I’d say that for some scenarios like Office 365, the decision is a no-brainer (impersonation of course), and in some other scenarios it will depend on what can you configure and what is the simpler and more effective configuration.

Like I stated above I am always more inclined to decide for delegation against Exchange on premises and hosted Exchange, and impersonation against Office 365.

As always I hope this article is helpful, and feel free to share your thoughts.