Active Directory Connector 5 brings significant performance improvements, firewall-friendliness, and support for HTTP proxy servers. If your HTTP proxy server requires authentication, Active Directory Connector 5 provides it using Windows domain authentication.
Note. Active Directory Connector 5 must be installed on a host running Windows Server 2012 r2 and up. If you choose to run an earlier version of Windows Server on the connector host, you must use Active Directory Connector 4.
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. For an overview of Active Directory Connector load balancing and failover, see Installing Additional Active Directory Connectors for High Availability. The instructions that follow in this article cover 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.
This article covers the following topics:
- Windows Server 2012 r2+
Note. While Active Directory Connectors must be installed on machines running Windows Server 2012 r2+, they can support domain controllers running on earlier versions of Windows Server.
- .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.
- 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 (perimeter network) 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.
For more information, see https://technet.microsoft.com/en-us/library/dd772723(v=ws.10).aspx.
OneLogin Network Port Requirements:
TCP/UDP – 389
TCP/UDP – 636
TCP/UDP – 88
TCP/UDP – 464
TCP/UDP – 53
The upgrade process is different for:
- Upgrading from an earlier version of Active Directory Connector 5 to the current version
- Upgrading from Active Directory Connector 4.x to Active Directory Connector 5.x
From an earlier version of Active Directory 5
To upgrade from an earlier version of Active Directory Connector 5, you must download the latest installer and re-run it for each instance, following the instructions in Installation and Setup. The installer will copy your existing installation token and configuration; accept the defaults presented by the installer.
From Active Directory Connector 4.x to Active Directory Connector 5
To upgrade from Active Directory Connector 4.x:
Copy your installation token for each instance.
You will use these tokens when you install Active Directory Connector 5.
Log into OneLogin as an admin and go to Users > Directories.
Select your Active Directory configuration.
On the Connector Instances tab, click an Active Directory Connector instance row to open the connector details dialog.
On the connector details dialog, copy the Installation Token.
Uninstall your Active Directory Connector 4.x instances.
Assuming that you're using multiple Active Directory Connectors for load-balancing and failover, we recommend that you uninstall and upgrade standby or authentication-only instances before you uninstall and upgrade your authentication + synchronization (active) instance. This will limit any down time.
Install Active Directory Connector 5.x on each of the machines that hosted Active Directory Connector 4.x, using the tokens that you copied in step 1.
Use the Installation and setup instructions that follow, making note of the following:
Unless you also want to install new connector instances or change your Active Directory Connector configuration, you only need to perform task 1 (Download the installer) and task 3 (Install the Active Directory Connector).
If you want to select domains and security groups to sync with OneLogin, you must also perform task 4 (Run the Domain Configuration wizard).
- If you want to install behind a proxy server, you must also perform task 5 (Configure proxy settings).
Installation and setup
To set up an Active Directory Connector, you perform the following tasks:
- Download the Active Directory Connector installer
- Get the installation token
- Install the Active Directory Connector
- (Optional) Run the Domain Configuration wizard
- (Optional) Configure proxy settings
- (Optional) 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
1. Download the Active Directory Connector installer
Download the installer here: onelogin_ad_connector.msi
You can also download release notes.
2. Get the installation token
For new installations (not upgrades that use the same installation token):
Log in to OneLogin 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.
- Name your directory (OneLogin supports simultaneous integration of multiple directories, each having a different name).
Do NOT download the installer here; the Active Directory Connector 5 installer is not available on this page.
Copy the installation token.
You will provide the token to the Active Directory Connector when you install it.
3. Install the Active Directory Connector
You should install the connector on a server on the same network as your Active Directory service.
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.
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.
Run the Active Directory Connector installer.
This is the installer that you downloaded above.
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 upgrading an existing Active Directory Connector instance or 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 has been 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 has been 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 complete, the wizard lets you know and prompts you to click the Finish button to exit the installer.
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.
Install the intermediate Certificate Authorities used to sign the OneLogin SSL certificate.
See "Invalid Certificate Chain" in Troubleshooting the Active Directory Connector.
- Restart the AD Connector service.
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.
4. (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.
5. (Optional) Configure proxy settings
If your company wants to use a proxy server to manage network traffic to and from your Active Directory server, perform the following settings after you install your Active Directory Connector.
Note. If you are using Desktop SSO with Active Directory Connectors, the Desktop SSO traffic travels only between the browser and the Active Directory Connector. Therefore it will not pass through the HTTP proxy.
Log in to the Active Directory host as the OneLogin Service Account.
This is the account that you created or entered on the Service Log On Credentials page when you ran the installer.
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.
Click OK on the LAN Settings dialog and the Internet Properties dialog.
6. (Optional) 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.
7. (Optional) Enable SSL for each Active Directory Connector instance
If you use Desktop SSO and have multiple Active Directory Connector instances for load balancing, you must enable SSL for each instance.
For instructions, see Enabling SSL for Active Directory Connectors.
8. Configure the Active Directory Connector
Once you have installed your Active Directory Connector, you must go to the OneLogin admin portal to configure it.
For instructions, see Configuring Active Directory Connectors.