This site requires JavaScript to be enabled
External Customer KB > General > Mappings
Article: KB0010625 Published: 03/30/2022 Last modified: 03/30/2022

This article includes the following topics:


Mappings in OneLogin enable you to automate changes to user attributes, roles, and groups, based on conditions that you define.  Typically, you use mappings to grant application access based on user attributes stored in third-party directories. For example, you can use mappings to assign a OneLogin role (and access to all of the apps defined by that role) to users whose memberOf attribute contains a specified Active Directory security group. 

Important! Mappings always override attribute values that are set manually.

Note. You can't apply mappings to disabled directories.


  • If you are using mappings to automate membership in OneLogin roles or groups, you must define those roles and groups first. 
  • If you are using mappings to map user attributes from third-party directories like Active Directory, you must have an active connection to the third-party directory, and you must enable mappings for the directory:

    1. Log in to OneLogin as an admin.
    2. Go to Users > Directory and select your directory.
    3. On the Advanced tab, toggle Mappings on.

Create a mapping

To configure a mapping:

  1. Navigate to Users > Mappings and click New Mapping to open the Mappings page.

  2. Give the mapping a name.
  3. Set the Conditions that determine what gets mapped.

    You can set conditions based on DistinguishedName, MemberOf, Email, and many other fields. You can also set different thresholds for the condition, including equals, contains, does not contain, begins with, and ends with.

    Note: If you are setting a DistinguishedName or MemberOf as a condition, it is best practice to use contains rather than equals.

    Note: The DistinguishedName field is sent as Regex. If your DistinguishedName field contains characters used by Regex - including ( ) and * - you can use \ to escape Regex. Example:  \(New Employee)\

    You can add multiple conditions. If you add multiple conditions, you can choose to have users meet all of these conditions or any of these conditions by selecting the option from the Match all / any of the following conditions setting:

    • All sets the conditions to be processed as if joined by an and. In other words, if you had two conditions, Department > contains > Documentation and Title > contains > writer, the mapping would apply to users who are both in the Documentation department and have a title that includes the word "writer."

    • Any sets the conditions to be processed as if joined by an or. In other words, if you set the mapping to apply to users who meet any of the two conditions listed above, the mapping would apply to users who are either in the Documentation department or have a title that includes the word "writer."

    mappings any example

    You can also create mappings that include no conditions.

  4. Set the Actions that you want to apply to the objects that meet the conditions.

    Actions are selectable from the drop-down list.  Some actions take predefined values, which are available by drop-down to the right of the Action field.  Other actions take editable values, which you can enter in an edit box to the right of the Action field.

    You can set multiple actions.

    Take care not to set conflicting actions.

  5. Click Save.

Important! Whenever you create or update a mapping, you must apply the mapping to users by selecting Reapply All Mappings on the main Mappings page (where the mappings are listed) or from the More Actions drop-down on an individual user configuration page (Users > All Users > select user).

Test a mapping

You can test your mapping by checking whether an individual user who should be mapped is indeed mapped.

  1. Go to Users > Mappings and select the mapping from the list.
  2. Enter a user name in the Check Conditions with Users (optional) field and click CHECK.

    You can enter a character or two and a list of matching names appears.

    The mapping results appear immediately below this field, and let you know whether or not the user will be mapped. Note: only licensed users will be mapped. 

Reorder mappings

Mappings are applied in the order in which they are listed on the Mappings page. In the example pictured below, the mappings run in the following order:

  1. Business Development Mapping
  2. Customer Success Management Mapping
  3. Deprovision
  4. Design Mapping

There are occasions when the order in which mappings are applied can be important. In those cases, you can change the mapping order simply by grabbing a mapping row...

...and dragging it to another row:

Troubleshoot a mapping

Why is a value I'm manually setting for a user being overidden by another value?

If you find that a value you’ve manually set for a user is being been overridden by another value, take a look at your mappings. Mappings always override competing attributes that you manually set for a user record.

For example, let's say that you manually set the Authenticated By value for a user to OneLogin.

When you save the user, you find that the Authenticated By value has changed to Active Directory. You change it back to OneLogin, save the user, and find that the value keeps reverting to Active Directory.

Take a look at your mappings. You may have set up a mapping that will automatically set the authentication directory to Active Directory for a set of users that includes the user you are manually updating.

Use Cases

Manager Field Mapping

Admins can now use mappings to set a user's OneLogin Manager field by username or email.

Follow the steps below to set a user's OneLogin Manager field by username or email.

  1. Go to Users > Custom User Fields and click New User Field. Create a custom attribute. Below are 2 examples, choose the value that is available in the directory. 

    • Custom Attribute 1- in the Name field, enter manager email.  In the Short name field, enter manager_email.

      company apps

    • Custom Attribute 2- in the Name field, enter manager username. In the Short name field, enter manager_username.

      company apps

  2. Go to Users > Directories and click on the appropriate directory.

  3. On the Directory Attribute tab, click Add Attribute and select a value that represents the manager's email or user name in that directory. For Bamboo, we select jobinfo_actual.reportsTo which maps to manager email.  

    company apps

  4. Go to Users > Mappings and click New Mapping

    • Create a Condition, for example: manager email > does not equal > blank (leave field empty).

    • Create an Action, for example, Set Manager > by email > manager email.

      We can't assign the manager directly, but if we import the manager's email into a field, you can use a mapping to locate a user with this email and assign them as the user’s manager.

      company apps

  5. Click Reapply All Mappings in the upper right hand corner.

To better understand the relationship between OneLogin Groups, Roles and Mappings check out our video training!

Groups, Roles and Mappings, Oh My!

Expand/Collapse Comments
Was this helpful?