Map User Attributes Between Okta and Office 365

If you have selected the User Sync or Universal Sync option on the provisioning page, you enable the Office 365 integration to use Universal Directory (UD) to manage the mapping of attributes from AD/Okta to Office 365. This allows you to:

The following section details common use cases where UD is used with Office 365, however this isn’t an in-depth guide into Universal Directory.

UD is all about giving you the power to control the mapping of attributes to Office 365 from either the source directory, or the user in Okta. It also lets you, using expressions, manipulate the data in those attributes. For Office 365, these are the most common situations where you want to make changes to the default configuration of UD.

  • Username of the AD user (UPN) that was copied into Okta is not what you want to use in Office 365. (Idfix transformation)
  • Primary email address for the AD user that was copied into Okta is not what you want in Office 365.
  • You have a mix of AD and Okta users that both need to conform to a common username/email format in Office 365
  • Different domains in Office 365 and want to handle the mapping of users differently between them.

Example Scenario 1 – Customizing a users User Principal Name for Office 365:

  1. Login to your Okta orgThe Okta container that represents a real-world organization. as an administrator and navigate to the Applications \ Office 365 appAn abbreviation of application. Essentially, it is a web-based site used to perform any number of specific tasks, and requires authentication from end users by signing in. instance you wish to control the username formats of provisioned users. Select the Provisioning tab.
  2. Make sure that Provisioning has been enabled and that the type is User Sync. Scroll to the bottom and click on “Edit Mappings”.
  3. You are then presented with buttons at the top. The first is for mapping attributes when you import from Office 365 into Okta, but we are interested in mapping attribute when we create the Office 365 user from Okta. So click on the button for Okta to Microsoft Office 365.
  4. You will now see the list of 20 attributes and by default, they will map to either existing Okta attributes or there will be an expression to get the attribute from the AD user, if there is one. The use case we want to address here is that the username from AD that is used in Okta, might not be the username you want in Office 365. Therefore change the value in the UserPrincipalName field (which will be login by default) to the expression shown below. <image> The expression takes the same username prefix (sam.smith) from the current Okta username but forces the domainA domain is an attribute of an Okta organization. Okta uses a fully-qualified domain name, meaning it always includes the top-level domain (.com, .eu, etc.), but does not include the protocol (https). you have configured in Office 365.
  5. Click on the Save Mappings button and this will update the configuration. Note if you have any users that are currently assigned and provisioned, the new changes will automatically update.

Example Scenario 2 – Customizing user attributes:

  1. By default the FacsimileTelephoneNumber is the following expression: hasDirectoryUser()?findDirectoryUser().facsimileTelephoneNumber:null Which will use whatever is set in AD but default to blank if there is no value. You could extend this to evaluate if the AD user’s fax is blank and always set to the main company fax number. i.e. hasDirectoryUser()?((findDirectoryUser().facsimileTelephoneNumber==null OR findDirectoryUser().facsimileTelephoneNumber=="")?"555 1234567":findDirectoryUser().facsimileTelephoneNumber):"555 123 4567"
  2. Create a displayName with more data in it than default and force a standard displayname over whatever came in from AD. source.firstName + " " + source.lastName + "(" + source.department + ")" You could use a custom attribute in AD for setting titles. For example, if you added a customer attribute (or used one of the exchange customer attributes) in AD, and stored in it a true or false depending on if the user was a contractor. You can use the following expression for the Office 365 title. source.title + (source.customAttribute01 == "true"?" (Contractor)":"")
  3. This will result in a title of “Sam Smith” for employees and “Alex Andrews (Contractor)” for contractors.

Another important aspect about Universal Directory and Office 365 is that you have complete control over different domains of users. For example, you might have two Active Directory domains with different email address formats.

  Domain A Domain B
Email Format Firstname(1)

Then in Office 365 you might have two domains, and and users in Domain B need accounts in but Domain A in But you might want to have firstName.lastName for the first part of the email on both domains. UD from Okta makes this easy. In Okta you add a separate Office 365 app for each domain in Office 365 for which you are provisioning users.

You can set all the usernames in Okta to be a common format when you import users from the two Active Directory domains, because you have separate UD mappings and expressions for each domain. (See earlier in this document for mappings when bringing users in from AD). Then because you have two Office 365 apps in Okta for each domain, you can simply use different mappings to ensure the right emails and usernames are created in Office 365.