OneLogin's Active Directory Connector (ADC) is the perfect tool for companies that use Microsoft Active Directory as a domain controller.
Active Directory Connector 5 provides significant performance improvements, firewall-friendliness, and support for HTTP proxy servers. If your HTTP proxy server requires authentication, Active Directory Connector 5 provides it with Windows domain authentication.
Active Directory Connectors manage OneLogin user authentication against Active Directory and provide real-time synchronization of users between Active Directory (AD) and OneLogin. Active Directory Connectors also function as the redirect service in a Windows Domain Authentication implementation.
Install and configure a minimum of three Active Directory Connector instances to provide load balancing and failover. For an overview of Active Directory Connector load balancing and failover, see Install Additional Active Directory Connectors for High Availability.
The instructions in this article detail the installation of a single Active Directory Connector instance, but also provide links to load balancing and failover installation at the appropriate point in the installation procedure.
If your organization uses any workstations running Windows 10 or later, you need to activate your licenses with Office 365. Please see Configure Hybrid Azure Active Directory Join.
Windows Server 2012, 2016, or 2019
Note: Active Directory Connectors can be installed on Windows Server 2012 R2+, they also support domain controllers running on earlier versions of Windows Server. Don't attempt installation in FIPS compliance mode; the installation will succeed, but startup aborts with an error in ADC.LOG
.NET Framework 4.5.1 and up
Processor: Pentium 4 or better
RAM: 512MB
Disk space: 120MB, configurable to less than 50
Outbound TCP Port 443 from the server running the connector to the network ranges listed in OneLogin Domains and IP addresses.
For domain whitelisting, whitelist smux.us.onelogin.com (replaces adc.onelogin.com)
Remote Server Admin Tools: AD DS and AD LDS Tools in windows server features, if the server isn't a domain controller. The names may differ for prior versions of Windows Server 2016.
To verify if your browser is supported, see Supported Platforms and Standards.
Review the Create a Domain Service Account to run Active Directory Connector document to understand where to install the Active Directory Connector.
Review your Account Settings prior to installing Active Directory Connectors. Account Settings can affect the way OneLogin treats Active Directory passwords.
Enable directory fallback password cache: Enabled by default. Caches a hash of the user AD passwords that enables OneLogin to authenticate a user with the last successful password, in the event of lost communication between OneLogin and AD.
Enable password mapping: Caches encrypted AD passwords in OneLogin to provide access to apps that use SSO password for app authentication.
For more information, see Account Settings for Account Owners.
A minimal amount of ports are required to install a OneLogin Active Directory Connector in the DMZ (perimeter network). Microsoft Windows Server must be connected to the Windows Domain Controller for ADC installations. Microsoft provides the required network port communication for connecting through a firewall.
OneLogin Active Directory Connector uses only the following network ports for connections to AD:
Additionally, because the ADC depends upon DNS for connections, port TCP/UDP port 53 must be open. Active Directory itself depends upon the availability of other ports to properly perform services. For example:
For more information, see https://technet.microsoft.com/en-us/library/dd772723(v=ws.10).aspx.
As an admin, go to Users > Directories, and click New.
On the Select a Directory Type page, choose Active Directory from the list of available directory types. This launches the Active Directory Setup Wizard.
In Section A, name your directory. OneLogin supports the simultaneous integration of multiple directories, each with a different name. Note: you will use these names often, so choose something descriptive.
In Section B, click Download AD Connector Version to download the installer file. You can review the release notes here: ADC Release Notes.
You can also download the installer here: onelogin_ad_connector.msi
Install the connector on a server on the same network as your Active Directory service.
Important! We recommend you install the Active Directory Connector on a member server machine in the same physical network as the DC.
Sign in as a domain administrator on the machine that will host your Active Directory Connector.
Run the Active Directory Connector installer that you previously downloaded.
Click Next, on the Welcome page and accept the license terms on the End-User License Agreement Page.
On the Connector Token dialog, paste the token you copied from the Active Directory Setup wizard.
If you're upgrading an existing Active Directory Connector instance, or adding an additional authentication-only Active Directory Connector instance, this is the token you copied from the Active Directory Connector configuration dialog.
On the Service Log On Credentials page, provide the domain and account used to run the Active Directory Connector.
Select the appropriate options, depending on your current system setup:
You're prompted to Use existing OneLogin Service Account if you're upgrading an existing Active Directory Connector. We recommend you select this option if you are upgrading.
You're prompted to Create a OneLogin Service Account if no ADC has been installed on this machine.
We recommend you select this option for new Active Directory Connector installations. It creates a domain service account named OneLoginADC with Builtin\Administrators credentials in the local Domain. Follow the prompts to create the service account. 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.
If no Active Directory Connector is installed on this machine, and you want to use an existing domain service account, select Run service as: and enter the domain and account used to run the Active Directory Connector.
This must be a domain service account with privileges to read the directory tree throughout your Forest and Domains, the ability to reset passwords. For more information about creating this account, see Create a Domain Service Account to Run Active Directory Connector.
Select Run Service as LocalSystem if you use a single domain and you are planning on installing the Active Directory Connector on Domain Controllers only not member servers.
Note: The Active Directory Connector can only be installed on a full Read-Write Domain Controller.
On the Select Port for Desktop SSO dialog, provide the port used for Desktop SSO.
If you're not using Desktop SSO, accept the default port number of 8080.
If you use Desktop SSO with a single Active Directory Connector instance, in most cases, accept the default port number of 8080.
Set the Active Directory Connector to use a different port if there's a firewall or port conflict. If you do, open any server-based firewalls for inbound connections to that port.
If you are using Desktop SSO with multiple Active Directory Connector instances for load-balancing, set the port to 443, which supports SSL.
On the Select Shard page, select the location (US or EU) of the OneLogin database for your account.
If your organization is headquartered in the US, your OneLogin database shard is likely located in the US. For orgs headquartered in the EU, your OneLogin database shard is likely located in the EU. For other locales, or if you have any doubt, please contact your OneLogin representative for confirmation.
On the Ready to install OneLogin Active Directory Connector page, click Install.
When the installation is complete, the wizard prompts you to click Finish to exit the installer.
You have the option to launch the Domain Configuration wizard, which enables you to select the domains that the Active Directory Connector syncs with OneLogin, and enables you to select which universal security groups sync with OneLogin. You can run the Domain Configuration Wizard at any time by launching ADConfigWizard
from the Active Directory Connector installation directory.
See (Optional) Select Domains and Security Groups to synchronize with OneLogin.
Once the installation is complete, the service runs under the domain service account.
If you don't implement Desktop SSO, disable the Windows Host Firewall Rule for Port 8080.
Active Directory Connector opens a Windows Host Firewall Rule for Port 8080 (or the port you specified in step 7). This rule is used for Windows Domain Authentication.
For more information, see Configure Windows Domain Authentication Using Active Directory Connectors.
Once you have completed the installation, the Active Directory Installation Wizard will automatically progress to its second stage: Import Users
Select the OUs and/or Domains you wish to synchronize with. Click Finish.
To initialize the first synchronization click on the More Actions menu and select Synchronize Users. Users 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 Active Directory and OneLogin.
Complete the steps below to finish this configuration.
Before you complete the configuration steps described in this article, install at least one Active Directory Connector.
Go to Users > Directories and select the directory.
Verify that the Active Directory Connector instance is successfully connected.
By default, OneLogin provides key directory attributes imported from Active Directory to OneLogin during sync. Default mappings for these Active Directory fields, to the OneLogin fields, hold the synchronized values. Add and set additional 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.
In addition to the default mappings listed on this tab, OneLogin also syncs the following fields from Active Directory to OneLogin.
Active Directory Field | OneLogin Field |
company | Company |
department | Department |
manager | Manager |
manager's objectGUID | manager_guid |
objectGUID | Object GUID |
title | Title |
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 more information, see Custom User Fields.
On the Directory Attributes tab, click the Add Attribute 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 to select the custom field from the OneLogin Field drop-down.
You can use custom attribute mappings to import and export the manager field between OneLogin and AD/LDAP.
To import the Manager field, set Manager by distinguished name.
To export the Manager field, create a new mapping macro {manager_distinguished_name}.
Go to the OU Selection tab to select the AD organizational units to import into OneLogin.
The tab displays your domain's Base DN in the format DC=yourcompany, DC=com.
Select the plus button to expand the tree. Initially, only the top level node is displayed. After you select OUs and save, 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 screenshot below displays the default tree view.
Below, the tree is expanded after clicking the bottom ellipsis button (in line with the Stor node).
Note: All of the siblings of the Stor node are displayed.
Go to the Advanced tab to set granular Active Directory Connector settings.
(OBSOLETE) Base DN: If 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. Used with ADC Version 3.x which is no longer supported
Mappings: Toggle 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: 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 approval steps. If this option is on, imported users are listed as Unapproved in Users > Users. You can activate users individually on the user detail page, or approve the unapproved users by clicking More Actions and select Approve all users from the drop-down menu.
Sync User Status from Active Directory: Select to ensure users disabled in AD are disabled in OneLogin. This deprovisions users from apps.
(OBSOLETE) Ignore computed user access control: Select to inform OneLogin not to use the Computed User Access Control attribute (msDS-User-Account-Control-Computed) in Active Directory to determine if a user should be locked out, based on Group Policy. Used with Windows Server 2003 which is no longer supported.
Enable Smart Password: Select if you migrate an LDAP directory to this Active Directory instance. This setting also captures user LDAP passwords in Active Directory without requiring a password reset.
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 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 multiple Active Directory Connectors are configured for this Active Directory instance 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 Install Additional Active Directory Connectors for High Availability.
Login username attribute: Select the attribute to map to the username attribute. The username attribute is 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.
Exporting users: Select to export user attributes from OneLogin to Active Directory. To export user attributes to AD, switch the sync direction for each attribute on the Directory Attributes tab.
Deleted users in AD...: Select an what action occurs when users are deleted in Active Directory or when a user is removed from scope (for example, removed from an OU set to synchronize with OneLogin):
Account owners aren't suspended or deleted regardless of what action is selected. Account owners can be prevented from logging if authenticated by Active Directory and the AD account was deleted. For this reason, Account Owner accounts shouldn't authenticated against external directories like Active Directory.
Enforce OneLogin password expiration policies: Enable Active Directory to maintain OneLogin's policy-based password expiration settings, if the OneLogin policy is more restrictive. If this setting is enabled, the most restrictive password policy is applied: if OneLogin's password expiration interval is less than Active Directory's interval, then the OneLogin setting is applied.
Do not write user status back to Active Directory: If checked then OneLogin doesn't write back user status to Active Directory. If this is checked, 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.
You're prompted to launch the Domain Configuration wizard at the end of installation. Select the domains & security groups to sync with OneLogin using the Active Directory Connector.
You can open the Domain Configuration Wizard at any time by launching ADConfigWizard from the Active Directory Connector installation directory.
On the Domains tab, select the domains to sync with OneLogin. Expand a node to select specific domains. Select Show unselected domains to view all domains. By default, all domains are selected.
On the Security Groups tab, select security groups to synchronize with OneLogin. By default, all security groups are synchronized. Once you add one security group to the tab, the others security groups are excluded from synchronization, unless added.
Note: If you select a security group with child security groups, the members of the child security groups synchronize with OneLogin.
To deploy a proxy server that manages network traffic to and from your Active Directory server, configure the settings below. Install the Active Directory Connecter before you configure proxy settings.
Note: If you use Windows Domain Authentication with Active Directory Connectors, the traffic travels between the browser and Active Directory Connector. It doesn't pass through the HTTP proxy.
Log in to the Active Directory host as the OneLogin Service Account, which is the account used on the Service Log On Credentials page when you installed ADC.
Go to the Control Panel and select Network and Internet.
Click Internet Options to open the Internet Properties dialog.
On the Connections tab, click LAN settings.
On the Local Area Network (LAN) Settings dialog, select Use a proxy server for your LAN.
Enter your proxy server settings; use the Advanced option if required.
It's highly recommended that you install multiple Active Directory Connector instances for each domain.
For instructions, see Install Additional Active Directory Connectors for High Availability.
If you use Windows Domain Authentication with multiple Active Directory Connector instances for load balancing, enable SSL for each instance.
For instructions, see Enable SSL for Active Directory Connectors.