Manual Chapter :
LDAP and LDAPS Authentication
Applies To:
Show VersionsBIG-IP APM
- 16.1.5, 16.1.4, 16.1.3, 16.1.2, 16.1.1, 16.1.0
LDAP and LDAPS Authentication
About LDAP and
LDAPS authentication
You can use LDAPS in place of LDAP when the authentication
messages between the Access Policy
Manager and the LDAP server must be secured with encryption.
However, there are instances where you will not need LDAPS and the security
it provides. For example, authentication traffic happens on the internal
side of Access Policy Manager, and might not be subject to observation by
unauthorized users. Another example of when not to use LDAPS is when
authentication is used on separate VLANs to ensure that the traffic cannot
be observed by unauthorized users.
LDAPS is achieved by directing LDAP traffic over a virtual
server that uses server side SSL to communicate with the LDAP server.
Essentially, the system creates an LDAP AAA object that has the address of
the virtual server. That virtual server (with server SSL) directs its
traffic to a pool, which has as a member that has the address of the LDAP
server.
If using LDAP or RADIUS authentication in such a way that
requires multiple authentication requests, then One Time Password
will not work (because password usage is reached on the second
request).
About how APM handles
binary values in LDAP attributes
For LDAP, Access Policy Manager
(APM) converts an attribute value to hex only if the
value contains unprintable characters. If the session variable contains several values, and one
or more of those values is unprintable, then APM converts only those particular values to
hex.
An attribute with a
single unprintable value
9302eb80.session.ldap.last.attr.objectGUID 34 / 0xfef232d3039be9409a72bfc60bf2a6d0
Attribute with multiple
values, both printable and unprintable (binary)
29302eb80.session.ldap.last.attr.memberOf 251 | / CN=printable group,OU=groups,OU=someco,DC=smith, / DC=labt,DC=fp,DC=somelabnet,DC=com | / 0x434e3d756e7072696e7461626c6520c2bdc2a12067726f75702c4f553d67726f7570732c4f553d66352c / 44433d73686572776f6f642c44433d6c6162742c44433d66702c44433d66356e65742c44433d636f6d |
About AAA high availability
Using AAA high availability with Access Policy Manager (APM), you can configure multiple authentication servers to process requests, so that if one authentication server goes down or loses connectivity, the others can resume authentication requests, and new sessions can be established, as usual.
Although new authentications fail if the BIG-IP system loses connectivity to the server, existing sessions are unaffected provided that they do not attempt to re-authenticate.
APM supports the following AAA servers for high availability: RADIUS, Active Directory, LDAP, CRLDP, and TACACS+. APM supports high availability by providing the option to create a pool of server connections when you configure the supported type of AAA server.
If you use AAA with pools, such as RADIUS pools or Active
Directory pools, APM assigns each pool member with a different number for the pool
member's priority group value. APM must define each pool member with a different
priority group because AAA load balancing is not used. The priority group number
increases automatically with each created pool member. Alternative AAA pool
configurations can be defined manually using the full flexibility of Local Traffic
Manager (LTM) if high availability is desired.
Task summary for configuring for LDAPS authentication
This task list includes all steps required to set up this configuration. If you are adding
LDAPS authentication to an existing access policy, you do not need to create another access
profile and the access policy might already include a logon page.
Configuring an LDAPS
AAA server in APM
You
create an LDAPS AAA server when you need to encrypt authentication messages between Access Policy
Manager (APM) and the LDAP server.
- Select.The LDAP servers screen displays.
- ClickCreate.The New Server properties screen opens.
- In theNamefield, type a unique name for the authentication server.
- For theServer Connectionsetting, selectUse Pooleven if you have only one LDAP server.
- In theServer Pool Namefield, type a name for the AAA server pool.
- Populate theServer Addressesfield by typing the IP address of a pool member and clickingAdd.Type the IP address of an external LDAP server. If you have more than one pool member, repeat this step.
- For theModesetting, selectLDAPS.
- In theService Portfield, retain the default port number for LDAPS,636, or type the port number for the SSL service on the server.
- In theAdmin DNfield, type the distinguished name (DN) of the user with administrator rights.Type the value in this format:CN=administrator,CN=users,DC=sales,DC=mycompany,DC=com.
- In theAdmin Passwordfield, type the administrative password for the server.
- In theVerify Admin Passwordfield, re-type the administrative password for the server.
- From theSSL Profile (Server)list, select an SSL server profile.You can select the default profile, serverssl, if you do not need a custom SSL profile.LDAPS is achieved by directing LDAP traffic over a virtual server that uses server-side SSL to communicate with the LDAP server.
- Skip theTimeoutfield because it does not apply when you selectUse Pool.
- ClickFinished.The new server displays on the list.
The
new LDAPS server displays on the LDAP Server list.
Create an access profile
You create an access profile to provide the access policy configuration for a
virtual server that establishes a secured session.
- On the Main tab, click.The Access Profiles (Per-Session Policies) screen opens.
- ClickCreate.The New Profile screen opens.
- In theNamefield, type a unique name for the access profile.
- From theProfile Typelist, select one these options:
- ALL: Select to support LTM-APM and SSL-VPN access types.
- LTM-APM: Select for a web access management configuration.
- OAuth-Resource Server: For configuring APM to act as an OAuth resource server that provides an OAuth authorization layer into an API gateway.
- RDG-RAP: Select to validate connections to hosts behind APM when APM acts as a gateway for RDP clients.
- SSL-VPN: Select to configure network access, portal access, or application access. (Most access policy items are available for this type.)
- SSO: Select to configure matching virtual servers for Single Sign-On (SSO).No access policy is associated with this type of access profile
- SWG - Transparent: Select to configure access using Secure Web Gateway transparent forward proxy.
- SWG - Explicit: Select to configure access using Secure Web Gateway explicit forward proxy.
- System Authentication: Select to configure administrator access to the BIG-IP system (when using APM as a pluggable authentication module).
- Identity Service: Used internally to provide identity service for a supported integration. Only APM creates this type of profile.You can edit Identity Service profile properties.
Depending on licensing, you might not see all of these profile types.Additional settings display. - From theProfile Scopelist, select one these options to define user scope:
- Profile: Access to resources behind the profile.
- Virtual Server: Access to resources behind the virtual server.
- Global: Access to resources behind any access profile with global scope.
- Named: Access for SSL Orchestrator users to resources behind any access profile with global scope.
- Public: Access to resources that are behind the same access profile when the Named scope has configured the session and is checked based on the value and string configured in the Named scope field.
- For theCustomization Type, use the default valueModern.
- In the Language Settings area, add and remove accepted languages, and set the default language.If no browser language matches one in the accepted languages list, the browser uses the default language.
- ClickFinished.
The access
profile displays in the Access Profiles List. Default-log-setting is assigned to the
access profile.
Verify log settings for the access profile
Confirm that the correct log settings are selected
for the access profile to ensure that events are logged as you intend.
Log settings are configured in the
area of the product. They enable and disable logging for access
system and URL request filtering events. Log settings also specify log publishers
that send log messages to specified destinations. - On the Main tab, click.The Access Profiles (Per-Session Policies) screen opens.
- Click the name of the access profile that you want to edit.The properties screen opens.
- On the menu bar, clickLogs.The access profile log settings display.
- Move log settings between theAvailableandSelectedlists.You can assign up to three log settings that enable access system logging to an access profile. You can assign additional log settings to an access profile provided that they enable logging for URl request logging only.Logging is disabled when theSelectedlist is empty.
- ClickUpdate.
An access profile is in effect when it is assigned to a virtual server.
Configuring LDAPS
authentication
You
configure an access policy with an LDAP Auth action to provide LDAP authentication for
users.
- On the Main tab, click.The Access Profiles (Per-Session Policies) screen opens.
- In the Per-Session Policy column, click theEditlink for the access profile you want to configure.The visual policy editor opens the access policy in a separate screen.
- Click the(+)icon anywhere in the access policy to add a new item.Only an applicable subset of access policy items is available for selection in the visual policy editor for any access profile type.A popup screen opens, listing predefined actions on tabs such as General Purpose, Authentication, and so on.
- On the Logon tab, selectLogon Pageand click theAdd Itembutton.The Logon Page Agent properties screen opens.
- Make any changes that you require to the logon page properties and clickSave.The properties screen closes and the policy displays.
- Click the(+)icon anywhere in the access policy to add a new item.Only an applicable subset of access policy items is available for selection in the visual policy editor for any access profile type.A popup screen opens, listing predefined actions on tabs such as General Purpose, Authentication, and so on.
- On the Authentication tab, selectLDAP Authand clickAdd Item.
- From theServerlist, select an AAA LDAP server.The LDAP Auth action uses SSL connections if you select an LDAP AAA server that is configured for LDAPS.
- Specify theSearchDN, andSearchFiltersettings.SearchDN is the base DN from which the search is done.
- ClickSave.The properties screen closes and the policy displays.
- ClickApply Access Policyto save your configuration.
This
creates a basic access policy that collects credentials and uses them to authenticate with an
LDAP server over SSL. In practice, an access policy might include additional types of
authentication and might also assign ACLS and resources
If you use LDAP Query,
Access Policy Manager does not query for the primary group and add it to the
memberOf
attribute. You must manually look up the attribute memberOf
as well as the primary group.Creating a virtual server for LDAPS
You should have an Access Policy Manager LDAP AAA server
configured in LDAPS mode.
You create a virtual server to handle LDAP traffic and to encrypt authentication
messages between Access Policy Manager and the LDAP server.
An AAA server does not load-balance. Do not select a local traffic pool
for this virtual server.
- On the Main tab, click.The Virtual Server List screen opens.
- ClickCreate.The New Virtual Server screen opens.
- In theNamefield, type a unique name for the virtual server.
- From theConfigurationlist, selectAdvanced.
- In theDestination Addressfield, type the IP address for the external LDAP server.When you type the IP address for a single host, it is not necessary to append a prefix to the address.This IP address must match a server address configured in the LDAP AAA server.
- In theService Portfield, type the port number for the LDAP server.The server port (389) is the virtual port used as the external LDAP server's service port.The LDAP AAA server uses the external LDAP server's SSL service port.
- From theSSL Profile (Server)list, selectserverssl.This ensures the SSL connection between the virtual server and the external LDAP server is in place.
- From theSource Address Translationlist, selectAuto Map.
- ClickFinished.
Testing LDAPS authentication
Before starting this procedure, make sure that all the appropriate steps were performed to
create an LDAPS authentication.
- Ensure that LDAP authentication works in your environment.An intermediate virtual server should not exist for this verification step.
- Create an access policy that uses a AAA object that points directly to the LDAP server.
- Add an intermediate virtual server without a server-side SSL profile.Using the same access policy that you just created, modify the AAA object to point to a virtual server.
- Implement LDAPS by enabling server side SSL, and change the pool member to use port636.
- Review the log messages in Access Policy Manager reports.
- Make sure to set the Access Policy log level toDebug.To set log levels, see
- Review the log for LDAP messages and locate and confirm that the bind and search operation succeeds.
Test AAA high availability for supported authentication servers
To effectively test that high availability works for your authentication servers, you should have two servers that are accessible, where you can remove one of them from the network.
High availability is supported for these authentication server types only: RADIUS, Active Directory, LDAP, CRLDP, and TACACS+.
If you configured a supported authentication server type to use a pool of connection servers, you can test the configuration using these steps.
- Begin atcpdumpon the Access Policy Manager, using a protocol analyzer, and scanning for packets destined for the specific port for your authentication server.
- Log in to the virtual server with both servers active.
- Using thetcpdumprecords, verify that the requests are being sent to the higher priority server.
- Log out of the virtual server.
- Disable the higher-priority server.
- Log in to the virtual server again.
- Verify that the request is being sent to the other server.
- Log out again, re-enabling the server, and try one more time to verify that the new requests are being sent to the high priority server.
Example of LDAP auth and query default rules
In this example, after successful authentication, the system retrieves a user group using an
LDAP query. Resources are assigned to users and users are directed to a webtop if the user group
has access to the network access resources.
In this figure, the default branch rule for LDAP query was changed to check for a specific user
group attribute.
Importing LDAP user groups
Import user groups from an LDAP server to make them available for assigning
resources to an LDAP group. When you configure the LDAP Group Resource Assign access
policy item, you can type group names to exactly match those on the LDAP server, or you
can select them from the imported list of groups.
- Select.The LDAP servers screen displays.
- Click the name of the server that you want to update.The Properties screen displays.
- From the menu bar, clickGroups.
- From the Groups area of the screen, clickUpdate.After uploading the list, the screen displays the number of groups, the date last updated, and the list of groups.
Assigning resources
to an LDAP group
You can select groups from a list that you upload from an LDAP server; alternately, or
in addition. you can type group names to exactly match LDAP groups. If you plan to
select groups and have not updated the list recently, update it from the Groups screen
for the AAA LDAP server before you start.
Use an LDAP Group Resource Assign action to assign
resources to one or more groups that are configured on the LDAP server. For every group
to which a user belongs, the corresponding resources will be assigned to the session.
- On a policy branch, click the(+)icon to add an item to the policy.A popup screen displays actions on tabs, such as General Purpose and Authentication, and provides a search field.
- On the Assignment tab, select theLDAP Group Resource Assignagent, and then clickAdd Item.The LDAP Group Resource Assign screen opens.
- To make a list of groups available, select a server from theServerlist.A brief pause occurs while the agent retrieves any groups that were previously uploaded from the LDAP server to the BIG-IP system.
- To add an entry, clickAdd entry.An entry must include at least one group and the resources to be assigned to it. You can add multiple entries.A numbered entry displays in the Groups area.
- In the Groups area, click theeditlink for the entry that you want to update.A popup screen opens to the Groups tab.
- If you need to add a group, in theNew Groupfield, type the name of a group that exists on the server and clickAdd group manually.When the access policy runs, this action queries the group names using thememberOfattribute in the directory.The group displays in the list on the Groups tab.
- Select at least one group.
- Repeat these steps for each type of resource that you require.The screen displays one tab for each resource type.
- Click a tab.
- Select the resources that you want to assign to the selected groups.
Typical resource assignment rules apply. For example, you can assign multiple webtop links to a group, but you can assign only one webtop. - Click theUpdatebutton.TheLDAP Group Resource Assignscreen opens, and displays the groups and resources in the entry in the Groups table.
- Create any additional entries that you require.
- ClickSave.The properties screen closes and the policy displays.
This configures an LDAP group resource assign action and adds it to the access policy.
LDAP authentication session variables
When the LDAP Auth access policy item runs, it populates session variables which are
then available for use in access policy rules. The tables list the session variables for the LDAP
Auth access policy items and for a logon access policy item.
Session variables for LDAP authentication
Session Variable | Description |
---|---|
session.ldap.last.authresult | Provides the result of the LDAP authentication. The available values are:
|
session.ldap.last.errmsg | Useful for troubleshooting, and contains the last error message generated for LDAP,
for example aad2a221.ldap.last.errmsg . |
Common session variables
Session Variable | Description |
---|---|
session.logon.last.username | Provides user credentials. The username string is stored after
encrypting, using the system's client key. |
session.logon.last.password | Provides user credentials. The password string is stored after
encrypting, using the system's client key. |
UserDN settings in LDAP
The following is an example of a typical UserDN usage for LDAP.
Access Policy Manager attempts to bind with the LDAP server
using the supplied DN and user-entered password. If the bind succeeds, that is,
authentication succeeds, the user is validated. If the bind fails, the authentication fails.
This value is a fully qualified DN of the user with rights to run the query. Specify this
value in lowercase and without spaces to ensure compatibility with some specific LDAP
servers. The specific content of this string depends on your directory layout.
For example, in an LDAP structure, a typical UserDN for query would be similar to the
following string:
cn=%{session.logon.last.username}, cn=users, dc=sales,
dc=com.
Access Policy Manager supports using session variables in the
SearchFilter
, SearchDN
, and
UserDN
settings.session.ssl.cert.last.cn
in place of
session.logon.last.username
.LDAP authentication and query troubleshooting
tips
You might run into problems with LDAP authentication and query in some instances. Follow
these tips to try to resolve any issues you might encounter.
LDAP auth and query troubleshooting
Possible error messages | Possible explanations and corrective actions |
---|---|
LDAP auth failed |
|
LDAP query failed |
|
Additional troubleshooting tips for LDAP
authentication
You should | Steps to take |
---|---|
Check that your access policy is attempting to perform authentication |
Make sure that your log
level is set to the appropriate level. The default log level is notice |
Confirm network connectivity |
|
Confirm network connectivity |
|
Check the LDAP server configuration |
A good test is to use full
administrative credentials with all rights. If that works, you can use less powerful
credentials for verification. |
Capture a tcpdump | Use the tcpdump utility on the BIG-IP system to record activities between Access Policy Manager and the authentication server when authentication
attempts are made.
If you decide to
escalate the issue to customer support, you must provide a capture of the tcpdump when you
encounter authentication issues that you cannot otherwise resolve on your own. |