This site requires JavaScript to be enabled
External Customer KB > General > Configuring Windows Domain Authentication with Active Directory Connectors
Configuring Windows Domain Authentication with Active Directory Connectors
Article: KB0010313 Published: 02/23/2024 Last modified: 02/23/2024

Windows Domain Authentication (WDA), previously known as Desktop Single Sign-On or Desktop SSO, allows your users easy access to OneLogin from devices that you've approved. When a user is signed in to a properly configured workstation as part of an Active Directory (AD) domain and uses their browser to visit OneLogin, they're automatically signed in using Integrated Windows Authentication (IWA) and taken directly to their OneLogin apps without the need to enter their username and password.

Depending on your organization's needs, you may also consider using OneLogin Desktop. From the user's perspective, the passwordless experience of automatic authentication with either WDA or OneLogin Desktop is nearly identical, but there are key differences on the backend:

  • WDA is a server-based solution freely supported by all OneLogin accounts, but requires domain-joined workstations.
  • OneLogin Desktop is a paid software that must be installed on all client devices using it, but bypasses the need for an Active Directory domain.
Configuring Windows Domain Authentication

Check out our 3-part video training course for a deeper understanding of OneLogin's Windows Domain Authentication feature.

Watch Now

 


 

Overview

The typical WDA implementation uses OneLogin's Active Directory Connector (ADC) to manage authentication requests from OneLogin. Authentication requests are redirected from OneLogin to an ADC instance, which uses IWA to validate the user's credentials against Active Directory and sign the user into OneLogin using JSON Web Tokens (JWT).

Because you can configure multiple ADC instances for any Active Directory domain, authentication requests can be load-balanced for high availability. We recommend this, as the more host computers you have the ADC software installed on, the more resilient your system will be to failovers and high-traffic demands.

Windows Domain Authentication Diagram

This article describes how to install new implementations or upgrade older WDA configurations to use Active Directory Connector 5 for the most secure, reliable, and user-friendly experience.

Note: The OneLogin Active Directory Connector must be installed on Windows Server 2012 R2 or later. As of April 3rd, 2024, no previous versions of Windows Server operating systems are supported for the OneLogin ADC.

 


 

Preparing Your Browsers

Windows New Technology LAN Manager (NTLM) must be enabled for all browsers using WDA.

Windows

Microsoft Edge

Edge supports NTLM and Kerberos with IWA by default; no additional configuration is required.

Google Chrome

Chrome supplies the NTLM token to approved sites provided as a parameter at browser startup. Without this parameter, the permission list includes Local Machine servers or Local Intranet security zone servers.

  1. Create a dedicated shortcut for your Chrome browser.
  2. Right-click on the shortcut and select Properties.
  3. In the Shortcut tab, add --auth-server-whitelist="IWA-hostname.host-domain.com" to the end of the Target field and click OK.
Mozilla Firefox

In Firefox, you must ensure that the configuration is in HTTPS mode to avoid a user transition warning:

  1. In the address bar, enter about:config and accept the warning to proceed.
  2. Locate the network.negotiate-auth.trusted-uris and network.automatic-ntlm-auth.trusted-uris preference fields. Double-click each and enter your OneLogin IWA server hostname(s), separated by commas.
  3. If you are not entering the fully qualified domain name (FQDN) of your host servers, you must toggle the Value column of network.automatic-ntlm-auth.allow-non-fqdn and network.negotiate-auth.allow-non-fqdn to True.

If your ADC hosts are SSL-enabled (recommended), you must also add security exceptions for their SSL certificates.

Mac OS X

Kerberos must be enabled for any browsers used on a Mac OS X device joined to your Windows domain. This is required for each ADC host machine in your implementation.

  1. Log in to the host as a local administrator.
  2. Stop the OneLogin Active Directory service.
  3. Edit the file C:\Program Files (x86)\OneLogin, Inc\OneLogin Active Directory Connector\ConnectorService.exe.config to add this text after the last </setting> tag:
    <setting name="UseKerberosUnderSSO" serializeAs="String">
    <value>True</value>
    </setting>
  4. Start the OneLogin Active Directory service. The ADC will register a Service Principal Name (SPN) entry in Active Directory for the http protocol under the machine that the connector is installed on and the service account that you have assigned to run it.
  5. If you encounter any issues with your Kerberos configuration, consult Troubleshooting Windows Domain Authentication With Kerberos Configured.

 


 

Installing Your Active Directory Connectors

  1. Install Active Directory Connector 5 on each member server you're using as an ADC host.

    Note: It is not recommended to install ADC on a domain controller. To best support SSL and load-balancing, only member servers should be used to host your ADC configuration.

    During installation, you're prompted to accept default port 8080. When enabling SSL, which is recommended for any installation and required if using multiple ADC instances, you should instead set this to port 443.

  2. If you're installing multiple connectors (recommended), add them as described in Installing Additional Active Directory Connectors for High Availability.

  3. Enable SSL for each ADC instance. This step is required if you've installed additional AD connectors, and highly recommended for all other configurations.

 


 

Configuring WDA in OneLogin

In your OneLogin admin portal, go to Authentication > Windows Domain Authentication and configure your WDA requirements:

Windows Domain Authentication

Basic Settings

Basic Settings

Enable

Leave this disabled until you have finished your configuration and are ready to activate WDA.

IP Addresses (required)

Enter the public IP addresses for any devices in your Windows domain that are permitted to access OneLogin through WDA. You can indicate individual IP addresses separated by spaces or a range of IPs connected by a hyphen. Users visiting your unique OneLogin subdomain from these addresses will be automatically redirected.

Ignore X-Forwarded-For header IP addresses

Select this option if you use a proxy and firewall service like Zscaler.

Global IP Addresses (legacy)

