Applies To:Show Versions
- 11.5.9, 11.5.8, 11.5.7, 11.5.6, 11.5.5, 11.5.4, 11.5.3, 11.5.2, 11.5.1
About user identification
Secure Web Gateway (SWG) identifies users and maps them to IP addresses, or to sessions, without using cookies. Based on user identity, SWG assigns the appropriate scheme to each user. A scheme categorizes and filters URLs.
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. Based on user identification, you can determine which scheme to assign in the access policy so that Secure Web Gateway (SWG) filters URLs appropriately.
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. It queries domain controllers and stores a mapping of IP addresses to user
names in an IF-MAP server. Note: To identify users transparently, you must first install and configure the F5® DC 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.
- single scheme
- You can apply the same scheme to all users. 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
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|
Configuring the BIG-IP system for the F5 DC Agent
To support certificate inspection:
- Obtain a trusted certificate and key that are valid for all fully qualified domain names (FQDNs) used to access the BIG-IP system.
- Import the certificate and key into the BIG-IP system. You can import SSL certificates from the System area of the product.
- Obtain the IFMap iApps template file from F5® DevCentral™at http://devcentral.f5.com/wiki/iapp.Codeshare.ashx.
Import the template:
- On the Main tab, click .
- Next, click Import.
- Select the Overwrite Existing Templates check box.
- Click Choose File, then browse to and choose the template file.
- Click Upload.
Deploy an application service:
- On the Main tab, click Create. , and then click
In the Name field, type a name.
Note: The application service prefixes this name to the names of configuration objects it creates.
- From the Template list, select f5.ifmap.
- Follow the instructions on the screen to complete the deployment. A summary displays the configuration objects.
- Take note of the IP address of the virtual server created by the service. You need to type it into F5 DC Agent initialization file later.
To enable clientless HTTP basic authentication, create a user and password in
the local user database.
The purpose of this user account is to authenticate communication between the
F5 DC Agent and Secure Web Gateway.
- On the Main tab, click The Manage Users screen displays. .
- Click Create New User. The Create New Local User screen opens and displays User Information settings.
- From the Instance list, select the instance created when you deployed the application service.
- In the User Name field, type the user name. Take note of the user name and password. You need to type them again later when you configure the initialization file for F5 DC Agent.
- In the Password and Confirm Password fields, type the user's password.
Verifying network communication
- Open a command prompt on the Windows-based server.
- To verify that the Windows-based server sees all required domains, use the net view command. For example, type net view /network
- To check for DNS issues, use the nslookup command. For example, to verify that DNS resolves the host name, testmachine1, type this command: nslookup testmachine1. If the DNS lookup succeeds, the result is similar to: Server: testdns.test.example.com Address: 10.56.1.4 Name: testmachine1.test.example.com Address: 10.56.100.15
To verify that F5 DC Agent will be able to use NetBIOS, try to telnet to a
domain controller on port 139.
If the command is successful, the screen remains blank. If unsuccessful,
- A a router, firewall, or other device might be blocking NetBIOS traffic.
- NetBIOS might not be enabled and the domain controller might not be listening on port 139.
- If you could not successfully telnet to a domain controller on port 139, verify the status of the port using the netstat command. For example, type netstat -na | find "139".)
Downloading and installing F5 DC Agent
- Go to the Configuration utility Welcome screen. If you are already logged in, click the F5® logo to open the Welcome screen.
- In the Secure Web Gateway User Identification Agents area, click the DC Agent link. A DC Agent.exe file downloads.
Copy the downloaded file to a Windows-based server that is joined to a domain
Important: Do not install F5 DC Agent on a domain controller because the F5 DC Agent can put a load on the domain controller.
- From an account with both local and administrator privileges, click the DC Agent.exe file to start the installer. The installer displays instructions.
Follow the instructions to complete the installation.
Important: F5® strongly recommends that you use the default destination folder. On the Destination Folder screen, click Next without making any changes.The program installs a Windows service, F5 DC Agent.
Updating privileges for the F5 DC Agent service
On the Windows-based server, create a user account for F5 DC Agent:
- Assign the new account domain administrator privileges in all domains.
- Assign the same password to this account in all domains. Make a note of the password. You must type it again in step 2.
- Set the password to never expire.
Configure the F5 DC Agent service to log on as the user account you just
- Open the Windows Services dialog box. From the Control Panel, select .
- Locate the F5 DC Agent service, right-click the service name, and select Stop.
- Double-click the service name, and then select the Log On tab.
Select This account and type the account name
and password for the account you created in step 1.
Note: Some domains require that you type the account name in the format domain\username.
- Close the Services dialog box.
Configuring the initialization file
- Log on to the Windows-based server where you installed the F5 DC Agent.
- Navigate to this directory: C:\Program Files\F5 Networks\bin\config.
- Using a text editor, open the transid.ini file. The file contains one section, [DC Agent].
- For IFMapServer, type the protocol, host address, and port for the server. This is the virtual server that was created by the application service. Port 8096 is the default port. You might have specified another port number when you deployed the application service. For example, IFMapServer=https://AA.BB.CC.DD:8096, where AA.BB.CC.DD is the IP address of the server.
To authenticate to the BIG-IP system using clientless HTTP authentication, type
values for these parameters.
- For IFMapUsername, type the name of the user that logs on to the IF-MAP server on behalf of the F5 DC Agent. This is the name of a user you created in the local user database on the BIG-IP system.
- For IFMapPassword, type the password for the user. This is the password you typed in the local user database.
- Optional: To authenticate using a certificate, for IFMapCertClient, type the path to the SSL certificate file to use for authenticating to the BIG-IP system. This must match the name of the certificate you specified in the application service on the BIG-IP system. Make sure that this certificate is imported into the certificate store on the BIG-IP system.
For the remainder of the parameters, you can retain the default values or
For IFMapLifeTimeType, retain the default value,
IFMapLifeTimeType specifies whether to keep or
purge a user entry from the IF-MAP server when a session ends or times
out. The alternative value is session. Note: You can specify an absolute lifetime for a user entry in the IPCleanLifetime property.
- For PurgeOnStart, retain the default value, true. PurgeOnStart specifies whether the IF-MAP server should purge user records after the F5 DC Agent restarts.
- For IdleUpdate, you can retain the default value of 120 seconds. IdleUpdate specifies the interval between keep-alive pings from the F5 DC Agent to the IF-MAP server.
- For DiscoveryInterval, retain the default value of 84600 seconds (24 hours). DiscoveryInterval specifies the interval at which the domain auto-discovery process runs.
- For DC AgentEnable, retain the default value of true. DC AgentEnable specifies whether domain auto-discovery is enabled (true) or disabled (false).
- For QueryInterval, you can retain the default value of 10 seconds. QueryInterval specifies the interval at which the F5 DC Agent queries domain controllers in seconds. Valid values are between 5 and 90 seconds.
- For IPCleanLifetime, you can retain the default value of 7200 seconds (2 hours). IPCleanLifetime specifies the amount of time a user entry remains in the IF-MAP server before it is removed, in seconds. Valid values are integers greater than 3600, 0 to disable.
- For IFMapLifeTimeType, retain the default value, forever. IFMapLifeTimeType specifies whether to keep or purge a user entry from the IF-MAP server when a session ends or times out. The alternative value is session.
- Start or restart the F5 DC Agent service.
Configuring domain controller polling in the dc_agent.txt file
- Log on to the Windows-based server where you installed the F5 DC Agent.
- Navigate to this directory: C:\Program Files\F5 Networks\bin\.
- If the dc_config.txt file already exists, make a backup copy in another location.
- Create or open the dc_config.txt file using a text editor.
- Verify that all domains and controllers are on the list. This example shows two domain controller entries in each of two domains, WEST_DOMAIN and EAST_DOMAIN; polling is enabled on each domain controller. Note the blank line at the end of the file; it is required.[WEST_DOMAIN] dcWEST1=on dcWEST2=on [EAST_DOMAIN] dcEAST1=on dcEAST2=on
- If domains or domain controllers are missing, add them. To make sure that F5 DC Agent can see a domain, run the net view /domain command before you add the domain.
If the list contains domain controllers that F5 DC Agent should not poll, change
the entry value from on to off.
If you configure F5 DC Agent to avoid polling an active domain controller, the
agent cannot transparently identify the users that log on to it. Important: Rather than deleting a domain controller, change the setting to off. Otherwise, F5 DC Agent adds it to the file again after it next discovers domain controllers.In this example, polling is disabled for the dcEAST2 domain controller. dcEAST2=off
- Make sure that the file includes a carriage return after the last entry, creating a blank line at the end of the file. If you do not include the hard return, the last entry in the file get truncated, and an error message is written.
- Save the changes and close the file.
- Use the Windows Services dialog box to restart the F5 DC Agent service.
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 DC Agent.exe file and follow the instructions to install F5 DC Agent again.
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.|