Rules Best Practices

Creating a Test Active Directory Domain Controller

Auth0's AD/LDAP integration is relatively easy to set up, but it does require that you have access to an existing AD service and sufficient privileges to install and configure the Connector. What if, however, you'd just like to try out the Connector or set up a dev/test environment? The following steps guides you in creating a minimal AD Domain Controller installation on a cloud-deployed virtual machine for these purposes.


Create a New Windows Server VM on Azure

You can run your VM on any cloud platform, but this guide will walk through how to set one up on Microsoft Azure.

  1. If you don't have an account with Azure, create one before proceeding.

  2. Log into the Azure Management console.

  3. At the bottom left corner, click NEW, then COMPUTE > VIRTUAL MACHINE > QUICK CREATE

  4. Complete the form:

    • Choose a DNS name. Example: auth0-test-ad
    • Image: Windows Server 2012 R2 Datacenter
    • Size: D1
    • User name: ad-admin
    • Password: (generate your own secure password)
    • Region: (your choice)
  5. Click the CREATE A VIRTUAL MACHINE button. It will take a few minutes for the VM to provision.

  6. Click on the ENDPOINTS tab of the new VM, and take note of the PUBLIC PORT for the Remote Desktop endpoint.

  7. Open up Microsoft Remote Desktop client (Windows or Mac) or the client of your choice (such as rdesktop for Linux systems). Create a new connection to your VM:

  8. Open the connection, disregarding any certificate warnings presented by the Remote Desktop client. You should be logged in automatically and eventually see a desktop that looks like this:

  9. If you're prompted to find PC's, devices, and content on the local network, choose No.


Install Active Directory Domain Services

  1. Click the PowerShell icon in the Windows Task Bar to open the PowerShell Command Prompt.

  2. Install Active Directory Domain Services (ADDS) using this command:

    Note that the Install-windowsfeature command first became available in Windows Server 2012. In Windows Server 2008, the equivalent command was Add-windowsfeature (See MSDN for more information).


Promote the Server to a Domain Controller

  1. Promote the server to a domain controller that manages a FQDN of mycompany.local:
  2. When prompted for the SafeModeAdministratorPassword, enter the Administrator password you used when creating the VM.
  3. You will also be prompted to confirm whether or not you want to continue. Click Enter to do so. The promotion script will run and the VM will automatically reboot.


Add Test Groups and Users

  1. Once the VM finishes rebooting, log in to the VM using the Remote Desktop client.
  2. Open the PowerShell Command Prompt.
  3. Run the following script, which will:
    • Create two groups: Accounting and IT
    • Create two users: Bob Johnson and Mary Smith
    • Add Bob to the Accounting group and Mary to the Account and IT groups

npm modules

Install and Configure the AD/LDAP Connector

  1. Using the Auth0 Management Dashboard, create a new Active Directory/LDAP connection with the name auth0-test-ad by following these steps.

    Be sure to copy the Ticket URL that is generated at the end of those instructions.

  2. On the VM, disable Internet Explorer Enhanced Security Configuration.

  3. Open Internet Explorer with the Ticket URL you saved in step 1.

  4. Follow the instructions in the browser to download, install, and configure the Connector. When you are prompted for the LDAP service account, use the admin account you created for the VM:

    • Username: mycompany\ad-admin
    • Password: (same as before)
  5. When you're done configuring and installing the Connector, reboot the server.

  6. Log back into the VM using Remote Desktop.

  7. Open the Connector configuration site by navigating to http://localhost:8357/.

  8. Check that the Connector is able to find a user:

    • Click on the Search tab.
    • Under "Find User by Login", type mary.smith.
    • Click Search. You should get JSON back that contains that user's AD profile data:

Environment variables

Test an Authentication Flow from Auth0

To ensure that everything is working using your Auth0 account, we're going to configure your Default App in Auth0 to use your new Active Directory / LDAP Connection, and use the /authorize endpoint to initiate an authentication flow.

  1. Using the Auth0 Management Dashboard, navigate to your Applications.

  2. Click the Settings icon of your Default App

  3. Add to the list of the Application's Allowed Callback URLs.

  4. Click the Connections tab.

  5. Under Enterprise, enable the auth0-test-ad Active Directory / LDAP connection.

  6. Test the authentication flow by opening the following link in your browser:

  7. Log in with one of the test users that was created in the directory:

    • Username: mary.smith or bob.johnson
    • Password: Pass@word1!

  8. If everything is working, you should be redirected to the website to see the contents of the resulting JWT: