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.
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.
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: ADC 5 requires Windows Server 2012 r2 and above on the ADC host machine. If you're running an earlier version of Windows Server, you must use the most recent version of Active Directory Connector 4. Not all features described here may be supported by ADC 4.
Configuring Windows Domain Authentication
Preparing Your Browsers
Windows New Technology LAN Manager (NTLM) must be enabled for all browsers using WDA.
Edge supports NTLM and Kerberos with IWA by default; no additional configuration is required.
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.
- Create a dedicated shortcut for your Chrome browser.
- Right-click on the shortcut and select Properties.
- In the Shortcut tab, add
--auth-server-whitelist="IWA-hostname.host-domain.com" to the end of the Target field and click OK.
In Firefox, you must ensure that the configuration is in HTTPS mode to avoid a user transition warning:
- In the address bar, enter
about:config and accept the warning to proceed.
- 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.
- 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.
- Log in to the host as a local administrator.
- Stop the OneLogin Active Directory service.
- Edit the file
C:\Program Files (x86)\OneLogin, Inc\OneLogin Active Directory Connector\ConnectorService.exe.config to add this text after the last
<setting name="UseKerberosUnderSSO" serializeAs="String">
- 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.
- If you encounter any issues with your Kerberos configuration, consult Troubleshooting Windows Domain Authentication With Kerberos Configured.
Installing Your Active Directory Connectors
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
If you're installing multiple connectors (recommended), add them as described in Installing Additional Active Directory Connectors for High Availability.
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:
||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.
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.
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.
Auto Create New Users
||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.
||Select this option to automatically apply any mappings you've configured to these newly created users.
||Select the role that you'd like to be applied to automatically created users.
Connecting Your Redirect URLs
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.
For each AD Connector instance you have configured:
- Verify that Authentication & Desktop SSO is toggled on to display a green checkmark.
- 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.
- Click Continue.
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.
In GPMC, right-click your group policy and select Edit....
Expand the navigation tree down to Computer Configuration > Policies > Administrative Templates > Windows Components > Internet Explorer > Internet Control Panel > Security Page
Open the Security Page's Site to Zone Assignment List.
Select Enabled, then click Show... in the Options: pane.
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.
Click OK in both this dialogue and the Site to Zone Assignment List to return to your group policy editor.
From Security Page in the navigation tree, open Intranet Zone and select Logon options from the main pane.
Select Enabled. Under Options: select Automatic logon with current username and password.
Click OK to return to your group policy editor.
Expand the navigation tree to open your domain. In the Linked Group Policy Objects tab, right-click the group policy row and select Enforced.
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
Return to Authentication > Windows Domain Authentication and select Enable.
Save your WDA configuration and stop/restart each ADC instance being used.
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
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.