Prepare for directory synchronization to Office 365

The benefits to hybrid identity and directory synchronization your organization include:

  • Reducing the administrative programs in your organization
  • Optionally enabling single sign-on scenario
  • Automating account changes in Office 365

For more information about the advantages of using directory synchronization, see Directory synchronization roadmap and Hybrid identity for Office 365.

However, directory synchronization requires planning and preparation to ensure that your Active Directory Domain Services (AD DS) synchronizes to the Azure Active Directory (Azure AD) tenant of your Office 365 subscription with a minimum of errors.

Follow these steps in order for the best results.

1. Directory cleanup tasks

Before you synchronize your AD DS to your Azure AD tenant, you need to clean up your AD DS.

Important

If you don't perform AD DS cleanup before you synchronize, there can be a significant negative effect on the deployment process. It might take days, or even weeks, to go through the cycle of directory synchronization, identifying errors, and re-synchronization.

In your AD DS, complete the following clean-up tasks for each user account that will be assigned an Office 365 license:

  1. Ensure a valid and unique email address in the proxyAddresses attribute.

  2. Remove any duplicate values in the proxyAddresses attribute.

  3. If possible, ensure a valid and unique value for the userPrincipalName attribute in the user's user object. For the best synchronization experience, ensure that the AD DS UPN matches the Azure AD UPN. If a user does not have a value for the userPrincipalName attribute, then the user object must contain a valid and unique value for the sAMAccountName attribute. Remove any duplicate values in the userPrincipalName attribute.

  4. For optimal use of the global address list (GAL), ensure the information in the following attributes of the AD DS user account is correct:

  • givenName
  • surname
  • displayName
  • Job Title
  • Department
  • Office
  • Office Phone
  • Mobile Phone
  • Fax Number
  • Street Address
  • City
  • State or Province
  • Zip or Postal Code
  • Country or Region

2. Directory object and attribute preparation

Successful directory synchronization between your AD DS and Office 365 requires that your AD DS attributes are properly prepared. For example, you need to ensure that specific characters aren't used in certain attributes that are synchronized with the Office 365 environment. Unexpected characters do not cause directory synchronization to fail but might return a warning. Invalid characters will cause directory synchronization to fail.

Directory synchronization will also fail if some of your AD DS users have one or more duplicate attributes. Each user must have unique attributes.

