How to: Configure LDAP for user authentication

Overview

Configure LDAP for authentication so that you can customize role-based access to managed BIG-IP Next instances. This allows you to provide access to only those areas that you explicitly grant based on their job responsibilities.

After you configure LDAP, BIG-IP Next Central Manager encrypts connections to your company’s LDAP server using one of these methods, with certificate validation:

  • StartTLS - (with server certificate validation enabled) This is the recommended and most secure method.

  • LDAPS - Typically used for connections to older servers, such as those running LDAPv2.

Prerequisites

Before you configure LDAP, you’ll need the following information.

Information Notes
Host name of the LDAP server For the SSL server certificate validation to succeed, you must use a FQDN. For example: ldap.example.com The FQDN must match the FQDN in the CN (Common Name) attribute of the subject of the X509 certificate for the LDAP server. For example, an LDAP server might present a certificate that includes the following subject data:
Subject: C=US, ST=Washington, L=Seattle, O=ldap1, OU=F5 Networks, CN=ldap.example.com/emailAddress=ldap@example.com
If the value of the host name does not match the FQDN in the CN field, authentication will fail. Specifying an IP address instead of a FQDN results in such a mismatch.
Port of the LDAP server The default port is 389 for StartTLS and 636 for LDAPS, unless otherwise specified. If your LDAP server uses an alternate, non-standard port, you need to specify it in the authentication settings.
LDAP server's SSL certificate For the BIG-IP Next Central Manager to trust the SSL certificate presented by your LDAP server, you must provide a PEM-formatted certificate in the authentication provider settings. To establish the SSL connection to the LDAP server, the BIG-IP Next Central Manager must trust any one of the SSL certificates in the chain presented by the server during the SSL handshake.
As an alternative to the LDAP server's SSL certificate, you can use the issuing CA’s SSL certificate instead. A typical scenario where the issuing CA’s certificate is used instead, is when a domain controller uses multiple servers, each with a different certificate. In this case, all the certificates would have the same issuing CA, often the company’s own CA.
Root Distinguished Name This is the Root DN for your directory. The BIG-IP Next Central Manager uses it as the starting point in the directory when it searches for users and groups.
LDAP users You'll need to create BIG-IP Next Central Manager users and groups that map to the remote users and groups on the LDAP server. User access to certain BIG-IP Next Central Manager screens and features is dependent on the BIG-IP Next Central Manager roles you associate to the user. You can also manage user access based on the roles associated to the groups the user belongs to on your LDAP server. Use an LDAP browser to review the users and groups in your directory's structure and determine where they are located in the organizational units (OUs). Then, decide how you want to map those names to your BIG-IP Next Central Manager users and groups. To authenticate a user against the remote LDAP server, choose one of the following options: Map users directly to their Distinguished Name (DN) in the directory with a user bind template in the form of uid={username}, ou={organizational unit}, o={organization name}. When a user logs in, BIG-IP Next Central Manager inserts the user name into the template in place of the token, and the resulting DN is used to bind to the directory. For example, you'd map John Smith's user name to his DN as uid=jsmith, ou=people, o=F5 and he would log in as jsmith and would be correctly authenticated with his user name in the directory through his DN.
Allow users to log in with names that do not map directly to their DN by specifying a user search filter in the form of (&( uid={username})) when creating the provider. You'll need to provide a bind user Distinguished Name and password to bind to the directory, search for the login user, and validate the user's credentials. For example, user John Smith logs in as jsmith, and the login name is substituted in the directory search query as (&(uid=jsmith)).

Procedure

To authenticate users against your LDAP server, specify your LDAP server settings on BIG-IP Next Central Manager. You can use one or more of your company’s LDAP servers to authenticate users.

  1. Log in to BIG-IP Next Central Manager as admin, click the Workspace icon next to the F5 icon, click System, and then click Auth Providers.

  2. Click the Configure button next to LDAP.

  3. Click the Start Adding button.

  4. In the Servers setting Host field, type or paste the FQDN of your authentication server, and in the Port field specify the port.
    By default, BIG-IP Next Central Manager uses port 636 for LDAPS and 389 for StartTLS. It’s best to leave these defaults.
    For the SSL server certificate validation to succeed, you must use a Fully Qualified Domain Name (FDQN), rather than an IP address. The FQDN must match the FQDN in the Common Name attribute of the subject of the X509 certificate presented by the LDAP server. For example, an LDAP server might present a certificate that includes the following subject data:
    Subject: C=US, ST=Washington, L=Seattle, O=ldap1, OU=F5 Networks, CN=ldap.example.com/emailAddress=ldap@example.com.
    If your authentication server uses an alternate, non-standard port, you need to specify it in the authentication provider settings.

  5. From the SSL list, select how you want BIG-IP Next Central Manager to communicate with your authentication server.

  • StartTLS - In almost all cases, you’ll want to select this option, because it is the most secure option. You’ll want to keep server certificate validation option enabled.

  • LDAPS - This is primarily used to connect to older servers, running an older version of the LDAP protocol (LDAPv2).

  • Disabled - This option to disables SSL and is not secure and not recommended.

  1. Select the Validate SSL Certificate checkbox and in the SSL Certificate field, type or paste your LDAP server’s SSL certificate in PEM format.
    To establish the SSL connection to the LDAP server, BIG-IP Next Central Manager must trust any one of the SSL certificates in the chain presented by the authentication server during the SSL handshake.
    As an alternative to the server certificate, you can use the issuing CA’s SSL certificate instead. A typical scenario where the issuing CA’s certificate is used is the case where an authentication provider uses multiple LDAP servers, each with a different certificate and all the certificates have the same issuing CA.

  2. In the Bind User Distinguished Name and Bind User Password fields, type the full distinguished name and password for the dedicated bind account with directory search permissions.

  3. For the User Bind Template field, type or paste the username in the Root Distinguished Name format uid={username}, ou={organizational unit}, o={organization name}.

  4. In the Root Distinguished Name field, type the distinguished names (DN) of the root context that contains both users and groups.
    The DN of the root context must be a full distinguished name. BIG-IP Next Central Manager uses it as the starting point in the directory when it searches for users and groups.

  5. For the Authentication Method setting, specify a method.

  • Simple - Select this option to require a user name and password for authentication.

  • None - Select this option to ignore the user name and password. This option is not recommended. No password authentication is used if you select None.

  1. For the Search Scope setting, select an option to specify the depth at which searches are made, relative to the Root Distinguished Name.

  2. To specify time out settings, enable Show Advanced Settings at the top of the screen.

  • In the Connect Timeout field, type the number of seconds after which the BIG-IP Next Central Manager stops trying to authenticate a user or user group.

  • In the Read Timeout field, type the number of seconds BIG-IP Next Central Manager will wait for a response to a query.

  1. To verify these provider settings, type a user and password, and click the Test button.

