Manual Chapter : LDAP User Authentication

Applies To:

Show Versions Show Versions

BIG-IQ Centralized Management

  • 6.1.0
Manual Chapter

LDAP User Authentication

Use my LDAP server to authenticate BIG-IQ users

F5 BIG-IQ Centralized Management supports encrypted connections to your company's LDAP server (LDAP server versions 2 and 3, OpenLDAP directory, and Apache Directory 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.

After you set up BIG-IQ to use your LDAP server, you can add users and user groups that authenticated by the LDAP server.

Before integrating BIG-IQ with your LDAP server for authentication

Before integrating LDAP server authentication with the F5 BIG-IQ Centralized Management system, you must gather the following information.

Required 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-IQ 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-IQ 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-IQ uses it as the starting point in the directory when it searches for users and groups.

LDAP users

You'll need to create BIG-IQ users and groups that map to the remote users and groups on the LDAP server.

Important:

User access to certain BIG-IQ screens and features is dependent on the BIG-IQ 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-IQ 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=people, o=sevenSeas. When a user logs in, BIG-IQ 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=sevenSeas 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)).

LDAP groups

While not needed for user authentication if a User Bind Template is provided, a Bind User Distinguished Name must be provided to be able to search for groups. However, it is not necessary for either login or group search if your LDAP server allows anonymous binds (insecure option, not recommended).

If your company does not allow dedicated bind accounts, any directory user with permissions to search the directory for groups can be used to bind instead.

Set up BIG-IQ to use your LDAP server for user authentication and authorization

Before you can set up BIG-IQ to authenticate and authorize BIG-IQ users against your LDAP server, you have to specify your LDAP server settings on F5 BIG-IQ Centralized Management and perform all the tasks outlined in the section titled, Before integrating BIG-IQ with your LDAP server.

You can configure BIG-IQ to use one or more of your company's LDAP servers to authenticate and authorize users. Some fields are pre-populated with values that work well for most LDAP servers with standard configurations and schemas. Feel free to change these default values if your LDAP schema is different.

  1. At the top of the screen, click System.
  2. On the left, click USER MANAGEMENT > Auth Providers .
  3. Click the Add button.
  4. From the Provider Type list, select your LDAP server.
  5. In the Name field, type a name for this new provider.
    This must be a unique name, and can be a maximum of 152 characters.
  6. In the Servers setting Host field, type or paste the FQDN of your LDAP server, and specify the port.

    By default, BIG-IQ 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 LDAP server uses an alternate, non-standard port, you need to specify it in the authentication provider settings.
  7. From the SSL list, select how you want BIG-IQ to communicate with your LDAP 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.
  8. 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, the BIG-IQ must trust any one of the SSL certificates in the chain presented by the LDAP 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.
  9. If your company supports dedicated Bind authentication, 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.
  10. If your company does not support dedicated bind authentication, in the User Bind Template field, type or paste the user in the Distinguished Name format uid={username},ou=people,o=sevenSeas
  11. In the User Search Filter field, type the filter expression you want to use to find users' propertie to see what type of authorization they have.

    For example: (&(uid={username})).

  12. 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-IQ uses it as the starting point in the directory when it searches for users and groups.
  13. 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.
    Warning: No password authentication is used if you select None.
  14. For the Search Scope setting, select an option to specify the depth at which searches are made, relative to the Root Distinguished Name.
  15. In the Connect Timeout field, type the number of seconds after which the BIG-IQ system stops trying to authenticate a user or user group.
  16. In the Read Timeout field, type the number of seconds the BIG-IQ system will wait for a response to a query.
  17. The default query for the Group Search Filter setting works well for most directories that use a standard LDAP configuration schema.
    This returns all the groups under the provided Root DN that matches the search term for the Remote Group Filter setting on the group search screen. However, feel free to delete two of the three clauses involving objectClass, leaving only the one corresponding to your directory schema.

    For example: (&(-[[|(objectClass=posixGroup) (objectClass=groupOfUniqueNames)(objectClass=groupOfNames)) (]]-+[[objectCategory=group)(]]+cn={searchterm}+[[*]]+))

  18. For the Group Membership User Attribute setting, the default value works well for most Active Directory DCs that use a standard schema.

    When authenticating a user, BIG-IQ uses this query to get all of the groups on the Active Directory DC to which the user belongs. Feel free however to simplify it and leave only the one of the three clauses that matches your directory schema. In you change the query, you can use the token {userDN} anywhere the user's distinguished name should be substituted in the Active Directory query and the token {username} anywhere the user’s login name should be substituted.

  19. If you don't want the authentication provider to display on the BIG-IQ log in screen, for the Hide Provider setting, select the Hide provider on login screen check box.
  20. To verify these provider settings, type a user and password, and click the Test button.