The attributes that you need to prepare are listed here:

  • displayName

    • If the attribute exists in the user object, it will be synchronized with Office 365.
    • If this attribute exists in the user object, there must be a value for it. That is, the attribute must not be blank.
    • Maximum number of characters: 256
  • givenName

    • If the attribute exists in the user object, it will be synchronized with Office 365, but Office 365 does not require or use it.
    • Maximum number of characters: 64
  • mail

    • The attribute value must be unique within the directory.

      Note

      If there are duplicate values, the first user with the value is synchronized. Subsequent users will not appear in Office 365. You must modify either the value in Office 365 or modify both of the values in AD DS in order for both users to appear in Office 365.

  • mailNickname (Exchange alias)

    • The attribute value cannot begin with a period (.).
    • The attribute value must be unique within the directory.
  • proxyAddresses

    • Multiple-value attribute

    • Maximum number of characters per value: 256

    • The attribute value must not contain a space.

    • The attribute value must be unique within the directory.

    • Invalid characters: < > ( ) ; , [ ] "

      Note that the invalid characters apply to the characters following the type delimiter and ":", such that SMTP:User@contso.com is allowed, but SMTP:user:M@contoso.com is not.

      Important

      All Simple Mail Transport Protocol (SMTP) addresses should comply with email messaging standards. If duplicate or unwanted addresses exist, see the Help topic Removing duplicate and unwanted proxy addresses in Exchange.

  • sAMAccountName

    • Maximum number of characters: 20
    • The attribute value must be unique within the directory.
    • Invalid characters: [ \ " | , / : < > + = ; ? * ]
    • If a user has an invalid sAMAccountName attribute but has a valid userPrincipalName attribute, the user account is created in Office 365.
    • If both sAMAccountName and userPrincipalName are invalid, the AD DS userPrincipalName attribute must be updated.
  • sn (surname)

    • If the attribute exists in the user object, it will be synchronized with Office 365, but Office 365 does not require or use it.
  • targetAddress

    It's required that the targetAddress attribute (for example, SMTP:tom@contoso.com) that's populated for the user must appear in the Office 365 GAL. In third-party messaging migration scenarios, this would require the Office 365 schema extension for the AD DS. The Office 365 schema extension would also add other useful attributes to manage Office 365 objects that are populated by using a directory synchronization tool from AD DS. For example, the msExchHideFromAddressLists attribute to manage hidden mailboxes or distribution groups would be added.

    • Maximum number of characters: 256
    • The attribute value must not contain a space.
    • The attribute value must be unique within the directory.
    • Invalid characters: \ < > ( ) ; , [ ] "
    • All Simple Mail Transport Protocol (SMTP) addresses should comply with email messaging standards.
  • userPrincipalName

    • The userPrincipalName attribute must be in the Internet-style sign-in format where the user name is followed by the at sign (@) and a domain name: for example, user@contoso.com. All Simple Mail Transport Protocol (SMTP) addresses should comply with email messaging standards.
    • The maximum number of characters for the userPrincipalName attribute is 113. A specific number of characters are permitted before and after the at sign (@), as follows:
    • Maximum number of characters for the username that is in front of the at sign (@): 64
    • Maximum number of characters for the domain name following the at sign (@): 48
    • Invalid characters: \ % & * + / = ? { } | < > ( ) ; : , [ ] "
    • An umlaut is also an invalid character.
    • The @ character is required in each userPrincipalName value.
    • The @ character cannot be the first character in each userPrincipalName value.
    • The username cannot end with a period (.), an ampersand (&), a space, or an at sign (@).
    • The username cannot contain any spaces.
    • Routable domains must be used; for example, local or internal domains cannot be used.
    • Unicode is converted to underscore characters.
    • userPrincipalName cannot contain any duplicate values in the directory.

See Prepare directory attributes with the IdFix tool to use the IdFIx tool to identify errors in the attributes of your AD DS.

2. Prepare the userPrincipalName attribute

Active Directory is designed to allow the end users in your organization to sign in to your directory by using either sAMAccountName or userPrincipalName. Similarly, end users can sign in to Office 365 by using the user principal name (UPN) of their work or school account. Directory synchronization attempts to create new users in Azure Active Directory by using the same UPN that's in your AD SD. The UPN is formatted like an email address.

In Office 365, the UPN is the default attribute that's used to generate the email address. It's easy to get userPrincipalName (in AD DS and in Azure AD) and the primary email address in proxyAddresses set to different values. When they are set to different values, there can be confusion for administrators and end users.

It's best to align these attributes to reduce confusion. To meet the requirements of single sign-on with Active Directory Federation Services (AD FS) 2.0, you need to ensure that the UPNs in Azure Active Directory and your AD DS match and are using a valid domain namespace.

4. Add an alternative UPN suffix to AD DS

You may need to add an alternative UPN suffix to associate the user's corporate credentials with the Office 365 environment. A UPN suffix is the part of a UPN to the right of the @ character. UPNs that are used for single sign-on can contain letters, numbers, periods, dashes, and underscores, but no other types of characters.

For more information on how to add an alternative UPN suffix to Active Directory, see Prepare for directory synchronization.

5. Match the AD DS UPN with the Office 365 UPN

If you've already set up directory synchronization, the user's UPN for Office 365 may not match the user's AD DS UPN that's defined in your AD DS. This can occur when a user was assigned a license before the domain was verified. To fix this, use PowerShell to fix duplicate UPN to update the user's UPN to ensure that the Office 365 UPN matches the corporate user name and domain. If you are updating the UPN in the AD DS and would like it to synchronize with the Azure Active Directory identity, you need to remove the user's license in Office 365 prior to making the changes in AD DS.

Also see How to prepare a non-routable domain (such as .local domain) for directory synchronization.

Next steps

See Prepare directory attributes with the IdFix tool to help you correct errors in the attributes of your AD DS prior to directory synchronization.

If you have corrected all the attribute errors identified with the IdFix tool and have done steps 1 through 5 above, see Set up directory synchronization.