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.
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 2008 R2 SP 1and above
Note. While Active Directory Connectors can 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.
- If using domain whitelisting, ensure smux.us.onelogin.com is whitelisted (replaces adc.onelogin.com)
- 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 a 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
Install and Configure Active Directory Connector 5
|If you are upgrading you need to follow our upgrade guide here|
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 the simultaneous integration of multiple directories, each having a different name).
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 Connector 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 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 by launching ADConfigWizard from 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.
Upgrade to Active Directory Connector 5
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 Connector 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.
Note: We discourage copying ADC config files when you upgrade or install the AD Connector. Configuration settings often change when a new version of the AD Connector is released. Follow the instructions outlined in the AD Connector Upgrade Documentation to upgrade your version of the connector. If a specific setting fails to migrate after the upgrade, you need to manually merge it.
Upgrade Active Directory Connector 4.x to Active Directory Connector 5
Follow these instructions to upgrade from Active Directory Connector 4.x to 5:
Note: Windows Server 2008 R2+ is required to run ADC version 5.
Prior to performing the upgrade, you'll want to take the following into consideration if you are using any of the advanced features bulleted below. If you are, then you will need to make note of the advanced features and verify they are present or add them to your upgraded ADC 5 installation after it completes the installation wizard. We recommend saving a copy of your existing config file on your desktop so you can refer to it later if necessary. The config file is located at:
C:\Program Files (x86)\OneLogin, Inc\OneLogin Active Directory Connector\ConnectorService.exe.config
1) Desktop SSO and Logging Configurations
C:\Program Files (x86)\OneLogin, Inc\OneLogin Active Directory Connector\ConnectorService.exe.config
- Search the file for the section HttpListenerUrls then note the port number listed within the <string> tag as highlighted in the screenshot. If your current ADC makes use of a non-default port (any port number other than 8080 or 443), make note of the value as you will need to enter this port in the installation wizard when prompted.
If the value is 443 then your current ADC has SSL enabled and you will need to enter port 443 in the installation wizard when prompted.
- Next, search for UseKerberosUnderSSO section. If you find this entry then your ADC currently has Kerberos enabled (this is not enabled by default) and you will need to add this string back to your config file after upgrading.
- Next, search for the section RollingFileAppender and check the values in your config file against the ones noted in the screenshot below. The below screenshot is the default setting and not customized. If you have values listed that differ from the screenshot, then you have Customized Active Directory Connector logging enabled and will need to re-enter these settings in the config file after you upgrade.
2) Lastly, navigate to the domaincache file located at the following location:
- If you have a hardcoded primary Domain Controller IP Address as indicated by the highlighted value in the screenshot then make note of this value. You will need to input this value into the new domaincache file after you upgrade.
Installation of Active Directory Connector 5
Note: In your OneLogin instance, it is not recommended to run Active Directory Connectors 4.x and 5.x simultaneously and connect to the same instance of Active Directory.
Go to the Users menu > Select Directories > Select your Active Directory instance
Click on the + button to add a new Active Directory Connector 5.x instance.
Name the new Active Directory Connector instance.
Open the new ADC instance and copy the new Installation Token in the dialog. Click the Download button.
- On Active Directory Connector host, first perform an uninstall of the existing Active Directory Connector 4.x via Programs and Features.
- Run installation wizard
If you want to install behind a proxy server, you must also perform task 5 (Configure proxy settings).
(If using Desktop SSO with SSL): Update your certificate binding with the new App ID and Desktop SSO Redirect URL
- If any Desktop SSO, Logging, or Primary Domain Controller configurations were identified, apply to new ADC instance as noted above.