Work with Active Directory user profiles and attributes

Use the Profile Editor to add and remove attributes from the profile, customize attribute mappings, and perform data transformations within inbound or outbound flows.

Known issues

Terminology

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. user profile — A list of user attributes (first name, last name, email and so on) that AD and Okta use to identify and authenticate users.

Attribute mapping — Identifies the relationship between specific AD and Okta attributes. For example, the AD attribute givenName is the same as firstName in Okta.

Expressions and Transformations — Used to concatenate attributes, manipulate strings, convert data types, and more. If equivalent attributes are unavailable for a specific attribute in AD or Okta, you can use data transformations to identify the matching attribute. For example, the AD attribute cn does not have a direct equivalent in Okta. The Okta Expression Language is used to create a transformation so AD knows that the equivalent of cn is a combination of the Okta attributes user.firstName + user.lastName.

To understand how UD and Profile Editor help you manage user profiles and attributes, see About Universal Directory and user profiles.

Base AD attributes

There is a distinction between base and custom attributes. For AD, only 10 attributes are considered base. This means that for Okta, a minimum AD profile contains only 10 attributes. Every attribute outside of the 10-field base profile is considered custom. Some of these custom attributes were previously part of the static profile, but now with UD, you can remove them.

Display Name Variable Name Data Type
distinguishedName dn string
mail email string
objectGUID externalID string
givenName firstName string
sn lastName string
managerUpn managerUpn string
objectSid objectSid string
primaryGroupID primaryGroupID string
sAMAccountName samAccountName string
userPrincipalName userName string

If you have manager value coming from Workday or any other application into Okta and that value can be represented as managerUPN in AD, use the managerUpn mapping. When doing so, the manager must be in same domainA domain is an attribute of an Okta organization. Okta uses a fully-qualified domain name, meaning it always includes the top-level domain (.com, .eu, etc.), but does not include the protocol (https). as the user.

If you have manager value coming from Workday or any other app into Okta and that value can be represented as mangerDN in AD, use the managerDn mapping. In this case the manager can be in different domain than the user.

Mapping the managerUPN or the managerDN incorrectly could result in the manager value failing to update the user object in AD.

Active Directory attribute mappings

To view how Okta attributes are mapped to corresponding AD attributes, see Active Directory attribute mappings to Okta properties.


Add or remove custom attributes

You can only add attributes to the directory profile if they are already in the directory, so Okta performs a schema discoveryAbility to import additional attributes to Okta to populate the list of available attributes. For Okta to discover the attribute, it must be added to an object within the User object hierarchy in the directory: a user object, a parent object, or an auxiliary object.

Schema discovery takes a few seconds to complete and when it’s done you’ll get a list of the attributes that Okta has the permissions to discover in the directory.

  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. In the Filters list, click Directories.
  3. For the directory that you want to modify, click Profile in the Actions column.
  4. Click Add Attribute.
  5. Select attributes in the Add Attributes dialog box, and then click Save.

Delete custom attributes

  1. On the Okta Admin Console, click Directory > Profile Editor.
  2. In the Filters list, click Directories.
  3. Click Profile in the Actions column for the AD directory you want to modify.
  4. Click X next to the attribute.
  5. Click Delete Attribute.

Map profile attributes

  1. On the Okta Admin Console, click Directory > Profile Editor.
  2. Select Mappings for the app, directory, or identify provider.
  1. Select one of the following tabs in the User Profile Mappings dialog box:

a. App to Okta — maps attributes from the app to Okta. The app user profile contains the source attributes and Okta is the target

b. Okta to App — maps attributes from Okta to the app. Okta contains the source attributes and the app user profile is the target

  1. Map attributes:

a. Scroll through the attribute mappings.

b. Ensure that required attributes in the target are mapped. The Okta or app user profile indicates which are required.

c. Use the drop-down to add attributes, or use expressions to add attributes with concatenated or transformed values. For more information about expressions, see Using expressions (transformations).

  1. Optional. Click to set the push frequency for the attribute. See Using Selective Profile Push.
  2. Optional. Click Preview to check your mappings. For more information about this feature, see Universal Directory - Preview Mapping.
  3. Click Save Mappings and Apply updates now.

Remove mapping

  1. On the Okta Admin Console, click Directory > Profile Editor
  2. Select Mappings for the app, directory, or identify provider.
  3. Delete the attribute. The attribute label changes to Choose an attribute or enter an expression.
  4. Optional. Repeat step 3 to remove additional mappings.
  5. Click Save Mappings and Apply updates now.

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 Admin Console, click Directory > Profile Editor.
  2. Select Mappings for the app, directory, or 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..
  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 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).
  • 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.
Top