Import distribution groups to Office 365: Exchange Online with PowerShell

Today we faced an issue where a client needed to migrate their GroupWise distribution groups to Office 365. Since there is no easy way doing this we developed a PowerShell script to automate this proces. Well, actually it are two scripts.

The scripts are divided in one, creating the distribution groups and part two is adding the members to the newly created groups. First we have to gather the input for creating the distribution groups in Office 365. For this I only used the required attributes for creating a distribution group.

$import = Import-Csv -Path “C:\temp\Create-DG.csv” -Delimiter “;”
foreach ($item in $import) {
New-DistributionGroup -Name $item.Name -DisplayName $item.DisplayName -PrimarySmtpAddress $item.PrimairyEmailAddress -Type $item.Type
Export-Csv -Path “C:\temp\New-DistributionGroup_LogFile_$(get-date -Format ddMMyyyy).csv”
}

Once the distribution groups are created we can head on adding the members to them using the PowerShell script below.

$import = Import-Csv -Path “C:\temp\Add-DGMembers.csv” -Delimiter “;”
foreach ($item in $import) {
Add-DistributionGroupMember -Identity $item.GroupName -Member $item.UPN -Verbose
Out-File -FilePath “C:\temp\Add-DGMembers_LogFile_$(get-date -Format ddMMyyyy).log”
}

As we can see both the scripts import a .csv file containing the content. The .csv files and the PowerShell scripts can be downloaded below.

DOWNLOAD HERE

Please note that the distribution groups can be either created on-premises in Active Directory and then synced to Windows Azure Active Directory (Office 365) or either directly created in Office 365 with the help of remote PowerShell. Based on your infrastructure and migration scenario it can differ which is the best way to go. Functionally there will be no difference for Exchange Online. However in some hybrid scenarios it can be best to create the distribution groups on-premises and sync them to Office 36 with the help of Azure Active Directory Sync (DirSync).

Filter OU’s to be synchronized to Office 365 with Windows Azure Active Directory Sync

When performing Office 365 deployments for most companies DirSync comes in the picture. Or as Microsoft prefers to call it, Windows Azure Active Directory Sync. Since most of the IT environments become polluted when time flies by most of my client’s prefer to perform a limited synchronization with DirSync.

As said earlier, most IT environments become polluted by time. As Active Directory Users & Computers is one of the most heavily administered you can imagine how much dirt sneaks in which makes it very interesting for businesses. Therefore Microsoft has a way to perform a limited DirSync based on OU (Organizational Unit) hierarchy and selection. For this we have to digg our way into ForeFront Identity Manager.

For this we have to open the FIM 2010 console by navigating to the following directory “C:\Program Files\Windows Azure Active Directory Sync\SYNCBUS\Synchronization Service\UIShell”.

Here you will find a executable called miisclient.exe. Run this application with “Run as administrator” priviliges. Make sure the account which initiates the request is member of the “Domain Admins” and the “Enterpirse Admins” security groups within your ADS forest. It’s also required to be a member of the local security group “FIMSyncAdmins” on the DirSync server.

Please refer to the image illustrated here for the instructions listed below.
FIM_console_instructions1
1. Click on “Management Agents” in the top ribbon.
2. Right click on the “Active Directory Connector” management agent and select “Properties”.
3. Click on “Configure Directory Partitions” on the left hand side of the menu.
4. Click on “Containers” and fill in the credentials of the local ADS service account.
5. After filling in the credentials a windows opens with the AD forest hierarchy. Here you can select the required Organizational Unit’s. Please refer to the image illustrated below.
FIM_console_instructions2

After selecting the prefered OU’s select OK and save the configuration. Next is waiting for DirSync to kick of a fresh Delta Sync. If you can’t wait then fire up PowerShell on the DirSync server and run the following two cmd-lets:

1. Import-Module DirSync
2. Start-OnlineCoexistenceSync -FullSync

Hope this helps fellow IT Professionals deploying succesfull Office 365 product. And obviously it is best to configure this filtering before Windows Azure Directory Sync synchronizes for the first time.

Change explicit User Principal Names to match Office 365 domain suffix

Most Enterprise Office 365 clients will use Active Directory Federation Services and Windows Azure Active Directory Sync, also known as DirSync for Single Sign-On functionality with Office 365.

Standard AD FS will use the on-premises UPN to access services in Office 365. Therefore Microsoft advises to make sure User Principal Name suffixes and e-mail adress suffixes match to make life simpler. Most ADS domains still use an internal routable domainname for instance contoso.local. However when implementing AD FS with Office 365 it permitted to have an “internet routable” domain suffix for instance contoso.com.

The best solution for this before implementing and running a DirSync is to create a new User Principal Name suffix to match your Office 365 domain suffix. This can be done by adding a new UPN suffix by going to:

  1. Open Active Directory Domains and Trusts
    2. Right click on the top level of the tree in the left pane and select properties
    3. Add the new internet routable UPN suffix e.i. contoso.com

Next step is to change the explicit User Principal Names for all the designated user objects in Active Directory which you plan to synchronize to Office 365. The easiest way to do this is with the help of allmighty PowerShell.

I wrote this easy one-liner which allows you to target a specific OU in Active Directory. Don’t forget to use the Active Directory Module for PowerShell.

Get-ADUser -Filter * -SearchBase ‘OU=Users,DC=fabrikam,DC=local’ -Properties userPrincipalName | foreach { Set-ADUser $_ -UserPrincipalName “$($_.samaccountname)@contoso.com”}

After succesfully running the cmd-lets you will notice the new UPN suffix is configured for the targeted user objects in ADS.