Work with Okta user profiles and attributes

Universal DirectoryUniversal Directory enables you to store an unlimited amount of users and attributes from applications and sources like AD or HR systems. Any type of attributes are supported including linked-objects, sensitive attributes, and pre-defines lists. All of it accessible by all apps in our OIN catalog, over LDAP or via API. (UD) delivers rich user profiles and fine-grained control over how attributes flow between applications. This makes it easier for organizations to create and maintain a single source of truth for its users, enabling new authentication and provisioning scenarios.

As you configure and deploy your Okta orgThe Okta container that represents a real-world organization., you will need to understand what attributes will need to be part of the Okta user profile. Factors you will need to consider include whether you are using a directory such as Active DirectoryActive Directory (AD) is a directory service that Microsoft developed for the Windows domain networks. It is included in most Windows Server operating systems as a set of processes and services. Initially, Active Directory was only in charge of centralized domain management. or LDAPLightweight Directory Access Protocol (LDAP) is a lightweight client-server protocol for accessing directory services, specifically X.500-based directory services. LDAP runs over TCP/IP or other connection oriented transfer services., or another 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. as a profile masterA profile master is an application (usually a directory service such as Active Directory, or human capital management system such as Workday) that acts as a source of truth for user profile attributes. A user can only be mastered by a single application or directory at any one time. For more details, see the Profile Master page. When users are mastered by attribute, we call this attribute-level mastery (ALM). ALM delivers finer grain control over how profiles are mastered by allowing admins to specify different profile masters for individual attributes. Profile mastering only applies to Okta user profiles, not app user profiles. For more details, see Attribute Level Mastering. such as an HR app. To learn more about how UD and Profile Editor work to help you manage user profiles and attributes, see About Universal Directory and user profiles.

Working with the Okta user profile and attributes includes the following:

Enforce custom attribute uniqueness

You can enforce attribute uniqueness across your organization for custom attributes in the Okta user profile, such as employee identification number. You can declare a maximum of 5 unique attributes for each user type. The limit of 5 unique attributes is applied on a per-type basis. You do not need to select the same set of attributes for each user type. For example, the 5 unique attributes you declare unique for user profile A do not need to match what you declared for user profiles B, C, or D.

Unique attributes share a single namespace across all user types per org. If user types A and B both contain the attribute ice cream and you identify it as unique in both profiles, then if user type A has the value chocolate, no other users of type A or B (or any other user type with ice cream declared unique) can have that value. To allow duplicates between unique attributes in different types, modify the attribute names to be slightly different. For example, ice creamA and ice creamB are tracked separately.

Attributes that are not unique are not tracked for uniqueness. If the attribute candy is unique in type E and not unique in type F, and a user of type E has the value caramel for the attribute, then no other users of type E can have the value caramel for the attribute, but any number of users of type F can still have the value caramel. Although candy is unique in E, it is not unique in F, so the value for the attribute in users of type F does not matter.

You can only enforce uniqueness in custom attributes in the Okta user profile. If you are importing users from Active Directory or LDAP and attempt to import one or more users who would violate the uniqueness requirement, import will fail on those users.

If an end user edits their profile and attempts to enter a duplicate value for a custom attribute that has the uniqueness restriction applied to it, they will see a message that the value already exists. They will be unable to save their change until they enter a unique value.

When you mark an existing custom attribute as requiring a unique value, Universal Directory will run a validation check to ensure that no duplicate entries already exist.

  • This check may take some time, depending on how many user records you have.
  • A status message on the Profile Editor page indicates:
    • how many records have been checked
    • how many duplicates have been found and,
    • the estimated time remaining.
  • If duplicate records are found meaning the attribute cannot currently have uniqueness applied to it, the Restriction check box will be cleared automatically. You will have to resolve the duplicate values before applying uniqueness to the attribute.

To enforce uniqueness for a custom attribute:

  1. In the Profile Editor, click the Okta Profile to edit the Okta user profile attributes.
  2. Scroll to the custom attribute you want to mark as unique.
  3. Click Edit.
  4. For Restriction , select that the value must be unique for each user.

    While Okta verifies that the existing data is unique across all users, the check box is unavailable. To remove the uniqueness requirement, deselect the option.

  5. Click Save Attribute.

The status message on the Profile Editor page displays the validation progress and status. This message is displayed to all admins viewing the Profile Editor page so that they are aware a validation check is running.

Use expressions (transformations)

Expressions within mappings let you modify attributes before they are stored in Okta or sent to apps.

Expressions allow you to concatenate attributes, manipulate strings, convert data types, and more. Okta supports a subset of the Spring Expression Language (SpEL) functions. For a comprehensive list of the supported functions, see Okta Expression Language. All functions work in UD mappings.

