Configure Active Directory Integration

Integrate Active Directory with NGINX Controller for external authentication.

Overview

This topic explains how to add and manage an external Active Directory authentication provider. NGINX Controller supports unencrypted LDAP, LDAPS, and StartTLS.

Before You Begin

Install Active Directory Domain Forest

This guide assumes you’ve already installed an Active Directory Domain Forest. If you haven’t done that yet, refer to the following Microsoft topic for instructions:

Enable LDAP over SSL

If you’re using LDAPS or StartTLS, you need to enable LDAP over SSL with a certification authority. See the following Microsoft docs for guidance:

Additionally, make sure that you can connect to your Active Directory server from NGINX Controller.

 


Create an Active Directory Authentication Provider

Take the following steps to create an Authentication Provider:

  1. Open the NGINX Controller user interface and log in.
  2. Select the NGINX Controller menu icon, then select Platform.
  3. On the Platform menu, select Auth Providers.
  4. On the Auth Providers menu, select the Create Auth Provider quick action.

 

Configure Your Active Directory Provider

On the Create Auth Provider Configuration page, provide the following settings:

  1. Add a name.

    The name cannot be changed. This is the name that appears in the NGINX Controller login drop-down list.

  2. (Optional) Add a display name.

  3. (Optional) Add a description.

  4. In the Authentication Provider Type list, select Active Directory.

  5. Select the username format:

    • User Domain, for example, DOMAIN\username
    • UPN (User Principle Name), for example, username@domain.com
  6. Specify the login domain.

    The login domain applies to usernames that don’t have a domain specified. For example, it would apply if a user logs in as “nedflanders”, as opposed to EVERGREEN\nedflanders or nedflanders@evergreen.ter.

  7. Select Next.

 

Configure the Active Directory Connection

On the Auth Provider Connection page, provide the following settings:

  1. Add an LDAP domain to authenticate against as a domain-component. NGINX Controller can bind to only one domain for each configured Active Directory Authentication Provider. This field cannot be updated.

    For example:

    DC=mydomain,DC=example,DC=com
    
  2. Add the connection URI.

    For example:

    ldap://dc1.mydomain.com
    

    -Or-

    ldaps://dc2.mydomain2.com
    
  3. In the SSL Parameters list, select the SSL connection mode. NGINX Controller supports the following options for connections from NGINX Controller to the Active Directory server:

    • PLAIN_TEXT (Not secured) - Unencrypted connection. Does not require SSL certificates.

      Warning:
      Use this mode only if you accept the risks associated with using unencrypted LDAP. Data travels “as is,” without encryption, and can be spied upon by passive attackers.
    • REQUIRE (Default) - Require an SSL connection. NGINX Controller trusts the certificate that the Active Directory server provides, and no certificate authority (CA) is required. Unencrypted connections will fail.

    • VERIFY_CA(Most secure) - Recommended for production environments. Verify the certificate authority of the Active Directory connection. The server is verified by checking the certificate chain up to the root certificate stored on the client.

  4. (Optional) If you generated a self-signed certificate for Active Directory Certificate Services, or if the certificate wasn’t issued by a certificate authority, then you must add the certificate to use for verification. You can either paste the certificate into the Certificate form or upload the file.

  5. Select Next.

 

Configure the Active Directory User Binding

On the Auth Provider User Binding page, provide the following settings:

  1. Select the authentication type.

  2. Add the bind username for accessing the Authentication Provider. For example, domain\username or username@mydomain.

    Tip:
    You can use either format. This setting isn’t governed by the username format that you defined on the Auth Provider Connection page.
  3. Add the bind user password.

  4. Select Next.

 

Configure the Active Directory Group Settings

