Applies To:
Show Versions
BIG-IP APM
- 11.6.5, 11.6.4, 11.6.3, 11.6.2, 11.6.1
About user identification
Secure Web Gateway (SWG) identifies users and maps them to IP addresses, or to sessions, without using cookies.
About session management cookies and Secure Web Gateway
Secure Web Gateway (SWG) does not use Access Policy Manager (APM) session management cookies. If presented with an APM session management cookie, SWG ignores it.
About ways to configure user identification for SWG
User identification configuration requires a method setting in the access profile and an access policy configured to support the setting. Depending on the access profile type, you can select one of these user identification methods: by IP address (for SWG-Explicit or SWG-Transparent access profile types) or by credentials (for SWG-Explicit type).
Identification by IP address
When you identify users by IP address, you can employ any of these methods.
- transparent user identification
- Transparent user identification makes a best effort to identify users without
requesting credentials.
An agent obtains
data and stores a mapping of IP addresses to user names in an IF-MAP server. An F5 DC
Agent queries domain controllers. An F5 Logon Agent runs a script when a client logs in
and can run a script when the client logs out. Note: To identify users transparently, you must first install and configure one BIG-IP user identification agent, either the F5 DC Agent or the F5 Logon Agent.
- explicit user identification
- You can present a logon page in an access policy to request user credentials and validate them. SWG maintains an internal mapping of IP addresses to user names. (You can present the appropriate logon page for the access policy type. For explicit forward proxy, you can present a 407 page. For transparent forward proxy, you can present a 401 page.)
- source IP ranges or subnets
- You can forego actually identifying the user and base the choice of which scheme to apply on whether the IP address is in a source IP range or on a subnet. SWG maintains an internal mapping of IP addresses to sessions.
Identification by credentials
When you choose to identify users by credentials, SWG maintains an internal mapping of credentials to sessions. To support this choice, you need an NTLM Auth Configuration object and you should check the result of NTLM authentication in the access policy.
Overview: Identifying users transparently using F5 DC AgentConfiguring F5 DC Agent to support the IF-MAP service
The F5 DC Agent enables transparent user identification, a best effort to identify users without requesting credentials.

You can install the F5 DC Agent on a Windows-based server in any domain in the network. The F5 DC Agent discovers domains and domain controllers, queries the domain controllers for logon sessions, and sends an IP-address-to-user-name mapping to the BIG-IP system. F5 DC Agent sends only those new user name and IP address pairs recorded since the previous query. The BIG-IP system maintains user identity information in an IF-MAP server and stores only the most recently identified user name for a given IP address.
Considerations for installing multiple agents
You can install more than one F5 DC Agent in your network and configure F5 DC Agents to communicate with the same BIG-IP system.
- NetBIOS port 139
- F5 DC Agent uses NetBIOS port 139 for automatic domain detection. If NetBIOS port 139 is blocked in your network, you can deploy an F5 DC Agent instance for each virtually or physically remote domain.
- Multiple subnets
- As a best practice, install a separate F5 DC Agent in each subnet to avoid problems gathering logon information from domain controllers.
- Network size, disk space, and RAM
- If your network is very large (10,000+ users or 30+ domain controllers), you might benefit from installing F5 DC Agent on multiple machines to evenly distribute resource usage. F5 DC Agent uses TCP to transmit data, and transmits roughly 80 bytes per user name and IP address pair.
Number of users | Average amount of data transferred per day |
---|---|
250 users | 30 KB |
2,000 users | 240 KB |
10,000 users | 1200 KB |
Task summary
Configuring the BIG-IP system for the F5 DC Agent
Verifying network communication
Downloading and installing F5 DC Agent
Updating privileges for the F5 DC Agent service
-
On the Windows-based server, create a user account for F5 DC Agent:
-
Configure the F5 DC Agent service to log on as the user account you just
configured:
Configuring the initialization file
Configuring domain controller polling in the dc_agent.txt file
Recovering from an unsuccessful installation
- Log on to the Windows-based server from a user account with local and domain administrator privilege.
- From the Windows Programs and Features dialog box, uninstall the F5 Installer application.
- From Windows Explorer, click the SWGUserIdentificationAgents.exe file and follow the instructions to install F5 DC Agent again.
Enabling debug logging for the F5 DC Agent
Troubleshooting when a user is identified incorrectly
- Log on to the client system that belongs to the user.
- Open a browser and navigate to four or more distinctive web sites.
- Log on to the Windows-based server where the F5 DC Agent is installed.
- Look for error messages in the Windows Event Viewer.
- Proceed based on any error messages that you discover.
F5 DC Agent error messages
Error messages from the F5 DC Agent display in the Event Viewer on the Windows-based server where DC Agent is installed.
Error code | Error message | Possible causes |
---|---|---|
3 | Could not configure DC Agent (Code 3) | An attempt was made to install F5 DC Agent using an account that does not have domain and local administrator privileges. As a result, some required files are not installed properly, and F5 DC Agent service cannot run. |
5 | ERROR_ACCESS_DENIED | F5 DC Agent service does not have sufficient permissions to perform required
tasks. This error can occur when:
|
53 | ERROR_BAD_NETPATH | A network problem prevents F5 DC Agent from contacting a domain controller. This
error can occur when:
|
71 | System error while enumerating the domain controllers. domain: (****)ecode: 71 : message: No more connections can be made to this remote computer at this time because there are already as many connections as the computer can accept. | The error results from F5 DC Agent automatic domain discovery process, used to identify new domains and domain controllers. It can also occur when F5 DC Agent tries to connect to a Windows XP-based computer that is broadcasting itself as the master browser for a non-company domain or workgroup. Although the issue might indicate a problem with connectivity to the domain controller, it is more likely that the domain is a workgroup with no domain controllers. This error can be ignored. |
997 | Error Code 997 | An attempt was made to install F5 DC Agent using an account that does not have domain and local administrator privileges. As a result, some required files are not installed properly, and F5 DC Agent service cannot run. |
1058 | Error Code 1058 | This error is seen on startup. A Local Security Policy on the Windows-based server might have disabled the F5 DC Agent service. |
Overview: Identifying users transparently using F5 Logon AgentConfiguring F5 Logon Agent to support the IF-MAP service
The F5 Logon Agent enables transparent user identification, a best effort to identify users without requesting credentials.
You can install the F5 Logon Agent on a Windows-based server in any domain in the network. The F5 Logon Agent identifies users in real time when the users log on to domains, which prevents missing a user logon because of a query timing issue. F5 Logon Agent sends up-to-date session information to the BIG-IP system.
F5 Logon Agent identification process
- When users log on to the network, a network logon script invokes the logon application (LogonApp.exe).
- The logon application contacts F5 Logon Agent using HTTP.
- F5 Logon Agent sends an NTLM authentication challenge, and the logon application provides a user name, hashed password, and IP address to F5 Logon Agent.
- F5 Logon Agent verifies the username and password combination from the logon application by establishing a session with the domain controller. (F5 Logon Agent contacts User Service to determine which domain controller is the logon source.)
- After verifying the user name and IP address pair, F5 Logon Agent sends the information to the BIG-IP system and adds an entry to its user map in local memory. The user map is periodically saved to a backup file, AuthServer.bak.
- The BIG-IP system records user name and IP address pairs to the BIG-IP system copy of the user map in local memory. Confidential information (such as user passwords) is not sent to the BIG-IP system.
Considerations for installing multiple agents
You can install more than one F5 Logon Agent in your network, and configure F5 Logon Agents to communicate with the same BIG-IP system. If you have multiple BIG-IP systems, each BIG-IP system must be able to communicate with every F5 Logon Agent in your network.
- NetBIOS port 139
- F5 Logon Agent uses NetBIOS port 139 for automatic domain detection. If NetBIOS port 139 is blocked in your network, you can deploy an F5 Logon Agent instance for each virtually or physically remote domain.
- Multiple subnets
- As a best practice, install a separate F5 Logon Agent in each subnet to avoid problems gathering logon information from domain controllers.
- Network size, disk space, and RAM
- If your network is very large (10,000+ users or 30+ domain controllers), you might benefit from installing F5 Logon Agent on multiple machines to evenly distribute resource usage.
Task summary
Configuring the BIG-IP system for the F5 Logon Agent
Verifying network communication
Downloading and installing F5 Logon Agent
Updating privileges for the F5 Logon Agent service
-
On the Windows-based server, create a user account for F5 Logon Agent:
-
Configure the F5 Logon Agent service to log on as the user account you just
configured:
Configuring the initialization file
Recovering from an unsuccessful installation
- Log on to the Windows-based server from a user account with local and domain administrator privilege.
- From the Windows Programs and Features dialog box, uninstall the F5 Installer application.
- From Windows Explorer, click the SWGUserIdentificationAgents.exe file and follow the instructions to install F5 Logon Agent again.
Enabling debug logging for the F5 Logon Agent
Troubleshooting when a user is identified incorrectly
- Log on to the client system that belongs to the user.
- Open a browser and navigate to four or more distinctive web sites.
- Log on to the Windows-based server where the F5 Logon Agent is installed.
- Look for error messages in the Windows Event Viewer.
- Proceed based on any error messages that you discover.
Files used by Logon Agent
This table explains the relevant files used by F5 Logon Agent after you install the installation file from the BIG-IP system Configuration utility Welcome screen.
Filename | File location | Additional information |
---|---|---|
LogonApp.exe | Stored in User Identity Agents > LogonApp > Windows folder. |
Sends user information to F5 Logon Agent Captures user logon sessions as they occur. Runs on Windows client machines. |
logon.bat | Stored in User Identity Agents > LogonApp > Windows folder. | Invokes LogonApp.exe, which runs on client machines and captures logon sessions. |
AuthServer.ini | Stored in User Identity Agents > config folder. | Contains one initialization parameter for Logon Agent. |
Overview: Creating a script on a Windows system for F5 Logon Agent
When you install the F5 Logon Agent, you must create a logon script for clients that identify the clients to the BIG-IP system when they log on to a Windows domain. The application, LogonApp.exe, provides a username and IP address to F5 Logon Agent each time a Windows client connects to a Windows Active Directory or a Windows NT directory service.
When installing F5 Logon Agent, the following files are placed in the F5 Networks folder (by default, C:\Program Files\F5 Networks\User Identity Agents\LogonApp):
- LogonApp.exe
- logon.bat
Task summary
Creating a logon or logout script
Running a logon or logout script on Active Directory
Logon and logout script parameters
This table explains the relevant parameters used by a logon or logout script for F5 Logon Agent.
Parameter | Description |
---|---|
<server> | The IP address of the BIG-IP system F5 Logon Agent. |
<port> | The port number used by F5 Logon Agent. The default value is 15880. |
/NOPERSIST |
Triggers the logon application to send user information to F5 Logon Agent only at logon. The username and IP address are communicated to the server during the logon process and remain in the F5 Logon Agent user map until the user data is automatically cleared at a predefined time interval. The default user entry expiration is 24 hours. If the NOPERSIST parameter is omitted, LogonApp.exe operates in persistent mode, located in the memory of the domain server and updates F5 Logon Agent with the usernames and IP addresses at predefined intervals. The default interval is 15 minutes. The following example logon script sends user information to F5 logon Agent at the logon step only. The information is not updated during the user's session (NOPERSIST). The information is sent to port 15880 on the server identified by IP address 10.2.2.95. LogonApp.exe http://10.2.2.95:15880 /NOPERSIST |
/COPY | Copies the logon application to the %USERPROFILE%\Local Settings\Temp directory on the user machine, where the logon script runs it from the local memory. This optional parameter helps prevent your logon script from hanging. COPY can be used only in persistent mode. |
/VERBOSE | A debugging parameter that can be used only with help from technical support. |
/LOGOUT |
Used only in an optional logout script, this parameter removes the user's logon information from the F5 Logon Agent user map when the user logs off. If you use Active Directory, this parameter can clear the logon information from the user map before the interval that is defined for F5 Logon Agent has elapsed. Use this optional parameter in a logout script in a batch file that is different than the one containing the logon script. The following example logout script clears the logon information for each user as soon as the user logs out. LogonApp.exe http://10.2.2.95:15880 /NOPERSIST /LOGOUT |