Disclaimer: While some functions (namely string) work in other areas of the product (e.g., SAMLAn acronym for Security Assertion Markup Language, SAML is an XML-based standard for exchanging authentication and authorization data between an identity provider (IdP) and a service provider (SP). The SAML standard addresses issues unique to the single sign-on (SSO) solution, and defines three roles: the end user, the IdP, and the SP. Here's how SAML works through Okta: SP-initiated flow: the end user requests (principally through a browser) a service from the SP. The SP requests and obtains an identity assertion from the IdP (in this case, Okta). On the basis of this assertion, the SP can decide whether or not to authorize or authenticate the service for the end user. IdP-initiated flow: with Okta as the IdP, an end user goes to the Okta browser and clicks on an app, sending a SAMLResponse to the configured SP. A session is established with the SP, and the end user is authenticated. 2.0 Template attributes and custom username formats), not all do.

Expressions are useful for maintaining data integrity and formats across apps. For example, you might wish to use an email prefix as an username, bulk replace an email suffix, or populate attributes based on a combination of existing ones (e.g., displayName = lastName, firstName).

  1. On the Okta AdminAn abbreviation of administrator. This is the individual(s) who have access to the Okta Administrator Dashboard. They control the provisioning and deprovisioning of end users, the assigning of apps, the resetting of passwords, and the overall end user experience. Only administrators have the Administration button on the upper right side of the My Applications page. Console, click Directory > Profile Editor.
  2. Select Mappings for the app, directory, or IDP.
  3. Enter an expression in the Choose an attribute or enter an expression field.
  4. Preface the variable name(s) with the corresponding object or profile.

a. source refers to the object on the left hand side:

  • Can be used in either Okta to App or App to Okta mappings.
  • Example: source.firstName

b. user refers to the Okta user profile:

  • Can only be used in the Okta to App mapping.
  • Example: user.firstName

c. appUser (implicit reference) refers to the in-context app (not Okta user profile):

  • Can only be used in the App to Okta mapping.
  • Example: appUser.firstName

d. appUserName (explicit reference) refers to a specific app by name:

  • Can be used in either Okta to App or App to Okta mappings.
  • Is used to reference an app outside the mappings.
  • Example:google.nameGivenName
  • If multiple instances of an app are configured, each app user profile has a different variable name appended with an underscore and an incremented number.
  • Example:google, google_1, google_2, etc.
  1. To find instance and variable names use the profile editor:

a. On the Okta Admin Console, click Directory > Profile Editor.

b. Select Profile for the app, directory, or IDP and note the instance and variable name.

  1. Click Save Mappings and Apply updates now.

Override a username

The username override feature overrides a previously selected Okta username format or app username format (different per app). When you implement username override, previously selected username formats no longer apply.

Username override can also be used with Selective Attribute Push to continuously update app user names as user profile information changes. For example, if a user gets assigned to an app with a username of email, and that email subsequently changes, Okta can automatically update the app username to the new email. Prior to this enhancement, an Okta the user's app username had to be manually updated by unassigning and reassigning them to the app. This enhancement applies to all apps and is not limited to only apps with provisioning capabilities.

The following are recommendations for creating usernames:

  • Construct an Okta user name by concatenating multiple imported attributes.
  • Create differently formatted user names using conditionals. For example
    • If attribute1 = A, then username should end in Otherwise, username should end in
    • Example:,
    • This is useful for distinguishing between different types of users (such as employees vs. contractors).
  • Construct app user names from attributes in various sources.
  • Enforce a max length by truncating.
  1. On the Okta Admin Console, click Directory > Profile Editor.
  2. Select Mappings for the app, directory, or IDP.
  3. Choose the mapping direction App to Okta.
  4. Click Override with mapping.
  5. User-added image
  6. Select an attribute or enter an expression to create the Okta username.
  7. Click Save Mappings and Apply updates now.

Override an app username

  1. On the Okta Admin Console, click Directory > Profile Editor.
  2. Select Apps in the FILTERS list.
  3.  Select Mappings for the app.
  4. Choose the mapping direction App to Okta.
  5. Click Override with mapping.
  6. Select an attribute from the drop-down or enter an expression to create the app username.
  7. Click Save Mappings and Apply updates now.

Keep an app username automatically updated

  1. On the Okta Admin Console, click Directory > Profile Editor.
  2. Select Apps in the FILTERS list.
  3. Select Mappings for the app.
  4. Choose the mapping direction Okta to App.
  5. Click next to userName and select Apply mapping on user create and update.
  6. Click Save Mappings and Apply updates now.

Exclude AD username updates during provisioning

To ensure that provisioning events do not update the User Personal Name (UPN) or samAccountName in AD, change the mapping for these attributes.

  1. On the Okta Admin Console, click Directory > Profile Editor.
  2. Click Directories in the Filters list.
  3. For Active Directory, click Mappings.
  4. Click Okta to <your AD instance>.

    User-added image

  5. In the drop-down next to samAccountName, select Apply mapping on user create only.
  6. In the userName attribute immediately below the samAccountName attribute, click Override with mapping.
  7. In the drop-down next to userName, select Apply mapping on user create only.

    Screen capture of the attribute mapping options.

  8. Click Save Mappings and Apply updates now.

Related Topics

About Universal Directory and user profiles

Enforce uniqueness on custom attributes

Hide sensitive attributes