End of Sale Notice:

F5 NGINX is announcing the End of Sale (EoS) for NGINX Controller API Management Module, effective January 1, 2024.

F5 maintains generous lifecycle policies that allow customers to continue support and receive product updates. Existing NGINX Controller API- Management customers can continue to use the product past the EoS date. License renewals are not available after September 30, 2024.

See our End of Sale announcement for more details.

End of Sale Notice:

F5 NGINX is announcing the End of Sale (EoS) for NGINX Controller Application Delivery Module, effective January 1, 2024.

F5 maintains generous lifecycle policies that allow customers to continue support and receive product updates. Existing NGINX Controller Application Delivery customers can continue to use the product past the EoS date. License renewals are not available after September 30, 2024.

See our End of Sale announcement for more details.

Configure Active Directory Integration

Set up Active Directory authentication for F5 NGINX Controller using OIDC with Microsoft Entra or LDAP, LDAPs, and StartTLS with Windows Active Directory.

Overview

By completing the steps in this guide, you will learn how to add an Active Directory (AD) integration to F5 NGINX Controller. NGINX Controller supports the following AD types and protocols:

Microsoft Entra: OpenID Connect (OIDC) over HTTPS;
Windows Active Directory: unencrypted LDAP, LDAPS, and StartTLS.

Before You Begin

Before proceeding with this guide, complete the steps in the appropriate prerequisites section for the type of Active Directory integration that you want to create.

Microsoft Entra

To configure an auth provider in Microsoft Entra using OIDC over HTTPS, complete the following prerequisites.

Create an Microsoft Entra Tenant and App Registration.

Refer to the Microsoft Microsoft Entra Quick Start Guide for instructions:
- Set up Microsoft Entra Tenant
- Register App
Record your tenant ID, as well as the Client ID and Client Secret(s) for your App. Keep them handy, you will need this information to set up the Microsoft Entra Auth Provider in NGINX Controller.

Important:
Microsoft Azure will only display the Client Secret once, during the App Registration process. Be sure to keep this information somewhere safe so you can refer to it later.
Add the following application permissions to the App Registration’s “Microsoft Graph” API:
- Group.ReadAll
- GroupMember.ReadAll
- User.Read
- User.ReadAll
Tip:
These permissions require approval from the Azure admin.
Make sure that you can contact Microsoft Entra from the host on which you are running NGINX Controller.

Windows Server Active Directory

To configure an auth provider in Active Directory over LDAP, LDAPS, or StartTLS, complete the following prerequisites.

Install Active Directory Domain Forest. Refer to the Microsoft Windows Server documentation for instructions: Install Windows Server Active Directory Forest (Level 200)
Enable LDAP over SSL.

In order to use a secure means of communication like LDAPS or StartTLS, you need to enable LDAP over SSL with a certification authority. Refer to the following Microsoft user guides for instructions:
- LDAP over SSL (LDAPS) Certificate
- Enable LDAP over SSL with a third-party certification authority
Make sure that you can connect to your Windows Active Directory server from the host on which you are running NGINX Controller.

Create an Authentication Provider

Take the steps below to create a new Authentication Provider by using the NGINX Controller user interface.

Open the NGINX Controller user interface and log in.
Select the NGINX Controller menu icon, then select Platform.
On the Platform menu, select Auth Providers.
On the Auth Providers menu, select the Create Auth Provider quick action.
Select the desired type of authentication provider in the Authentication Provider Type list.
Next, proceed to the appropriate section for the type of Authentication Provider you selected:
- Microsoft Entra
- Windows Active Directory

Set up an Microsoft Entra Auth Provider

Introduced in NGINX Controller ADC v3.22

In the previous section, you selected Microsoft Entra from the Authentication Provider Type list. Next, you’ll set up the Auth Provider so it can connect to Microsoft Entra.

Add a name for the Auth Provider.

Important:
This name is a permanent setting that cannot be changed.

This is the name that your users will be able to select as the authentication provider when logging in to NGINX Controller. Be sure the name you provide is accurate and easy to identify.
(Optional) Add a display name. This will be displayed in the NGINX Controller user interface.
(Optional) Add a description.
Select Next.

Set up OpenID Connect

