In certain circumstances, an org may have multiple different Directory Integrations with different Okta Username Formats (Email Address, SAM Account Name, UPN), which will cause users in different Directory integrations to have varied usernames.

• Secure Assertion Markup Language (SAML)
• SAML Username Attribute

The following videos show how to change the username format of a SAML app integration:

In this example, a user may have the following information:

First Name: Tammy
Last Name: Test
Email: ​tammytest@testdomain.internal
SAMAccountName: ttest
UPN: testtam

If Tammy is part of Directory Integration 1, with "Email Address" as the Okta Username Format, then the Okta login would be made with "tammytest@testdomain.internal" (or the prefix). Conversely, if Tammy belongs to Directory Integration 2, which uses "SAMAccountName," the Okta login would be made with "ttest."

In many instances, a third-party application may be able to accept multiple username formats.   In certain circumstances, a third-party SAML application may require a certain format for the username field in order to properly identify the user's identity through a SAML assertion.  If the SAML application expects "Email Address" as the attribute to pull for username, then the information passed from the Okta side will need to be "Email Address" or else the user will not be allowed access to the app.  By default, the Application Username Format in the Sign On Settings for an application is set to "Okta Username".

In the above scenarios, Directory Integration 1 would work without any adjustment, as the Okta Username Format is "Email Address". Since the Application is set to "Okta Username" for the Application Username, the attribute would be passed all the way through to the third-party SAML application, without issue (tammytest@testdomain.internal).

In the case of Directory Integration 2, if the Application Username Format is set to "Okta Username," users in Directory Integration 2 would be passing their SAM Account Name ("ttest").  Since the third-party SAML app is expecting an email address, access would be rejected, and the user would not be allowed to launch the app.

Since the Application Username Format has multiple options (Okta Username, Okta Username Prefix, Email, Email Prefix, Custom, None), each individual application can easily be tailored to suit the requirements of the application.  In the example, since the third-party SAML app requires "Email Address", the Application Username Format can be forced on the Okta side to use the "Email Address" attribute, which is a required user attribute:

1. In the Okta Admin Console, navigate to the SAML application.

2. Click the Sign On tab.

3. Set the Application username format to the required format (Email in this example).