If you're installing a new implementation or upgrading a configuration created in 2016 or later, disregard this field.

If you're upgrading a configuration enabled prior to 2016, contact OneLogin Support and provide them with your public gateway network's IP addresses. After verifying your account ownership, the support representative will enter the IP addresses you provide, which will appear in this read-only field after saving and refreshing your configuration.

Include mobile devices

Select this option to redirect authentication requests initiated from mobile devices on your network. This is not typically recommended, as user mobile browsers must support IWA and are best to exclude from WDA. Contact OneLogin Support for guidance.

Include Mac devices

Select this option to redirect authentication requests initiated from domain-joined Mac OS X computers on your network that have had Kerberos enabled.

Honor user policy MFA configuration

Select this option to enforce any multi-factor authentication (MFA) requirements configured in your organization's user policies. Enabling this setting automatically disables Auto Create New Users.

Important: Users who have not previously registered any MFA devices will be unable to sign in with WDA if this setting is enabled. Be sure any users whose policy requires MFA have the opportunity to log in and configure a device prior to enabling. Otherwise, you may need to temporarily disable WDA to allow them access to configure their required MFA.

Authentication Endpoints

There are two ways to configure your authentication endpoints: with a directory connector (recommended for most configurations), or an IIS script.

Active Directory Connector

After selecting Active Directory Connector, a DSSO Directory(s) menu appears, providing all AD instances that have connectors configured. Select one or more directories to process WDA requests.

Enable this option if you're not sure which type of endpoint to select.

Authentication Endpoints - Active Directory Connector

Fixed URL for remote authentication script

While IIS was previously required for some Mac OS X implementations of earlier ADC versions, ADC 5 supports Mac devices without this requirement. Only enable this endpoint type if you're certain that a redirect script is necessary for your configuration, and contact OneLogin Professional Services for assistance with creating the script for new IIS implementations.

If your implementation was created prior to 2016, this option may be enabled by default. Otherwise, you may enable it to display additional options and a Remote Token to copy. Contact OneLogin Professional Services for more information.

Authentication Endpoints - Remote Authentication Script

Auto Create New Users

Enable

If this option is selected, then whenever a user previously unknown to OneLogin authenticates against Active Directory from your public gateway network's IP addresses, a corresponding user account will automatically be created in OneLogin. This is not typically necessary, but can be useful for correcting sync gaps between your directories.

Apply mappings

Select this option to automatically apply any mappings you've configured to these newly created users.

Default Role

Select the role that you'd like to be applied to automatically created users.

Auto Create New Users

 


 

Connecting Your Redirect URLs

  1. Save your WDA configuration, then either click Go to your active directory under Authentication Endpoints or navigate to Users > Directories and select your active directory.

    Active Directory
    Active Directory
  2. For each AD Connector instance you have configured:

    1. Verify that Authentication & Desktop SSO is toggled on to display a green checkmark.
    2. In the Desktop SSO Redirect Url field, enter the URL https://internal-FQDN:443/onelogin/idp, using the fully qualified domain name (FQDN) of the server where this connector was installed.

      Note: If you selected a different port number while installing the connector, replace 443 with the appropriate port.

    3. Click Continue.
    Edit AD Connector

 


 

Establishing Identity Passthrough

The best way to ensure that every workstation in this domain allows the user's Windows identity to pass through to their browser is by configuring a group policy to use your domain's intranet zone.

This section requires that your ADC host server is installed with Group Policy Management Console (GPMC) and has a group policy configured for your Active Directory domain.

  1. In GPMC, right-click your group policy and select Edit....

  2. Expand the navigation tree down to Computer Configuration > Policies > Administrative Templates > Windows Components > Internet Explorer > Internet Control Panel > Security Page

  3. Open the Security Page's Site to Zone Assignment List.

  4. Select Enabled, then click Show... in the Options: pane.

  5. For each ADC host, enter a Value name with the server's FQDN and a Value of 1 to indicate that it is using the intranet zone. You can list each host individually (https://host.subdomain.domain.com), or use a wildcard character (https://*.subdomain.domain.com) to include multiple hosts.

    Enter the zone assignments here
  6. Click OK in both this dialogue and the Site to Zone Assignment List to return to your group policy editor.

  7. From Security Page in the navigation tree, open Intranet Zone and select Logon options from the main pane.

  8. Select Enabled. Under Options:, select Automatic logon with current username and password.

  9. Click OK to return to your group policy editor.

  10. Expand the navigation tree to open your domain. In the Linked Group Policy Objects tab, right-click the group policy row and select Enforced.

  11. The group policy should update on all of your systems within approximately half an hour. To force an update, you can run gpupdate /force in the Command Prompt of any workstation.

 


 

Completing and Testing Your Configuration

  1. Return to Authentication > Windows Domain Authentication and select Enable.

  2. Save your WDA configuration and stop/restart each ADC instance being used.

  3. There are two ways to test your configuration:

    • Sign into an active directory workstation, open the browser, and visit https://your-subdomain.onelogin.com. You should be taken through one of the Redirect URLs defined for your ADC instances and land directly in your OneLogin portal without being prompted for login credentials.
    • Check that the AD Connector service has opened a listener at port you selected during your ADC installation (typically port 443) by running the command c:>netstat -a

 


 

Troubleshooting Tools

Bypassing Windows Domain Authentication

In some cases, such as when your OneLogin account is set up for a shared admin, it's necessary to bypass your WDA configuration. Use the bypass URL https://your-subdomain.onelogin.com/login?remote=off to prevent the automatic redirect and prompt for a traditional login instead.

Troubleshooting Active Directory Connectors

If you're experiencing connection, authentication, or syncing issues with your AD Connector, consult Troubleshooting the Active Directory Connector.


Expand/Collapse Comments
:     
Was this helpful?
YesYesNoNo