OneLogin's Active Directory Connector (ADC) is the perfect tool for companies that use Microsoft Active Directory as a domain controller (DC).
Active Directory Connector 5 provides significant performance improvements, firewall-friendliness, and support for HTTP proxy servers. If your HTTP proxy server requires authentication, ADC 5 provides it with Windows domain authentication.
ADCs manage OneLogin user authentication against Active Directory and provide real-time synchronization of users between Active Directory (AD) and OneLogin. ADCs also function as the redirect service in a Windows Domain Authentication implementation.
Before proceeding with the steps in this article, you should:
smux.us.onelogin.com (this replaces
Note: ADCs can be installed on Windows Server 2012 R2+, as well as support DCs running on earlier versions of Windows Server. However, do not attempt installation in FIPS Compliance Mode. The installation will succeed, but startup aborts with an error in ADC.LOG.
Important! We recommend you install the connector on a member server machine in the same physical network as your Active Directory service.
Sign in to the OneLogin admin portal and go to Users > Directories. If you have previously configured a directory, click New from your directories list. Otherwise, you're taken directly to the Select a Directory Type page.
Choose Active Directory from the list of available directory types. This launches the Active Directory Setup Wizard.
Name your directory. OneLogin supports the simultaneous integration of multiple directories as long as they each have a unique name. You'll use these names often, so choose something simple and descriptive.
Click Download AD Connector to download the most recent version of the installer file.If you've previously installed ADC 4 and are upgrading your connector to ADC 5, you may see an option to Upgrade Remotely. Click this option, wait a minimum of 5 minutes, then refresh the Connector Instances page in your OneLogin Active Directory configuration. You will not see a progress indicator during the 5-minute wait, but if the refreshed page now shows the most recent version number, the remote upgrade process has finished successfully.
Copy the installation token for use during the installation.
Sign in as a domain administrator on the machine that will host your Active Directory Connector.
Run the Active Directory Connector installer you downloaded in the previous section.
Review and Accept the license terms.
Paste the token you previously copied from the Active Directory Setup wizard and click Next.
Select the appropriate option, depending on your current system setup:
Use existing OneLogin Service Account
This option is only visible if you're upgrading an existing ADC.
Create a OneLogin Service Account
Select this option for new ADC installations. It creates a domain service account in the local Domain named OneLoginADC with Builtin\Administrators credentials.
Note: If you have more than one domain in your Active Directory Forest, you will need to add this new account to the Domain Administrators or Builtin\administrators groups in the other domains.
Run service as:
If no ADC is installed on this machine and you want to use an existing domain service account, select this option and enter the Domain and account used to run the ADC.Note: This must be a domain service account with privileges to read the directory tree throughout your Forest and Domains as well as the ability to reset passwords.
Run Service as LocalSystem
Select this option if you use a single domain and you're planning on installing the ADC only on DCs, not on member servers.
Note: The Active Directory Connector can only be installed on a full Read-Write Domain Controller.
Set the port that will be used by Windows Domain Authentication to authenticate ADC and click Next.
443 if you intend to enable SSL for this connector (recommended for most configurations, and required to support multible ADC instances).
If you choose to accept the default port of
8080 or enter another port, be sure to disable the Windows Host Firewall Rule or open any other server-based firewalls for inbound connections to that port.
Select the location (US or EU) of your organization's OneLogin database. If you're unsure, or if your organization is headquartered outside the US or Europe, contact your OneLogin representative for confirmation. Click Next.
Click Install. When the installation is complete, click Finish to exit the installer.
The service runs under the domain service account by default, but you can use the Domain Configuration Wizard to customize the domains and universal security groups that the ADC syncs with OneLogin. Open the wizard when prompted at the end of installation, or at any time later by launching ADConfigWizard from the ADC installation directory. See Synchronizing Domains and Security Groups with OneLogin for more information.
Once you have completed the installation, the Active Directory Installation Wizard in OneLogin will automatically progress to the Import Users stage.
Select the organizational units and/or domains you wish to synchronize with and click Finish.
To initialize the first synchronization, open the More Actions menu and select Synchronize Users. Users will now automatically sync from Active Directory to OneLogin when they're created or updated in Active Directory.
Once the Active Directory Connectors are successfully installed, configure the integration between your instance of Active Directory and OneLogin.
Go to Users > Directories and select the directory.
Verify that the Active Directory Connector instance is successfully connected.
To review and update directory attribute mappings, go to Directory Attributes.
OneLogin syncs the following fields from Active Directory to OneLogin:
|Active Directory Field
The attributes in the default mappings are hardcoded, but you can map other Active Directory attributes to custom OneLogin fields:
Create a custom user field for your mapping.
In Directory Attributes, click Add Attribute. A new attribute row is added to the bottom of the list.
Select the fields you would like to map together from the two drop-down menus.
You can use custom attribute mappings to import and export the manager field between OneLogin and AD/LDAP.
To import the Manager field, choose Set Manager and by distinguished name.
To export the Manager field, create a new mapping macro called
Go to OU Selection. A display tree beginning with your domain's Base DN appears in this format:
DC=your-company,DC=com. Expand the tree and select the AD organizational units you want to import into OneLogin.
As of version 5.1.3, you can deselect a child OU from the selected parent OU in order to exclude it from the synchronization process. The users under the deselected OU aren't synchronized, including the OUs under this deselected branch of the OU tree. All ADC connectors must be running at least this version in order for this feature to work.In this example, New York and its child objects won't synchronize:
Go to Advanced to set granular Active Directory Connector settings:
OBSOLETE: Used with ADC Version 3.x, which is no longer supported
When toggled on, enables OneLogin to assign roles, groups, and other user attributes based on AD security groups. See Mappings for more information.
When toggled on, moves AD users to OneLogin's staging environment during sync, requiring manual approval. You can activate users individually in their user detail page, or all at once by selecting Approve all users from the More Actions. When toggled off, synced AD users are automatically converted to active OneLogin users without approval steps.
Sync User Status from Active Directory
When checked, any users disabled in AD are automatically also disabled in OneLogin and deprovisioned from OneLogin apps.
Ignore computed user access control
OBSOLETE: Used with Windows Server 2003, which is no longer supported.
Enable Smart Password
When checked, users' SSO passwords are synced to AD without requiring password reset. This is useful if you migrate an LDAP directory to this Active Directory instance.
OneLogin uses the domain from the Distinguished Name (DN) that's synced from the LDAP directory and stored in the OneLogin user record. In a multi-domain environment, the
Enable auto-switch sync failover
When checked, OneLogin automatically switches to another ADC if the one responsible for synchronization fails, provided that multiple ADCs are configured for this Active Directory instance.
Login username attribute
Select the attribute used to match the user and prevent duplicates. The default value is email address. Users can log in with samAccountName or Email regardless of which field is selected to match to the username attribute, but the username attribute must be unique for each user.
When checked, user attributes are exported from OneLogin to Active Directory. By default, attributes are imported from AD to OneLogin, but this setting reverses the direction, exporting attributes from OneLogin to AD; this can be useful when user records are maintained in both Active Directory and another system synced to OneLogin, such as if you use Workday or UltiPro to manage HR for your users, but AD to manage their access to network resources.
You can switch the sync direction for each individual attribute by clicking the arrows between them in Directory Attributes.
Deleted users in AD...
Decide what occurs when users are deleted in Active Directory:
Warning: Account owners aren't suspended or deleted from OneLogin regardless of what action is selected, but if their account is authenticated by AD they may be prevented from logging in to OneLogin when deleted in AD. For this reason, Account Owner accounts should not be authenticated against external directories like Active Directory.
Enforce OneLogin password expiration policies
When checked, OneLogin's password expiration policy overrides AD's policy if it has a shorter expiration interval so that the more restrictive policy is always applied. When unchecked, AD's password expiration policy is always used regardless of interval.
Check users status before authenticating the user.
When checked, users' AD statuses are not automatically synced to OneLogin upon authentication. Instead, OneLogin checks the status and does not pass the authentication request to AD if the user is locked.
Do not write user status back to Active Directory
When checked, users' OneLogin statuses are not automatically synced to AD. Instead, the admin can unlock users in OneLogin regardless of the user status in Active Directory or if OneLogin can change the user status in Active Directory.
Open the Domain Configuration Wizard when prompted at the end of installation or by launching ADConfigWizard from the ADC installation directory.
By default, all domains are selected; uncheck any that you want to prevent from syncing with OneLogin. Previously unselected domains are hidden from the list but can be viewed by selecting Show unselected domains.
By default, all security groups are synchronized. However, once you add one security group, all others are excluded from synchronization unless you manually add them as well. If you select a security group with any child security groups, the child groups groups sync with OneLogin as well.
To deploy a proxy server that manages network traffic to and from your AD server, configure the Windows settings below after installing your ADC.
Note: If you use Windows Domain Authentication with Active Directory Connectors, the traffic travels between the browser and the ADC. It doesn't pass through the HTTP proxy.
To best support your organization's security and provide a user-friendly experience, we recommend enabling SSL for each ADC instance you install. Additionally, SSL is required if you use Windows Domain Authentication and have configured multiple AD Connectors for load balancing.
Follow the process described in Enabling SSL for Active Directory Connectors for each instance.
Go to Connector Instances in your OneLogin Active Directory configuration to view a list of all current connectors, along with their statuses, enabled tasks, and version numbers. The Sync Status column refreshes every 15 minutes and provides additional details about the connectors' reachable domains, backlogged users, and health checks.
Select any connector to manage its tasks and options and to disable, upgrade, or remove it.
Note: If you have multiple ADCs, we recommend that you upgrade your authentication connectors first, then switch an upgraded authentication connector to User Synchronization before upgrading the old user sync connector.
Open the connector and click Disable to stop it, then Download the connector installer and copy its Installation Token.
Run the downloaded installer on the connector's host machine, selecting Use existing OneLogin Service Account for the Service Log On Credentials.
After verifying that the upgraded connector has successfully installed, return to the connector instance in your OneLogin admin portal and re-enable it.
By default, the OneLogin ADC synchronizes most users in real-time by subscribing to Active Directory Change Notifications. If a user is added or removed, or one of their mapped or required attributes changes, AD sends the change to OneLogin for immediate update.
Additionally, a full directory sync is performed every 15 minutes to capture any changes missed by the real-time sync. To change this interval, launch Notepad or a similar text editor as an admin and open
C:\Program Files (x86)\OneLogin Inc\OneLogin Active Directory Connector\connectorService.exe.config. Locate the setting MinSyncPollWorkerWaitTimeout and modify its value in the HH:MM:SS format.
For extremely large or active organizations, the directory change notifications may fail to capture all events. In this case, you may wish to instead use Microsoft's DirSync control or OneLogin's directory sync cookie.
To enable the cookie, locate the ChangeNotificationMethod setting in your
connectorService.exe.config file and replace the
NormalChangeNotification value with
DirectorySyncCookie. The default polling interval for the directory sync cookie is 5 seconds, but this can be changed by entering a new HH:MM:SS value in the ChangeNotificationPollInterval setting.