Preparing user accounts prior to Office 365 & Okta integration Skip to main content
How satisfied are you with the Okta Help Center?
Thank you for your feedback!
How satisfied are you with the Okta Help Center?
Very Dissatisfied
Very satisfied
Enter content less than 200 characters.

Preparing user accounts prior to Office 365 & Okta integration

Sep 02, 2015 | by Thomas Hill in Office 365

Original Author: Simon Thorpe, Sr. Technical Marketing Manager, Okta

Okta is a fantastic solution for integrating your existing Microsoft Active Directory (AD) environment with Office 365. You can quickly synchronize users from your AD domains into Office 365 and enable federation for them. This means that users accessing Office 365 can use their existing Active Directory user names and passwords.

Before you can begin the process of migration, it is important to ensure your user accounts are configured appropriately in Active Directory. This article walks you through some advice for preparing accounts to ensure a successful integration of Okta and Office 365 with your existing Active Directory environment. There is also a useful accompanying article on the Microsoft TechNet network which discusses the tasks to prepare users in your Active Directory. Note the following information lacks certain details about authentication methods such as using certificates on smart cards. If you need information that is not clarified in the below, please contact your Okta technical representative.

Understanding your users

Before looking at the technical detail of the problem. It is worth making sure you understand how users in your environment currently authenticate today. In Active Directory there are two common methods for authenticating users to resources. The two common formats users will be familiar with when typing in their username and password are;




The first is the older pre-Windows 2000 format with the domain NetBios name (DOMAIN) followed by the users sAMAccountName (username). The second is the User Principle Name (UPN) which bears the same format as an email address. Users authenticating to Office 365 use the UPN only, so if your users are familiar with logging into their desktops and applications with DOMAIN\username, then you need to think through how to communicate to them the new method. Even when you have Desktop SSO enabled, users might navigate directly to and attempt to login. The Microsoft service is going to ask for their username so it can determine what identity provider is responsible for authenticating them.

Because the UPN looks like an email address, it makes a lot of sense to make it the same as their email address. It doesn't however have to be this way, but for most users it makes a lot of sense.



The above diagram is an example of an organization with two Active Directory forests. Users from all four domains need to be synchronized into Office 365. There are two scenarios for how this information can be brought from AD into Office 365.

  1. Use only Okta agents
  2. Use Okta agents with DirSync or FIM

Only Okta agents

If you plan on deploying Okta with Office 365 and use just Okta agents to bring data into the cloud, then you have a few choices on how to map users in Active Directory with users in Office 365. The Okta agent will copy user accounts into your Okta cloud directory. Your Okta directory then copies these users into Office 365. At each stage you make a decision on what attribute you will use to create the username in both Okta and in Office 365.

Using the above diagram, you will have four domains in Okta, and for each one you can choose the attribute to use to create the Okta account. Your choices are;

  • User Principal Name (UPN)
  • Email address
  • SAM Account Name
  • SAM Account Name + Configurable Suffix
  • Custom

Whatever selection you make, Okta requires that the username always be in the format of a UPN, in other words formatted as an email address, e.g. Note that if you select SAM Account Name, Okta will combine the SAMAccountName with the AD domain name. Okta will also import the AD accounts email address as an attribute of the Okta user.

This explains how the Okta username is created, now the next thing to understand is that Okta will next be creating the Office 365 account. Which if you remember, must be in the format of a UPN as well. The attribute used for the username in Office 365 can be one of many attributes on the Okta account. The drop down to choose which attribute is used can be found on the Single Sign-On settings tab for the Office 365 application. You need to ensure whatever attribute you set will actually result in a valid UPN. For Office 365 that UPN must be in the format of an email address, user@domain.tld and also it must have a suffix which matches a domain that has been registered with Office 365. The available attributes are;





So the suffix of the UPN needs to match the domain registered in Office 365. Below is a simple visual to explain.




You can see that the Okta AD Agent imports the user into Okta but uses the email attribute to create the user When the Office 365 app is assigned to the user, it is configured to use the Okta username and therefore creates a user in Office 365 called The domain is also configured in Office 365 to be responsible for email. With Okta, our user can now login to Office 365 using the username but his password is actually verified against his account in AD. Email for is also delivered to the Office 365 account

So far, so simple. Now let's look once more at that image further above where you have two forests and four domains.

Forest = corp.okta.comForest =
 Domain 1 ( 2 ( 3 ( 4 (
Typical loginOKTA\useruser@emea.corp.okta.comATKO\userHQ\user

Notice here that there is a variety of different ways the accounts are setup in each domain and the use of the mail attribute also changes. What's the right approach? It depends on your users, environment and how easily you can make changes to your local Active Directory. The good news is that Okta allows you a lot of flexibility, so even if you cannot force the change in Active Directory, you can normalize the user accounts in Okta before they get to Office 365. Here are some scenarios to think about with regards to the four domains above.

Add a new domain suffix

If you wanted to have all the users from both forests in a single Office 365 instance, but you wanted all the accounts to be and all the accounts to be Domains 1 and 2 don't have a UPN format that fits into your scheme. So what you can do is add a new domain suffix to the forest. Now you can modify user accounts and change their suffix to However all the users logging in as need to be informed of the change, and this could be confusing. Those logging in as DOMAIN\user are unaffected.

Domain 3 has already been solved because users accounts are already in that format and users are used to logging in with their UPN. Domain 4 will already be able to take on the suffix (it's inherited from the parent domain) but this change doesn't need to be communicated to existing users because they all login with their DOMAIN\user.

Use the email address for Okta accounts

As we mentioned earlier, Okta allows you to create accounts in Office 365 based on the email address in Active Directory. In this instance you might favor this approach. You only need to update the email addresses for those in domain 4. This doesn't however mean they would lose their email address, you simply change their mail attribute to and then add to their proxyAddresses attribute.

In some instances, you may want users to have a different username to their email address. This isn't a problem, you can have different groups of users with different primary email domains (e.g., & and yet have a common username domain ( This sort of configuration is fully supported, you just need to ensure you communicate clearly to your user base what their login details are.

Some users will always be impacted...

With both approaches above, some users are always going to have a change when moving to Office 365. For those that login to their Windows environments using DOMAIN\user, they are going to need to know their Office 365 account is going to be their UPN. In our experience it is always a good idea to have the UPN for Office 365 match the email address most commonly used by the user.

Okta agents with DirSync or Forefront Identity Manager (FIM)

Some customers use DirSync or its bigger brother, Forefront Identity Manager, to synchronize Active Directory data to Office 365. This can limit your options a little. DirSync is a prepackaged version of the more complex FIM technology. You can't chose what attribute to use when creating the Office 365 account, DirSync always uses the userPrincipalName. Therefore you must ensure all your accounts in Active Directory have the correct UPN before you use DirSync.

DirSync also doesn't work well with multi forest environments, meaning some customers deploy FIM instead. FIM is a complex identity management solution which allows you to highly customize any aspect of synchronizing data from multiple Active Directory forests into Office 365.

In either case, what is very important is that whatever username DirSync or FIM creates in Office 365. It must match the username of the Okta user for federation. So ensure that however the Okta username is created, it matches the account name that DirSync or FIM has created in Office 365.


  • Jon Murray on October 3, 2017


  • Jason Trent on February 27, 2017

    Why are all the screenshots missing?