Configure AD/LDAP Connector Authentication with Kerberos

You can federate with Active Directory through the AD/LDAP Connector. The AD/LDAP Connector enables your users to authenticate when they are on a domain-joined machine within the corporate network.

Configure Active Directory

1. Go to Auth0 Dashboard > Authentication > Enterprise > Active Directory/LDAP, and select the connection you want to configure.
2. Enable the Use Windows Integrated Auth (Kerberos) switch.

Auto-detected range for Kerberos

When Kerberos authentication is enabled, the visible IP address of the server where the AD Connector is running is implicitly added to the network IP range. This means that if a user’s requests originate from the same visible IP address as that of the AD Connector, then Kerberos authentication will be attempted.

1. Configure the IP Ranges. Use CIDR-notation. These should be ranges that are visible by Auth0. When Auth0 is running in the cloud, it won’t be able to see your user’s internal IP address. In that case you’d configure the public facing/WAN IP address(es) of your company.
2. We recommend restarting the Windows Service that hosts the AD Connector every time this setting is changed. This way, changes will take effect immediately.

Authentication flow

Depending on the users’ location, the authentication flow will be different when IP ranges are set. Using Fabrikam as an example, since it uses the SaaS version of Auth0, they configured their Public IP Address (24.12.34.56/32) in the connection. Users connecting from within the building will all originate from 24.12.34.56 (as configured on the connection). When they authenticate, the users can follow the AD/LDAP native flow and have a seamless SSO experience.

For this to work, the network must allow the users to connect to the AD/LDAP Connector on the port configured in the config.json file. In highly available deployments of the Connector, the address users will be connecting to is the network load balancer in front of all connectors instances.

To learn more, read Deploy AD/LDAP Connectors for High Availability Environments.

On the other hand, when users are not in the corporate network (for example, at a customer site, working from home without VPN) they won’t be able to access the AD/LDAP Connector directly. The users will need to enter their username/password, and Auth0 will validate these credentials with the AD/LDAP Connector (which will in turn use Active Directory to validate those credentials).

Auto-login with Lock

Detecting IP ranges in an AD/LDAP connection and using those ranges with Lock to allow integrated Windows Authentication is a feature that works in Lock 10, but can only be used in Lock 11 in Universal Login scenarios. This feature is disabled in Lock 11 when Lock 11 is used in Embedded Login scenarios.

When an application is using Lock 10 or 11 within the Login Page hosted by Auth0 (typically used for SAML/WS-Federation protocols and Single Sign-on (SSO) Integrations), there will be a button which allows users to authenticate using “Windows Authentication”.

In some cases the requirement could be to automatically sign in the user if Kerberos is possible (based on the IP-address of the end user). The following changes can be added to the Auth0 Login Page to automatically sign in the user if Kerberos is possible:

<script src="https://cdn.auth0.com/js/lock/11.x.x/lock.min.js"></script>
<script src="https://cdn.auth0.com/js/auth0/9.x/auth0.min.js"></script>
<script src="https://cdn.auth0.com/js/polyfills/1.0/object-assign.min.js"></script>

<script>
  var config = JSON.parse(decodeURIComponent(escape(window.atob('@@config@@'))));

  var lock = new Auth0Lock(config.clientID, config.auth0Domain, {
      //...additional configuration
  });

  function handleError(err) {
    // add proper error handling
    console.log(err);
  };

  var params = Object.assign({
      scope: config.internalOptions.scope,
      _csrf: config.internalOptions._csrf,
      state: config.internalOptions.state,
    },
    {
      /* additional configuration needed for use of custom domains 
      overrides: {
        __tenant: config.auth0Tenant,
        __token_issuer: '{yourCustomDomain}'
      }, */
      domain: config.auth0Domain,
      clientID: config.clientID,
      redirectUri: config.callbackURL,
      responseType: 'code'
    });

  var webAuth = new auth0.WebAuth(params);

  /*
   * Verify if Kerberos is possible, if it is, try to authenticate the user.
   *
   * the response from getSSOData will only have a connection and strategy if 
   * the IP address is within the Kerberos range in the connection's settings
   */
  webAuth.client.getSSOData(true, function(err, data) {
    if (err) handleError(err);

    if (data.connection && data.strategy === 'ad') {
      webAuth.authorize({connection: data.connection}, function(err) {
        if (err) handleError(err);
      });
    } else {
      lock.show();
    }
  });
</script>

Bypass Kerberos at runtime

You can prevent Kerberos from being used, even if the user is logging in from an IP address within the range configured in the connection’s settings, by passing rememberLastLogin: false to lock.show().

function useKerberos() {
      // return true to use Kerberos, false to bypass
    };
    
    lock.show({rememberLastLogin: useKerberos()});

Enable Kerberos request logging

1. To enable verbose logging of Kerberos requests, add a system level environment variable DEBUG=kerberos-server.
2. Restart the Connector.
3. Log in again and check the logs for more information.

Firefox support for Kerberos

By default, Firefox rejects all “negotiate” requests required to authenticate users with Kerberos. If you wish to use Firefox with Kerberos, you need to AllowList the server where the connector is installed.

1. Open a Firefox tab and type about:config in the address bar.
2. Dismiss any warning message, and in the search box type negotiate.
3. Locate the network.negotiate-auth.trusted-uris item and double click to change its value.
4. Type the domain name of the server where the connector is installed. If you have multiple instances of the connector behind a load balancer, add the dns name of the balancer. The value accepts a comma-separated list of URL prefixes or domains in the form of mydomain.com, https://myotherdomain.com.
5. Click Ok. You don’t need to restart the server for the changes to take effect.

HTTPS support for Kerberos

Kerberos authentication works over HTTP (not HTTPS). Microsoft Office 365 and other modern products might not work with HTTP.

To resolve this limitation:

1. Set up a reverse proxy and expose the AD/LDAP Connector on an HTTPS domain. You can use the SERVER_URL (Front Facing URL) parameter to publish the public location where the AD/LDAP Connector will be listening to incoming requests.
2. Map the SERVER_URL in the reverse proxy to all internal instances of the deployed connectors.