Configure a Required SAML Username Attribute for Multiple Okta Username Formats
Last Updated:
Overview
Organizations with multiple directory integrations often use different Okta username formats, such as email address, SAMAccountName, or User Principal Name (UPN). This configuration causes users in different directory integrations to have varied usernames. When a third-party Secure Assertion Markup Language (SAML) application requires a specific username format, administrators must configure the application username format in Okta to use the required attribute.
Applies To
- Okta Identity Engine (OIE)
- Okta Classic Engine
- Secure Assertion Markup Language (SAML)
- SAML Username Attribute
Solution
How is a required SAML username attribute configured for multiple Okta username formats?
Change the username format of a SAML application integration by navigating to the application sign-on settings in the Okta Admin Console and selecting the required format as detailed in either the video demonstration or the written instructions.
Consider a user with the following information:
- First Name: Tammy
- Last Name: Test
- Email:
<tammytest@testdomain.internal> - SAMAccountName: ttest
- UPN: testtam
If the user belongs to a directory integration with the Okta username format set to email address, Okta logs the user in with <tammytest@testdomain.internal>. Conversely, if the user belongs to a directory integration that uses SAMAccountName, Okta logs the user in with ttest.
Third-party applications often accept multiple username formats. However, a third-party SAML application might require a specific format for the username field to properly identify the user through a SAML assertion. If the SAML application expects an email address as the username attribute, Okta must pass the email address. Otherwise, the application denies access. By default, Okta sets the application username format in the application sign-on settings to the Okta username.
In the first scenario, the directory integration functions without adjustment because the Okta username format is an email address. Since the application username format is set to the Okta username, Okta passes the attribute to the third-party SAML application without issue.
In the second scenario, if the application username format remains set to the Okta username, users pass their SAMAccountName (ttest). Since the third-party SAML application expects an email address, the application rejects access.
Okta provides multiple options for the application username format, including "Okta username", "Okta username prefix", "Email", "Email prefix", "Custom", and "(none)". Administrators can tailor each application to suit specific requirements. In this example, since the third-party SAML application requires an email address, administrators can force the application username format in Okta to use the email address attribute.
Configure the application username format in the Okta Admin Console by navigating to the SAML application sign-on settings and selecting the required format.
- In the Okta Admin Console, navigate to the SAML application.
- Select the Sign On tab.
- Choose the required format from the Application username format dropdown menu (Email in this example).
