About Universal Directory

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. delivers rich user profiles and fine-grained control over how attributes are exchanged between applications. Universal Directory makes it easier for organizations to create and maintain a single source of truth for its users, enabling new authentication and provisioning scenarios.

With Universal Directory you'll have access to the Profile Editor in the 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 with the ability to:

These capabilities enable you to do the following:

  • Synchronize user profile information across cloud HR systems, on-premise directory systems and applications.
  • Provision application user accounts with rich profile information such as roles, managers, geo-locations and other attributes that aid in configuring complex authentication and authorization rules.
  • Collect, import and store any type of user attribute, including externally defined custom attributes.

Warning: Universal Directory and the accompanying Profile Editor features are very powerful options. The alteration of profiles and mappings can have unintended effects in downstream apps — please be cautious when making such changes.

This section describes various features and functions supported by Universal Directory, available configuration options and use-cases that can be accomplished. Topics include:

Profiles (Okta User and App User)

Universal Directory uses the concept of profiles, a logical grouping of attributes to represent user accounts. In particular, Universal Directory supports two types of profiles:

  • Okta User Profile
  • App User Profile

These two Profile types are used to:

  • Store rich attributes in Okta
  • Move rich attributes from Okta to 3rd party applications

Use the Profile Editor to view or modify these profiles: Directory > Profile Editor.

Best Practice: As a best practice, Okta recommends that you maintain the size of Okta user and App user profiles to less than or equal to 1MB in size. This recommended size includes the names and the corresponding values of all the attributes that make up a profile. For more information on analyzing profiles, see Profile Objects in the Okta API documentation.

Okta user profile

The Okta user profile is a logical representation of a user in Okta (also known as an Okta Account). The Okta user profile is comprised of two sets of attributes:

  • Base attributes.
  • Custom or extensible attributes.

Okta has defined 31 default base attributes for all users in an orgThe Okta container that represents a real-world organization.. These base attributes are generally fixed and cannot be modified or removed. There are two exceptions: First Name and Last Name. These two attributes can be marked as required or optional for Okta-mastered users only. To import users with blank First Name or Last Name attributes, you must first mark the attributes as optional in Okta, otherwise the import will fail. When you add attributes to the user profile, you add them as custom attributes.

To view an Okta user profile:

  1. From the Administrator Dashboard, click on Directory > Profile Editor.
  2. Click the Okta filter.
  3. Click the Profile button under the Actions column to open the Profile view for an Okta user.

Adding Custom Attributes

Extend an Okta User profile by adding an attribute to the custom portion of the profile. Base attributes are generally fixed and cannot be modified or removed. There are two exceptions: First Name and Last Name. These two attributes can be marked as required or optional for Okta-mastered users only.

  1. Select User under the Okta profile type.
  2. Click the Add Attribute button. The Add Attribute screen appears.
    User-added image
  3. Complete the following fields:
    • Data type:There are 8 admissible data types:
      • string: a chain of zero or more unicode characters (letters, digits, and/or punctuation marks)
      • number: floating-point decimal in Java's 64-bit Double format. For details see the Java Platform Specification.
      • Boolean: stores true, false, or null data values
      • integer: whole numbers in 64-bit Java's Long format
      • date: stores only the calendar date and requires four bytes in ISO 8601 format
      • array of string: sequential collection of strings
      • array of number: sequential collection of numbers
      • array of integer: sequential collection of integers
      • country code: Two character country code as listed in https://www.iso.org/iso-3166-country-codes.html.
    • Display name: A human readable label that will appear in the UI
    • Variable name: Name of attribute that can be referenced in mappings
    • Description: A meaningful description of the attribute
    • Attribute required: Select this check box if the attribute must be populated.
    • User permission: Choose options to hide the attribute or make it read-only or read-write.
  4. When completed, click the Add Attribute button or, if you wish to add more than one, click the Save and Add Another button.

App User Profile

An app user profile represents a user in a 3rd-party application, directory, or identity provider (IdPAn acronym for Identity Provider. It is a service that manages end user accounts analogous to user directories such as LDAP and Active Directory, and can send SAML responses to SPs to authenticate end users. Within this scenario, the IdP is Okta.). The app user profile lists the 3rd-party's attributes that Okta can read and write to (read-only for IdP). This profile is used to control the attributes that Okta pushes to an app or the attributes imported from an app into Okta.

Similar to Okta user profiles, app profiles have both base attributes and custom attributes. Custom attributes for app user profiles differ from those for Okta user profiles. Whereas Okta user profiles can be extended with any custom attribute, app user profiles can only be extended with attributes from a predefined list that Okta dynamically generates. Okta generates the list of attributes by querying the 3rd-party application or directory for supported attributes.

Note: 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. users, look here for details on Using Custom Attributes with Active Directory.


Profile mappings allow administrators to precisely control the attributes exchanged during provisioning processes. For a list of apps that integrate particularly well with Universal Directory, see Apps Supporting Profile Mapping. The two chief use-cases that Universal Directory facilitates are

  • App to Okta
  • Okta to app

In the first use-case (App to Okta), organizations typically use a source-of-truth app such as a directory or human resources system. Some organizations might have several sources of truth. Mappings define how attributes from these various sources are imported into the Okta user profile.

The diagram below illustrates the first use case. In the example, Active Directory (AD) and Workday supply the Okta user profile with attributes (AD provides FirstName and LastName; Workday provides Boss). The diagram illustrates the mapping of givenName and sn to FirstName and LastName (from AD to Okta), and it shows the mapping from managerUserName to Boss (from Workday to Okta).

User-added image

In the second use-case (Okta to App), organizations wish to propagate the data in Okta to other applications to provision accounts and update accounts with rich data. This is possible if the Okta user profile has rich attributes and the app in Okta supports provisioning.