Add a BIG-IQ user authenticated by my LDAP server and associate it with a role

If you want to add a user authenticated against your LDAP server, you first have to configure your LDAP server settings on BIG-IQ.
Once you understand exactly who you want to perform certain tasks, you can provide them access to particular areas of BIG-IQ by adding them as a user and assigning the appropriate built-in or custom role. You can assign as many roles as required to cover the user's responsibilities.

For the LDAP-authenticated user to access BIG-IQ, you must put the local user in a BIG-IQ role, or put in a role in a local group mapped to one of the user’s groups on the LDAP server.

  1. At the top of the screen, click System.
  2. On the left, click USER MANAGEMENT > Users .
  3. Click the Add button.
  4. From the Auth Provider list, select your LDAP server.
  5. In the User Name field, type the name for this user.
  6. In the Full Name field, type a name to identify the user from BIG-IQ.

    The full name can contain a combination of letters, symbols, numbers and spaces.

  7. For the Roles setting, from the Available list, select each user role you want to associate with this user, and move it to the Selected list.
    Important: Be sure to let your users know that their access to certain parts of the BIG-IQ user interface depends on which role they are assigned.
  8. Click the Save & Close button.
Important: If this BIG-IQ is part of an HA pair, you must log in to the secondary BIG-IQ system, click System -> BIG-IQ HA, click the BIG-IQ HA Settings button, then click the Log Out & Refresh button. This procedure is required because BIG-IQ handles users and user groups differently than other data synchronized between BIG-IQ systems in an HA pair. If you don't perform this procedure, this new user cannot successfully log in to the secondary system.

Create an LDAP authenticated user group

Important: For the LDAP-authenticated user to access BIG-IQ, you must put the local user in a BIG-IQ role, or put in a role a local group that is mapped to one of the user’s groups on the LDAP server.

Create a user group to offer individual users the same privileges on F5 BIG-IQ Centralized Management. This user group will be authorized by your LDAP server.

  1. At the top of the screen, click System.
  2. At the left, click USER MANAGEMENT > User Groups .
    The User Groups screen opens.
  3. Click the Add button.
  4. From the Auth Provider list, select your LDAP server.
  5. There are two ways to specify the remote group to map to:
    • If you specified a bind user and a group search filter for authentication, then type a term to filter into the Remote Group Filter field (for example, *Engineers*). Alternatively, you can leave it blank, or use the wildcard * to return all groups. Then click the Search button to view the list.

      The default Group Search Filter query, (&(objectCategory=group)(cn={searchterm}*)), works well for most Active Directory controllers that use a standard schema. This query returns all the groups under the provided Root DN that match the search term entered as the Remote Group Filter expression on the group search page. You can modify this query as needed to match your directory schema.

    • If you have not configured these options, in the Group Distinguished-[[-[[-[[+[[ Name]]+]]-+[[ Name]]+]]-+[[ Name]]+]]-+[[ Name]]+ field, type the exact name of the group.
  6. From the -[[-[[-[[+[[Available ]]+]]-+[[Available ]]+]]-+[[Available ]]+]]-+[[Available ]]+Roles list, select the user roles that have the privileges you want to grant to this user group and move them to the Selected list.
  7. Click the Save & Close button.
Important: If this BIG-IQ is part of an HA pair, you must log in to the secondary BIG-IQ system, click System -> BIG-IQ HA, click the BIG-IQ HA Settings button, then click the Log Out & Refresh button. This procedure is required because BIG-IQ handles users and user groups differently than other data synchronized between BIG-IQ systems in an HA pair. If you don't perform this procedure, this new user cannot successfully log in to the secondary system.