Okta allows modifying the username format used for Active Directory-sourced users during authentication by adjusting provisioning settings and applying custom expressions. This article describes how to change the username format and provides an example expression for a common use case.
- Okta Classic Engine
- Okta Identity Engine (OIE)
- Active Directory (AD)
- Delegated Authentication
- Active Directory-sourced users
How is the username format for Active Directory users modified?
Follow the video or steps below to access the directory integration settings and apply a new Okta username format.
-
In the Okta Admin Console, navigate to Directory > Directory Integrations.
-
Select the Active Directory domain.
-
Select Provisioning > To Okta and then select Edit.
-
Choose Custom from the Okta username format dropdown menu.
-
Enter a custom expression in the field provided.
NOTE: The following expression is an example that takes the first letter of the username and appends it to all characters after the first dot in the username:
String.substring(appuser.userName, 0, 1) + String.substringAfter(appuser.userName, ".")Example: If a user currently signs into Okta with
john.doe@domain.com, this expression changes the login tojdoe@domain.com. The expression is customizable but must remain in email format by default. -
After verifying the custom expression or selecting a predefined option, select Save.
-
Navigate to the Okta Attribute Mappings section.
-
Select Force Sync to apply the change to all existing users.
NOTE: The number of users in the directory directly impacts the time required for changes to take effect. To verify the updates, navigate to the Assignments tab of the Active Directory integration and review the usernames for the assigned users.
The following list describes the behavior for common predefined username options:
-
Okta username: Okta sends the exact value of
user.loginas the User Principal Name (UPN). This can result in a different UPN domain suffix if the value in Okta differs from the Active Directory domain name. -
From Okta username: Okta removes the domain suffix of
user.loginand adds the Domain naming context (e.g.,john.doe@domain.combecomesjohn.doe@ADDomainName.com) for the UPN. -
Email: Okta uses user.email to populate the UPN. This is not recommended as email uniqueness is not enforced in Okta, which can lead to provisioning errors.
