This article describes how to install and configure Active Directory Connector 4.x. The latest version of Active Directory Connector is version 5, which requires Windows Server 2012 r2 and above on the connector host. If you choose to run an earlier version of Windows Server on the connector host, you must use Active Directory Connector 4. For more information about Active Director Connector 5, see Installing Active Directory Connector 5.
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 Desktop SSO implementation.
The ideal implementation of Active Directory Connectors is to install and configure a minimum of three Active Directory Connector instances to provide load balancing and failover. The instructions that follow explain how to install one Active Directory Connector instance. For more information about how to install additional Active Directory Connector instances for load balancing and failover, see Installing Additional Active Directory Connectors for High Availability.
This article provides a full explanation of the Active Directory Connector installation process, but for a quick overview, check out this video:
- .NET 3.5 Framework (no other versions are supported)
- Windows Server 2008+, 2012+. (Core editions are currently not supported, but the service can be installed on any domain member server in your network).
- Windows Server 2003 end of life was July 14, 2015. It is no longer supported. Microsoft EOL announcement & upgrade path.
- Pentium 4 Processor or better
- 512 MB RAM
- 120 MB Available hard drive space (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.
- A supported web browser
OneLogin Account Password Settings
Before you install and configure your Active Directory Connectors, you should be aware of the Account Settings that affect the way OneLogin handles Active Directory passwords. These include:
- Enable directory fallback password cache: Enabled by default. Caches a hash of the user's AD password so that OneLogin can authenticate a user using 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 the SSO password for app authentication.
For more information, see Account Settings for Account Owners.
DMZ Installation Requirements
Installing an OneLogin Active Directory Connector in the DMZ only requires a handful of ports. However, the Active Directory Connector must be installed on a Microsoft Windows Server that is connected to the Windows Domain Controller. Microsoft provides the required network port communication for connecting through a firewall.
Microsoft Network Requirements:
OneLogin Network Port Requirements:
TCP/UDP – 389
TCP/UDP – 636
TCP/UDP – 88
TCP/UDP – 464
TCP/UDP – 53
Installation and setup
To set up an Active Directory Connector, you perform the following tasks:
- Download the Active Directory Connector installer
- Install the Active Directory Connector
- (Optional) Run the Domain Configuration wizard
- Add additional Active Directory Connector instances for load balancing and failover
- (Optional) Enable SSL for each Active Directory Connector instance (only if you use Desktop SSO and have multiple Active Directory Connector instances for load balancing)
- Configure the Active Directory Connector integration
Download the Active Directory Connector installer
- On a machine on the same local network as the Active Directory host, log in to OneLogin, go to Users > Directories, and click New.
Select Active Directory from the list of available directory types.
This launches the Active Directory Setup wizard.
- Name your directory (OneLogin supports simultaneous integration of multiple directories, each having a different name).
Download the Active Directory Connector installer.
You will install the connector on a server on the same network as your Active Directory service.
Copy the installation token.
You will provide the token to the Active Directory Connector when you install it.
Install the Active Directory Connector
Sign in as an administrator on the machine that will host your Active Directory Connector.
Your account should have the privileges required to start system services.
Important! If you install the Active Directory Connector on the machine that hosts the primary domain controller (PDC), you may see poor performance. We recommend that you install the Active Directory Connector on a member-server machine on the same physical network as the PDC.
Run the Active Directory Connector installer.
This is the installer that you downloaded from the Active Directory Setup wizard or, if you are adding an additional authentication-only Active Directory Connector instance, from the Active Directory Connector configuration dialog.
- On the Welcome page of the OneLogin Active Directory Connnector Setup installer, click Next.
- On the End-User License Agreement page, read and accept the license terms and click Next.
On the Connector Token page, paste the token that you copied from the Active Directory Setup wizard.
If you are adding an additional authentication-only Active Directory Connector instance, this is the token that you copied from the Active Directory Connector configuration dialog.
On the Service Log On Credentials page, provide the domain and account that you will use to run the Active Directory Connector.
You have the following choices, depending on your current system setup:
If you are upgrading an existing Active Directory Connector, you will be prompted to Use existing OneLogin Service Account (recommended).
We recommend that you select this option if you are upgrading. After you select it, click Next.
If no Active Directory Connector is currently installed on this machine, you will be prompted to Create a OneLogin Service Account (recommended).
We recommend that you select this option for new Active Directory Connector installations. It creates a domain service account named OneLoginADC that has privileges to read the directory tree throughout your Forests and Domains and has the ability to change and reset passwords. Follow the prompts to create the service account. Click Next when you are done.
If no Active Directory Connector is currently installed on this machine, and you want to use an existing domain service account, select Run service as: and enter the domain and account that you will use to run the Active Directory Connector.
This must be a domain service account that has privileges to read the directory tree throughout your Forests and Domains and has the ability to change and reset passwords. For more information about creating such an account, see Creating a Domain Service Account to Run Active Directory Connector.
Click Next when you are done.
If you are using a single domain, select Run Service as LocalSystem and click Next.
Note that if you are using a Read-Only Domain Controller, you will not be able to change any passwords if the Active Directory Connector is configured to run as a local system.
On the Select Port for Desktop SSO page, provide the port that will be used for Desktop SSO.
If you are not going to use Desktop SSO, accept the default port number of 8080 and click Next.
If you are using Desktop SSO with a single Active Directory Connector instance, in most cases you should accept the default port number of 8080 and click Next.
You can also 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, you must 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 most likely located in the US. If your organization is headquartered in the EU, your OneLogin database shard is most 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 completed, the wizard lets you know and prompts you to click the Finish button to exit the Setup Wizard.
At this time you also 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 also enables you to select which security groups will sync with OneLogin. If you choose not to launch the Domain Configuration wizard at this time, you can run it any time you want by launching ADConfigWizard from the the Active Directory Connector installation directory.
If you are not implementing 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 only for Desktop SSO.
For more information, see Configuring Desktop SSO Using Active Directory Connectors.
(Windows Server 2012 R2 and above) Install the intermediate Certificate Authorities used to sign the OneLogin SSL certificate.
See "Invalid Certificate Chain" in Troubleshooting the Active Directory Connector.
After you finalize the installation, the service should be running under the domain service account. The next steps walk you through the completion of the setup.
(Optional) Select Domains and Security Groups to synchronize with OneLogin
At the end of the installation, you'll be prompted to launch the Domain Configuration wizard. This enables you to select the domains that the Active Directory Connector syncs with OneLogin, and also enables you to select which security groups will sync with OneLogin.
You can also access this wizard can by launching ADConfigWizard from the the Active Directory Connector installation directory.
On the Domains tab, you can select the domains that contain the users you want to synchronize with OneLogin. Expand a node to select specific domains. You can view all domains (select Show unselected domains) or only selected domains (default). By default, all domains are selected.
On the Security Groups tab, select the security groups that contain the users you want to synchronize with OneLogin. By default, all security groups are synchronized. Once you add one security group to the tab, all others are excluded from synchronization unless you add them.
Note. If you select a security group that has child security groups, the members of the child security groups will also be synchronized with OneLogin.
Click OK to save your changes.
Install additional Active Directory Connector instances for load-balancing and failover
You can--and should--install multiple Active Directory Connector instances for each domain.
For instructions, see Installing Additional Active Directory Connectors for High Availability.