The following diagram illustrates the second use-case. In the example, Okta sends four attributes to Google. The diagram shows the mappings of four Okta user profile attributes to four Google App user profile attributes.

User-added image

Using the Profile Mapping Tab

To create a mapping between an Okta user profile and an app user profile:

  1. Identify the app, directory, or IDP to map.
  2. Select either the Profile or the Mappings button for the App user profile.

    User-added image

  3. Select the desired tab.
    • App to Okta (highlighted in red) maps the flow of attributes from the app to Okta. An app user profile contains the source attributes; Okta is the target.
    • Okta to App (highlighted in blue) maps the flow of attributes from Okta to the app.Okta contains the source attributes; an app user profile is the target.
  4. Map attributes (highlighted in orange) in the right tab:
    1. Scroll through the attribute mappings.
    2. Ensure that required attributes in the target are mapped. The Okta or app user profile indicates which are required.
    3. Define mappings using the drop-down menu or expressions:
      • Use the drop-down menu to directly populate target attributes with source attributes.
      • Use expressions to populate target attributes with concatenated or transformed values.
      • See Using Expressions (Transformations) below for details.
  5. Configure the profile push frequency (Optional). Mapping can be:
    • applied on user create and update.
    • applied on user create only.
    • disabled.
    For details on this feature, see Using Selective Profile Push.
  6. Once you have completed your changes, a best practice is to check your mappings using the Preview button. See Univeral Directory - Preview Mapping for details.
  7. Click the Save Mappings button to save your choices.

To remove a mapping, simply delete the entry from the field. When successfully deleted, the attribute's label changes to Add mapping.

User-added image

Using Expressions (Transformations)

The details above describe how to map attributes that flow from one source to another without modification. For example, a first name of "John" imported from Google gets stored as "John" in Okta. However, if you wish to modify attributes before storing them in Okta or sending them to apps, you can do this with expressions within the mappings.

Expressions allow you to concatenate attributes, manipulate strings, convert data types, and more. Okta supports a subset of the Spring Expression Language (SpEL) functions. Find a comprehensive description of the supported functions under Okta Expression Language. All functions work in Universal Directory mappings.

Disclaimer: While some functions (namely string) work in other areas of the product (e.g., SAML 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).

Configure Expressions

  1. Navigate to the Mappings page of the app (instructions are in the Configure Mappings section).
  2. Enter the desired expression in the Attribute Mapping field.
  3. Preface the variable name(s) with the corresponding object/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 for the above step, use the profile editor

a. Navigate to People > Profile Editor > Profiles.

b. View an Okta user profile and note the instance and variable name.

User-added image

c. View an app user profile and note the instance and variable name.

User-added image

Example expressions:

User name Overrides

Universal Directory allows you to handle the most demanding user name requirements. Constructing custom Okta user names or application user names with Universal Directory's data and expression language is easy.

Example use cases:

  1. Construct an Okta user name by concatenating multiple imported attributes.
  2. Create differently formatted user names using conditionals. For example
  • If attribute1 = A, then username should end in acme.com. Otherwise, username should end in acme-temp.com.
  • Example: john.doe@acme.com, john.doe@acme-temp.com
  • This is useful for distinguishing between different types of users (such as employees vs. contractors).
  1. Construct app user names from attributes in various sources.
  2. Enforce a max length by truncating.

The username override feature overrides a previously selected Okta username format or app username format (different per app). When username override is configured, the 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 admin had to manually change a user's app username by unassigning the user and reassigning him to the app. This enhancement applies to all apps and is not limited to only apps with provisioning capabilities.

To override an Okta username

  1. Navigate to the app's mapping.
  • The app from which Okta accounts are imported—typically AD or Workday.
  1. Choose the mapping direction App to Okta.
  • You're creating an Okta username from app attributes.
  1. Click the Override with mapping button.
User-added image
  1. Observe that a mapping field appears.
  2. Select an attribute or enter an expression to create the Okta username.
  3. Click Save Mappings and Apply updates now.

To override an app username

  1. Navigate to the app's mapping.
  • App whose username you wish to override.
  1. Choose the mapping direction Okta to App.
  • You're creating an app username from Universal Directory attributes.
  1. Click the Override with mapping button.
User-added image
  1. Observe that a mapping field appears.
  2. Select an attribute or enter an expression to create the app username.
  3. Click Save Mappings and Apply updates now.

To keep the app username automatically updated

  1. Navigate to the username override configuration.
  2. Select the green arrow.

To 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 in the Profile Editor as follows:

  1. Go to Directory > Profile Editor.
  2. Click Directories in the pane on the left.
  3. For Active Directory, click Mappings.
  4. Click Okta to <your AD instance>.

    User-added image

  5. From the drop down menu 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. From the drop down menu next to userName, select Apply mapping on user create only.

    User-added image

  8. Click Save Mappings.

Rich SAML Assertions and WS-Fed Claims

Universal Directory attributes can be sent in SAML assertions and WS-Fed claims. Apps can consume rich SAML assertions and WS-Fed claims to do the following:

  • Create rich user accounts in the app
  • Update accounts with rich data
  • Make fine-grained authorization decisions

Configure Rich SAML Assertions and WS-Fed Claims

Currently, only the Template SAML 2.0, Template WS-Fed, and SAML Wizard Apps can send Universal Directory data. To configure this:

  1. Add the Template SAML 2.0 App, Template WS-Fed App, or SAML Wizard App.
  2. Locate the attribute statements field.
  • Labeled Attribute Statements in the Template SAML 2.0 App
  • Labeled Custom Attribute Statements in the Template WS-Fed App
  • Labeled Attribute Statements in the SAML Wizard Apps
  1. Enter Okta user profile attributes in the attribute statements field.