On the Auth Provider Group Setup page, provide the following settings:

  1. (Optional) Specify the poll interval. This is the time, in seconds, to wait between refreshes of the Active Directory information, including the AD Groups list. The minimum is 300 seconds (5 minutes); the default is 3600 seconds (1 hour).

    Important:
    Consider carefully how long you want to wait between Active Directory refreshes. When users are deleted in Active Directory, the change is reflected immediately in NGINX Controller. However, suppose you change a group’s permission settings or reassign users to groups in Active Directory. In that case, it could take up to 1 hour for the changes to be reflected in NGINX Controller at the default poll interval of 3600 seconds.
  2. (Optional) Specify the group cache timeout. This is the time, in seconds, to wait before considering the AD Groups list to be stale. This value should be double the poll interval. The minimum is 600 seconds (10 minutes); default is 7200 seconds (2 hours).

  3. (Optional) Select whether to honor or disallow stale Active Directory groups when authorizing and authenticating users.

    • ENABLE - Honor stale Active Directory groups.
    • DISABLE (default) - Do not honor stale Active Directory groups.
  4. Add a group search filter, enclosed in parentheses. This is the search filter to use when finding AD Groups within a root domain.

    Examples:

    • Search all groups under the base domain:

      (objectClass=group)
      
    • To match more than one attribute use the ampersand symbol (&):

      (&(objectClass=group)(CN=devops))
      

      In the above example, the & means that we want to search for objectClass=group AND CN=devops. You can compound as many clauses as you need.

    • To match one or more attributes use the pipe symbol (|):

      (&(objectClass=group)(|(CN=devops)(CN=quality_assurance))
      

      In the above example, the | means that we want to search for CN=devops OR CN=quality_assurance.

    • To match wildcards, use the asterisk symbol (*):

      (&(objectClass=group)(CN=*Engineering*))
      

      In this example, we’ve combined the & with a wildcard (*) to search for results in objectClass=group AND for CN that includes the word ‘Engineering’.

    • To exclude entities, use the exclamation point ‘!':

      (&(objectClass=group)(&(ou:dn:=Seattle)(!(ou:dn:=Fremont))))
      

      In this example, we want to find all Seattle groups except those with a Fremont OU component.

  5. Add a group member attribute, without parentheses. This LDAP attribute identifies a user as a member of an Active Directory group.

    For example:

    memberOf
    
  6. Select Next.

 

Configure the Active Directory Group Mappings

On the Auth Provider Group Mappings page, provide the following settings to map Active Directory groups to NGINX Controller groups:

  1. Add the name of an external Active Directory group that you want to map to.

    For example:

    CN=devops,OU=Distribution Lists,OU=Groups
    
  2. (Optional) Specify the Case Sensitive setting:

    1. ENABLE: match the case of the external group name exactly.
    2. DISABLE (default): the match should be case-insensitive.
  3. Select the name of an internal NGINX Controller group that you want to map to.

    For example:

    admin_group
    
  4. Select Next.

  5. Review the API spec that shows the desired Authentication Provider settings.

    Tip:
    You can save the API request so you can easily delete and re-add the Active Directory authentication provider, if needed, via the NGINX Controller REST API.
  6. Select Submit to create the Authentication Provider.

 


View, Edit, or Delete an Active Directory Authentication Provider

Take the following steps to view, edit, or delete an Authentication Provider:

  1. Open the NGINX Controller user interface and log in.
  2. Select the NGINX Controller menu icon, then select Platform.
  3. On the Platform menu, select Auth Providers.
  4. On the Auth Providers menu, select the Create Auth Provider quick action.
  5. To view the details for an Authentication Provider, choose the Authentication Provider from the list. This opens a side panel where you can see the Authentication Provider’s configuration, connection, and bind user specifications.
  6. To edit an Authentication Provider, choose the Authentication Provider from the list, then select Edit (pencil icon).
  7. To delete an Authentication Provider, choose the Authentication Provider from the list, then select Delete (trash icon).

 


Troubleshooting

Active Directory User or Group Isn’t Found

If NGINX Controller doesn’t find Active Directory users or groups as expected, you can use ldapsearch or a similar tool to search your LDAP directory to verify the users and groups exist.

Examples:

  • To query for an Active Directory user named “Jane Doe” using ldapsearch, run the following command:

    ldapsearch -ZZ -W -H ldap://ldap.example.com \
               -b "DC=ldap,DC=example,DC=com" \
               -D "uid=search-user,ou=People,dc=example,dc=com" \
               "(&(objectClass=person)(CN=Jane Doe))"
    
  • To query for an Active Directory group – called “devops” in the example below – using ldapsearch, you would run the following command:

    ldapsearch -ZZ -W -H ldap://ldap.example.com \
               -b "DC=ldap,DC=example,DC=com" \
               -D "uid=search-user,ou=People,dc=example,dc=com" \
               "(&(objectClass=group)(CN=devops))"
    
See Also:
For an overview of the ldapsearch command and command options, see the ldapsearch man page.

How to Immediately Refresh the Active Directory Information

When setting up your Active Directory provider, you specified a poll interval. This is the time, in seconds, to wait between refreshes of the Active Directory information, including the AD Groups list. The minimum is 300 seconds (5 minutes); the default is 3600 seconds (1 hour).

Suppose there’s an emergency or pressing circumstance for which you need to update the Active Directory information sooner than the polling interval. Maybe there was a company reorganization, and all the mappings were changed. Or maybe there was an error in the Active Directory configuration, and a group was given the wrong permissions. In either case, you can delete the Active Directory provider in NGINX Controller and then add it back. The changes made on the Active Directory server will be reflected on NGINX Controller once the Active Directory provider is re-added.

Warning:
Deleting an authentication provider is disruptive. Once the authentication provider is removed, authenticated users will lose access to NGINX Controller until the authentication provider is added again.

This documentation applies to the following versions of NGINX Controller Documentation: 3.6, 3.7, 3.8, 3.9, 3.10, 3.12, 3.13, 3.14, 3.15, 3.16.1, 3.17 and 3.18.