Prerequisite

Authenticate with the BIG-IP Next Central Manager API. For details refer to How to: Authenticate with the BIG-IP Next Central Manager API.
Use the following BIG-IP Next Central Manager APIs to configure LDAP users:

  1. Configure LDAP server by sending a POST request to /spaces/default/auth-providers endpoint.

    POST https://{{cm_mgmt_ip}}/api/v1/spaces/default/auth-providers
    
    

    For the request payload, use the following example, modifying the values as required.

    {
    "provider_type": "LDAP",
    "name": "LDAP",
    "content": {
        "servers": [
            {
                "host": "{{ldap_server}}",
                "port": {{ldap_server_port}}
            }
        ],
        "ssl_type": "LDAPS",
        "validate_ssl_certificate": false,
        "bind_user_distinguished_name": "cn=admin,dc=xyz,dc=test,dc=testnet,dc=com",
        "bind_user_password": "password",
        "user_bind_template": "uid={username},ou=users,dc=test,dc=test,dc=testnet,dc=com",
        "user_search_filter": "(&(uid={username}))",
        "root_distinguished_name": "dc=xyz,dc=test,dc=examplenet,dc=com",
        "authentication_method": "Simple",
        "search_scope": "Subtree",
        "connect_timeout": 5,
        "read_timeout": 10
    },
    "disabled": false
    }
    
  2. Create LDAP users with roles such as administrator role or standard role by sending a POST request to /system/v1/users endpoint.

    POST https://{{cm_mgmt_ip}}/api/system/v1/users
    

    For the request payload, use the following example, modifying the values as required.
    role_type: Change role type to Administrator or Standard role as per the requirement.
    For a LDAP user, provider_type and provider_name must be LDAP.

    {
    "username": "{{ldap_user_1}}",
    "password": "",
    "role_type": "Administrator",
    "provider_type": "LDAP",
    "provider_name": "LDAP"
    }
    
  3. Retrieve the list of roles by sending a POST request to /system/v1/roles endpoint.

    GET https://{{cm_mgmt_ip}}/api/system/v1/roles
    
  4. Assign roles to LDAP users by sending a POST request to /system/v1/users/{id}/roles endpoint.

    POST https://{{cm_mgmt_ip}}/api/system/v1/users/{id}/roles
    

    For the request payload, use the following example, modifying the values as required.
    role_ids: Change the role ids as per the requirement.

    {
    "role_ids": [
        "{{role-id}}"
    ]
    }
    
  5. Test the LDAP server connection by sending a POST request to system/v1/auth-providers/login endpoint.

    POST https://{{cm_mgmt_ip}}/api/system/v1/auth-providers/login
    

    For the request payload, use the following example, modifying the values as required.

    {
    "provider_type": "LDAP",
    "name": "LDAP",
    "username": "{{ldap_user_1}}",
    "password": "{{ldap_user_1_password}}"
    }
    
  6. Login as a created user by sending a POST request to /api/login endpoint.

    POST https://{{cm_mgmt_ip}}/api/login
    

    For the request payload, use the following example, modifying the values as required

    {
    "username": "{{ldap_user_1}}",
    "password": "{{ldap_user_1_password}}",
    "provider_type": "LDAP",
    "provider_name": "LDAP"
    }
    
  7. Retrieve the list of users with their IDs by sending the GET request to system/v1/users endpoint. Identify the user IDs that help in operations like delete user.

    GET https://{{cm_mgmt_ip}}/api/system/v1/users
    
  8. Retrieve the ID of specific user by sending the GET request to system/v1/users?filter=username+eq+%27{{username}}%27 endpoint.

    GET https://{{cm_mgmt_ip}}/api/system/v1/users?filter=username+eq+%27{{username}}%27
    
  9. Modify a user role to another role by sending a POST request to /system/v1/users/{user-id}/roles endpoint.

    POST https://{{cm_mgmt_ip}}/api/system/v1/users/{user-id}/roles
    

    For the request payload, use the following example, modifying the values as required.
    role_ids: Change the role ids as per the requirement. If you want a user to have multiple roles, add the roles separated by a comma.

    {
    "role_ids": [
        "{{role-id1}}", "{{role-id2}}"
    ]
    }
    
  10. Logout a user by sending a POST request to /api/logout endpoint.

    POST https://{{cm_mgmt_ip}}/api/logout
    
  11. Delete a user by sending a DELETE request to /system/v1/users/{user-id} endpoint.

    DELETE https://{{cm_mgmt_ip}}/api/system/v1/users/{user-id}
    

    Note: To delete the user, logout from the user role and log in to the administrator role.