On the Auth Provider OIDC Config page, provide the following settings:

Provider URI: This is the authority URL that authorizes access to the OpenID Connect (OIDC) metadata document. NGINX Controller forwards authentication requests to this URL. This URL contains the {tenant} that you created earlier.

Refer to the Microsoft Microsoft Entra OIDC documentation for more information about the OIDC responses.

For example, the following Provider URI would allow users from the specified Microsoft Entra tenant to log in to NGINX Controller:
```
"https://login.microsoftonline.com/12345678-90ab-cdef-1234-567890abcdef/v2.0"
```
Client ID: This is the client ID from your Microsoft Entra App Registration.
Client Secret: This is the secret that you created with your Microsoft Entra App Registration.
Scopes: This defines the permissions the Auth Provider requests from Azure.

The default scopes are:
```
openID,email,profile
```
Any custom scopes should follow the same comma-separated format as the example above.
Select Next.

Set up Microsoft Entra Groups

On the NGINX Controller Auth Provider Group Setup page, provide the following information:

(Optional) Poll interval: This is the interval at which NGINX Controller fetches updated information, including the Groups list, from Microsoft Entra.
- The value must be defined in seconds.
- The minimum allowed value is 300 seconds (5 minutes).
- The default value is 3600 seconds (1 hour).
Important:
Consider how you want to set this field carefully. While deletions in Microsoft Entra are reflected in NGINX Controller immediately, changes such as group permission updates or user reassignments are not. This means that, when using the default poll interval, it could take up to an hour for changes in Microsoft Entra to be reflected in NGINX Controller.
(Optional) Cache timeout: This is the time, in seconds, to wait before considering the AD Groups list to be outdated, or, “stale”.
- This value should be double the poll interval.
- The minimum allowed value is 600 seconds (10 minutes).
- The default value is 7200 seconds (2 hours).
(Optional) Honor stale Microsoft Entra groups: This setting determines whether NGINX Controller will allow or deny login requests from users in stale AD groups.
- ENABLE - Honor stale Microsoft Entra groups.
- DISABLE (default) - Do not honor stale Microsoft Entra groups.
(Optional) Group search filter: This is the search filter that you want to use to return group results.
- This value must be enclosed in parentheses.
- The allowed syntax for the filters can be found in the Microsoft documentation.
- The default behavior is to return the first 100 groups.
- You need to set up Groups if you want to use NGINX Controller role-based access control (RBAC).
Select Next to review and record the NGINX Controller API call that sets up the Microsoft Entra auth provider.
Select Submit to create the Auth Provider. The NGINX Controller UI will display a redirect URI when the Auth Provider setup is complete.
Copy the redirect URI and add it to your Azure App Registration. Refer to the Microsoft Microsoft Entra Quick Start guide for instructions: Add a Redirect URI.

Set Up Role-Based Access Control with Microsoft Entra

In order to use role-based access control (RBAC) with Microsoft Entra (AD), you need to map groups from the Microsoft Entra tenant to NGINX Controller RBAC roles.

Important:
You should complete this step immediately after creating the Microsoft Entra authentication provider, before any other changes can be made.

If you haven’t already done so, create the Role(s) and Role group that you want to map the Microsoft Entra permissions to.
On the Platform menu in the NGINX Controller user interface, select Auth Providers, then select the Auth Provider that contains the Microsoft Entra configuration.
Set up the Auth Provider Group Mappings:
- Provide the name of the Microsoft Entra Group that you want to use.
  
  Tip:
  The Group filter determines which Groups are available for this setting. Be sure the Group that you want to add is included by your group filter.
- (Optional) Provide the Case Sensitive setting:
  - ENABLE: match the case of the external group name exactly.
  - DISABLE` (default): the match should be case-insensitive.
- Select the name of the NGINX Controller role group that you want to map the Microsoft Entra group to.
- Select Next to review and record the NGINX Controller API call that sets up the Microsoft Entra Group mappings.
- Select Submit to complete the RBAC setup.

Set up a Windows Active Directory Auth Provider

In the previous section, you selected Active Directory from the Authentication Provider Type list. Next, you’ll set up the Auth Provider so it can connect the Windows Active Directory (AD).

Add a name for the Auth Provider.

Important:
This name is a permanent setting that cannot be changed.

This is the name that your users will be able to select as the authentication provider when logging in to NGINX Controller. Be sure the name you provide is accurate and easy to identify.
(Optional) Add a display name. This will be displayed in the NGINX Controller user interface.
(Optional) Add a description.
Select the username format:
- User Domain: follows the format DOMAIN\username
- UPN (User Principle Name): uses the standard email format, for example username@domain.com
Specify the login domain.

The login domain applies to usernames that don’t have a domain specified (for example, if a user logs in as “nedflanders”, as opposed to EVERGREEN\nedflanders or nedflanders@evergreen.ter).
Select Next.

Set up the Active Directory Connection

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

The LDAP domain to authenticate against as a domain-component.
- NGINX Controller can bind to one domain for each configured Active Directory (AD) Authentication Provider.
- This field cannot be updated.
For example:
```
DC=mydomain,DC=example,DC=com
```

Add the connection URI.

For example:

ldap://dc1.mydomain.com

-Or-

ldaps://dc2.mydomain2.com

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. Not recommended for production environments.
- 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.
(Optional) Add the certificate to use for verification.
- 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.
Select Next.

Set Up the Active Directory User Binding

On the Auth Provider User Binding page, provide the following settings that will allow NGINX Controller to authenticate to the Active Directory (AD.

Authentication type: The type of authentication to use to connect to the Active Directory (AD).
Bind username: This is a username that will be used to access the AD. For example, domain\example.user or example.user@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.
Bind user password: The password for the user account that will be used to connect to the AD.
Select Next.

Set up Active Directory Groups

On the NGINX Controller Auth Provider Group Setup page, provide the following information:

(Optional) Poll interval: This is the interval at which NGINX Controller fetches updated information, including the Groups list, from the Active Directory (AD).
- The value must be defined in seconds.
- The minimum allowed value is 300 seconds (5 minutes).
- The default value is 3600 seconds (1 hour).
Important:
Consider how you want to set this field carefully. While deletions in the AD are reflected in NGINX Controller immediately, changes such as group permissions updates or user reassignments are not. This means that, when using the default poll interval, it could take up to an hour for changes to the AD to be reflected in NGINX Controller.
(Optional) Cache timeout: This is the time, in seconds, to wait before considering the AD Groups list to be outdated, or, “stale”.
- This value should be double the poll interval.
- The minimum allowed value is 600 seconds (10 minutes).
- The default value is 7200 seconds (2 hours).
(Optional) Honor stale Active Directory groups: This setting determines whether NGINX Controller will allow or deny login requests from users in stale AD groups.
- ENABLE - Honor stale AD groups.
- DISABLE (default) - Do not honor stale AD groups.
(Optional) Group search filter: This is the search filter that you want to use to return group results within a root domain. This value must be enclosed in parentheses.

Examples:
- Search all groups under the base domain:
```
(objectClass=group)
```
- Match more than one attribute using 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.
- 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.
- Match wildcards using 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’.
- Exclude entities using 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.
Add a group member attribute, without parentheses. This LDAP attribute identifies a user as a member of an Active Directory group.

For example:
```
memberOf
```
Select Next.

Set up Role-Based Access Control with Active Directory

In order to use role-based access control (RBAC) with Active Directory (AD), you need to map groups from the AD to NGINX Controller RBAC roles.

If you haven’t already done so, create the Role(s) and Role group that you want to map the AD permissions to.
On the Platform menu in the NGINX Controller user interface, select Auth Providers, then select the Auth Provider that contains the AD integration.
Add the name of the external AD group that you want to map to.

For example:
```
CN=devops,OU=Distribution Lists,OU=Groups
```
(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.
Select the name of the NGINX Controller Role group that you want to map to.
Select Next to review and record the NGINX Controller API call that sets up the AD integration.
Select Submit to create the Authentication Provider.

Manage an Existing Authentication Provider

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

Open the NGINX Controller user interface and log in.
Select the NGINX Controller menu icon, then select Platform.
On the Platform menu, select Auth Providers.
On the Auth Providers menu, select the Create Auth Provider quick action.
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.
To edit an Authentication Provider, choose the Authentication Provider from the list, then select Edit (pencil icon).
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.