To complete this configuration, do the following:
- Contact OneLogin support to enable this feature
- Migrating existing directories
- Verify your Active Directory connection
- Choose a Directory Type (Primary or Secondary)
- Matching Users in OneLogin
- Map Active Directory attributes to sync with OneLogin attributes
- Switch the synchronization direction to export from OneLogin to Active Directory
- Select the Organizational Units (OUs) that you want to sync from Active Directory to OneLogin
- Set advanced Active Directory Connector settings
As an option, OneLogin can enable Advanced Directory Mappings for Unlimited Plan customers that require finer-grained control over how individual attributes are synced from active directory.
When this is enabled, customers have much more control over which fields are brought in from their active directory instances.
Consider asking for the feature to be enabled if you have the need to pull different fields from multiple Active Directory instances in order to create a composite user record in OneLogin.
However, it is worth noting that once this feature is enabled, it is not backward-compatible with the older directories configuration, so this feature cannot be disabled until all Active directory instances have been deleted. Additionally, since it currently removes a large number of previously hard-coded mappings it is much more difficult to manage.
For these reasons, we recommend that customers first turn this feature on in a sandbox accounts and configure it there before enabling it for their main account.
Once enabled, this feature will migrate all existing Active Directory configurations you have in your account to the new format, and the Directory Attributes Mapping page will be replaced with the new Advanced version of this page.
At least initially, this will not automatically add in the previously hard-coded mappings that were automatically applied (but not displayed) in the older version. So you will want to go into your existing directories and manually add the following mappings if you wish to retain them:
|Active Directory Field||OneLogin Field|
Additionally, if this is the be the users' Authenticating Directory, DistinguishedName should be mapped as well.
Please note, that some of these values should not be added if this is to be used as a Secondary Directory as they will be overwritten by the Primary Directory.
Before you perform the configuration described in this article, you must install at least one Active Directory Connector.
Log in to OneLogin as an admin.
Go to Users > Directories, and select the directory.
On the Connector Instances tab, verify that the Active Directory Connector instance is successfully connected.
The Status should show the word "Connected" in green. If you have installed only one Active Directory Connector instance for this Active Directory domain, both User Sync and Auth should show a check mark. For additional Active Directory Connector instances on the same Active Directory domain, only Auth should show a check mark.
To review and update the directory type, go to the Directory Attributes tab.
As part of Advanced Directory Mappings, two types of user synchronization are supported:
- Primary directories - These are directories that have the ability to create new users in OneLogin, and by default, users authenticate against this directory.
- Secondary Directories - These are directories where the primary use case is to map only a subset of the user’s attributes to already existing (in OneLogin) users.
Additionally, unless steps are taken to ensure certain required attributes are matched in OneLogin, users will not be able to authenticate against this directory
- Choose “This directory can create and update users” if this is to be the Primary directory to create users in OneLogin
With this option selected certain user attributes will be required in order to make sure sufficient user details are mapped in order to create new users in OneLogin.
When a user is created or updated from this directory, this becomes the authenticating directory for this user (assuming other settings are configured to authenticate against external directories.)
- Choose “This directory can update users only” if you do not plan on authenticating against this Secondary directory and you only want a subset of user values to be synced over from this directory.
A note on the order of directories syncing:
- If a user is created first in a Secondary directory, OneLogin recognizes that no matching user (yet) exists in OneLogin, and it will cache the details about the user.
- If at a later time, a Primary directory creates a user that matches the secondary directory User Matching logic, it will apply the cached details from the Secondary Directory to the user create operation.
- This ensures users are created properly with all known details from both directory types regardless in the order they happen.
If you plan on mapping users values from multiple directories, you will need to have a common value that matches on all users’ records, regardless of what directory they come from.
Email is frequently used for this purpose, but other attributes (ex. Username, Employee ID) can be used as well.
Care should be taken to avoid matching users by attributes that may be different depending on what directory the user is coming from.
Determining which attributes to use to match existing users in OneLogin with users in Active directory:
This provides a list of attributes to match users in Active Directory against existing users in OneLogin.
- Choose an attribute from your AD instance from the drop-down menu of available fields (by default this will contain the existing directory mapping logic configured in your account)
- Choose the corresponding attribute in OneLogin to match to that value.
- The order of matching can be changed by dragging each row up or down. Fields will be matched in order, so if the first attribute fails to match it will then attempt to match using the next attribute in the list.
If you are matching users using an attribute that is not currently being mapped in the Attribute Mapping section, a warning will be displayed. To make sure users can be properly found, you should be keeping these lookup values in sync between Active Directory and OneLogin. There may be exceptions to this, but they are generally uncommon.
By default, OneLogin provides a few key directory attributes that will be imported from Active Directory to OneLogin during sync. OneLogin provides default mappings of these Active Directory fields to the OneLogin fields that will hold the synchronized values. You can add more mappings and set mappings to synchronize in the opposite direction, from OneLogin to Active Directory.
To review and update directory attribute mappings, go to the Directory Attributes tab.
If this is a Primary directory you cannot change the attributes in these default mappings or the defaults listed on the Directory Attributes tab as these are required in order to create users. But you can map other Active Directory attributes to other OneLogin fields:
Optionally, create a custom user field.
See Custom User Fields.
- On the Directory Attributes tab, click the + (plus) button above the information panel.
A new attribute row is added to the bottom of the list.
- Select the AD Directory Field from the left drop-down, and then select your custom field from the OneLogin Field drop-down.
- Current issues
- If this is a Primary directory, we require that the ad_id in Active Directory be mapped to the ad_id in OneLogin in order for user updates to be processed correctly after user creation. This will be addressed in a future release to not require this mapping.
- Status Field must be mapped to the User's Status field in OL if you want the users’ status to be synchronized from Active Directory to OneLogin
- Mapping the Email field to a custom attribute will result in the email field being mapped to the OL email field
Please note that the Login username attribute functions as a type of mapping to the OneLogin username attribute; the Authentication attribute chosen on the Advanced tab will also be mapped to the username.
By default, attributes are imported from Active Directory to OneLogin during sync. But you can also set user attributes to be exported from OneLogin to Active Directory.
Currently, in order for this to function properly in Advanced Mode, distinguished name (DN) must be mapped from Active Directory to the corresponding field in OneLogin.
Additionally, Secondary directories do not have the ability to write back fields from OneLogin to Active Directory.
Here are two typical scenarios in which you might switch the sync direction from the default:
You manage your user records in your HR system, like Workday or UltiPro, but you use Active Directory to manage access to network resources.
You configure a Workday or UltiPro directory connector to import users and their attributes to OneLogin, and then configure an Active Directory Connector to export users and their attributes from OneLogin to Active Directory. OneLogin functions as an intermediary in the process of syncing users from the HR system to OneLogin. For more details about this scenario, see Provisioning from Workday to Active Directory using Custom Reports.
You maintain some user records in your HR system and others in Active Directory, and you want them both in sync.
For example, you could use Active Directory to manage the attributes included in the default mappings (like first name, last name, email, distinguishedName, memberOf, and so forth), and use Workday to manage attributes that tend to get updated using your HR system, like title, manager name, employee ID, and location, as in the example depicted in the screenshot below. Note that the arrows indicate the direction of sync. The default mappings point from the Active Directory field to the OneLogin field, and the remaining mappings point from the OneLogin custom field (which hold values imported from Workday) to Active Directory fields:
To switch the sync direction:
Go to Advanced tab, select Exporting Users, and save your changes.
Return to this tab and simply click the arrow on an attribute row to switch directions.
You must change one attribute row at a time.
Go to the OU Selection tab to select the AD organizational units that you want to import into OneLogin.
The tab should display your domain's Base DN in the format
The tab opens with the tree expanded only to show nodes that have been selected. Therefore the first time you open the tab, only the top level node is displayed.
Expand the tree by selecting the plus button. After you have selected OUs and saved the page, the tree expands to display only the branches and nodes that include selected OUs. To view child nodes, click the plus button to expand the node. To view sibling nodes, click the ellipsis button.
The following screenshot shows the default tree view, showing only branches that include selected nodes.
The following screenshot shows the same tree, expanded after clicking the bottom ellipsis button (in line with the Stor node). Note that all of the siblings of the Stor node are now displayed.
Go to the Advanced tab to fine-tune your Active Directory Connector settings.
Base DN: If all of your OneLogin-synced Organizational Units are on one domain controller, enter the domain controller info (DC=yourcompany, DC=com) in the Base DN field to improve Active Directory Connector performance.
Mappings: Turn the toggle on to enable OneLogin to assign OneLogin role and group membership -- among other user attributes -- based on user membership in AD security groups. For more information, see Mappings.
Stage users: Turn the toggle on to move Active Directory users to OneLogin's staging environment (requiring manual approval of users) during sync. Turn it off to convert synced AD users automatically to active OneLogin users, without an approval step. If this option is on, you will see imported users listed as Unapproved in Users > All Users. You can activate them one-by-one from their user details page, or you can approve all unapproved users by clicking More Actions and selecting Approve all users from the drop-down menu.
Sync User Status from Active Directory: Select to ensure that users you disable in AD are disabled in OneLogin and deprovisioned from their apps.
Ignore computed user access control: Select to tell OneLogin not to use the Computed User Access Control attribute (msDS-User-Account-Control-Computed) in Active Directory to determine whether a user should be locked out, based on Group Policy.
Enable Smart Password: Select if you are migrating from an LDAP directory to this Active Directory and you want to capture your user's LDAP password in Active Directory without forcing them to do a password reset.
This option works for any user who already has a record in Active Directory. When your user authenticates to OneLogin using their LDAP credentials, OneLogin does a password reset in the background and provisions the user password to Active Directory. The password is never stored in OneLogin.
OneLogin takes the user's AD domain from the Base DN value that you enter on this tab. If that value is empty, OneLogin takes the domain from the Distinguished Name (DN) as synced from the LDAP directory and stored in the OneLogin user record. In a multi-domain environment, the
dc= value in the DN must match the user's Active Directory domain for password provisioning to work.
Enable auto-switch sync failover: Select if you have multiple Active Directory Connectors configured for this Active Directory and you want to fail over automatically to another Active Directory Connector if the Active Directory Connector responsible for synchronization fails. For more information, see Installing Additional Active Directory Connectors for High Availability.
Login username attribute: Select the attribute that your users should use as their user name on your company's branded OneLogin login page. The default is the email address.
With advanced Mappings, this effectively syncs this value from the directory to OneLogin and this attribute will be displayed as the "Authenticating attribute" on the mapping page.
Note that the default, unbranded login page always uses email address as the user name; if you don't brand your OneLogin login page, the setting here won't apply.
Exporting users: Select if you want to export any user attributes from OneLogin to Active Directory. To configure user attribute export to AD, you must also switch the sync direction for each attribute on the Directory Attributes tab.
Deleted users in AD...: Choose what you want OneLogin to do when a user is deleted in Active Directory:
- unaffected in OneLogin
- suspended in OneLogin (users are set to Inactive but their user record remains)
- deleted in OneLogin (user record is completely deleted from OneLogin directory)
Account owners are never suspended or deleted, regardless of your selection here.
Enforce OneLogin password expiration policies: enable to make Active Directory respect OneLogin's policy-based password expiration settings if the OneLogin policy is more restrictive. When you enable this setting, the most restrictive password policy always wins: if OneLogin's password expiration interval is shorter than your Active Directory's, OneLogin's is applied. If your Active Directory password expiration interval is shorter, its policy is applied.