About Universal Directory
Universal Directory (UD) is a platform that delivers rich user profiles and fine-grained control over how attributes are exchanged between applications. UD makes it easier for organizations to create and maintain a single source of truth for its users, enabling new authentication and provisioning scenarios.When UD is enabled for your org, you'll have access to the Profile Editor in the Admin Console with the ability to:
These new capabilities enable you to do the following:
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.
Using Universal Directory
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:
These two Profile types are used to:
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:
To view an Okta user profile:
Okta has defined 31 default base attributes for all users in an org. 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.
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.
App User Profile
An app user profile represents a user in a 3rd-party application, directory, or identity provider (IdP). 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 Directory 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 UD, see Apps Supporting Profile Mapping. The two chief use-cases that UD facilitates are
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).
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 is UD-upgraded.
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.
The previewmapping feature provides a view into how a mapped attribute will appear before committing to the change.
To use, enter a specific, valid user's name into the Preview field. A valid user is one that is currently assigned to the app that you are mapping attributes to or from. Entering the first name enables an auto complete list use keyboard arrows to find the required name, then click the Return button.
The preview appears on the right-side column, and is color coded to indicate success or failure. It also includes the attribute value and data type.
Viewing the Preview
The colors immediately indicate whether the mappings are successful or incomplete:
This is a valid mapping OR this is a valid mapping with no (null) value.
An invalid mapping. It also displays an error message that specifies the problem, as shown below.
A blank column indicates
There is not mapping for that attribute.
Every mapped attribute should result in a preview value under the right-side column. An exception is when the username has been determined through the app. In such cases, the username does not show a mapping, as shown below.
The exception to this is if you use the Override with Mapping button during your mapping. In this case, the username appears like all the other attributes.
Using the Profile Mapping Tab
To create a mapping between an Okta user profile and an app user profile:
a. App to Okta (highlighted in red) maps the flow of attributes from the app to Okta.
b. Okta to App (highlighted in blue) maps the flow of attributes from Okta to the app.
a. Scroll through the attribute mappings.
b. Ensure that required attributes in the target are mapped.
c. Define mappings using the drop-down menu or expressions:
d. For details on this feature, see Using Selective Profile Push.
To remove a mapping, simply delete the entry from the field. When successfully deleted, the attribute's label changes to Add mapping.
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 UD 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).
a. source refers to the object on the left hand side:
b. user refers to the Okta user profile:
c. appUser (implicit reference) refers to the in-context app (not Okta user profile):
d. appUserName (explicit reference) refers to a specific app by name:
a. Navigate to People > Profile Editor > Profiles.
b. View an Okta user profile and note the instance and variable name.
c. View an app user profile and note the instance and variable name.
Example screen shots of expressions:
User name Overrides
UD allows you to handle the most demanding user name requirements. Constructing custom Okta user names or application user names with UD's data and expression language is easy.
Example use cases:
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
To override an app username
To keep the app username automatically updated
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:
Rich SAML Assertions and WS-Fed Claims
UD 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:
Configure Rich SAML Assertions and WS-Fed Claims
Currently, only the Template SAML 2.0, Template WS-Fed, and SAML Wizard Apps can send UD data. To configure this: