en-US
search-icon

Directory Services Connector 4.0 Admin Guide

Installation and Configuration

 

Installing and Configuring the SSO Agent

This section provides information about installing and configuring the SSO Agent using the Directory Services Configuration Tool.

* 
NOTE: For best performance, SonicWall recommends installing the SSO Agent on a dedicated system.

When using NetAPI or WMI, one SSO Agent can support up to approximately 2500 users, depending on the performance level of the hardware that it is running on, how it is configured on the firewall and other network-dependent factors. When configured to read from domain controller security logs, one SSO Agent can support a much larger number of users identified via that mechanism, potentially 50,000+ users depending on similar factors.

Topics

Installing the SSO Agent with Active Directory

When using SSO with Windows, install the SonicWall SSO Agent on a host on your network that has access to the Active Directory server, the SonicWall network security appliance, and all client workstations.

* 
IMPORTANT: For best performance, SonicWall recommends installing the SSO Agent on a dedicated system.
* 
IMPORTANT: To run the SSO agent, .NET Framework v4.0 must be installed. If it is not installed, an error message appears.
Topics:

Installing the SSO Agent

To install the SonicWall SSO Agent for use with AD:
1
Download one of the following installers, depending on your computer:
SonicWall Directory Connector (32-bit) 4.0.29.exe
SonicWall Directory Connector (64-bit) 4.0.29.exe

You can find these on https://www.mysonicwall.com under Directory Services Connector. The installer is an MSI file signed by SonicWall Inc.

2
To begin installation, double-click the installer.

The installer uninstalls the previous SSO Agent automatically if its version is equal to or greater than 4.0. You can have both SSO Agent 3.x and SSO Agent 4.x installed at the same time, although only one can be running because they use the common port.

3
In the Welcome screen, click Next to continue the installation.

The License Agreement screen displays.

4
Accept the terms of the license agreement, and then click Next.
* 
TIP: To print a copy of this agreement, click Print.

The Destination Folder screen displays.

5
Select the destination folder:
To use the default folder, C:\Program Files\SonicWall\SSOAgent\, click Next.
To specify a custom location, click Change, select the folder, and then click Next.

What displays next, depends on whether this is a new installation or an upgrade:

For new installations, the Service User Configuration screen displays. Go to Step 7.
If your system has an older version of Directory Services Connector, a Service Configuration screen displays asking if you want to use the existing configuration. The Check this check box if want to use old configuration checkbox is selected by default.

6
Do one of the following:
To use the old configuration, click Next. The Service User Configuration screen displays. Go to Step 7.
To reconfigure the SSO product, clear Check this check box if want to use old configuration and then click Next.
7
Use the Service User Configuration screen to configure a common service account that the SSO Agent will use to log into a specified Windows domain.

* 
TIP: This section can be configured at a later time. To skip this step and configure it later, click Skip. Go to Step 8.
a
Enter the domain name of the account in the Domain Name field.
b
Enter the username of an account with administrative privileges in the Username field.
c
Enter the password for the account in the Password field.
d
Click Next.

The Appliance Configuration screen displays.

8
Use the Appliance Configuration screen to configure the IP address and port used for communication with the firewall.

a
Enter the IP address of your SonicWall security appliance in the SonicWall Appliance IP field.
b
Type the port number for the same appliance into the SonicWall Appliance Port field. The default port number is 2258.
c
Enter the hexadecimal representation (an even number of digits using only hexadecimal numbers) of the shared key in the Shared Key field.
d
Click Next. The Install screen displays.

9
Click Install to begin the installation. A Installing progress screen displays.
10
Wait for the installation to complete. A warning screen requesting permission to install files may display; click Yes.

The status bar displays while the SonicWall SSO Agent installs.

Program and service files are installed, including the SSOAgentService. If the SSO Agent 3.x service is running, the installer stops that service and then starts the newly installed service.

A Completed screen displays.

* 
IMPORTANT: To run the SSO agent, .NET Framework v4.0 must be installed. If it is not installed, an error message appears:

11
When the installation is complete, optionally select the Launch SonicWall Directory Connector checkbox to launch the SonicWall Directory Connector Configuration Tool. This option is not selected by default.
12
Click Finish.

The installer creates a desktop shortcut for the SonicWall Directory Connector Configuration Tool.

If you selected the Launch SonicWall Directory Connector checkbox, the Directory Connector Configuration Tool displays.

Installed Files

Topics:

Program Files

The installer places all the program files into C:\Program Files\SonicWall\SSOAgent by default:

SSOAgentUI.exe is the configuration UI program.
SSOAgentService.exe is the service program.
Plugins\SSOAgent.dll is a part of the service program.
Config.xml is the main configuration file.

The following additional files may also exist in that directory:

static.csv is used for automation load testing.
Users.xml is the user list that is saved during service restart.

The installer also creates short cuts in the Start menu and on the desktop.

Log Files

Log files and crash dump files are placed in C:\ProgramData\SonicWall\SSOAgent.

Configuring SonicWall Devices

To display all the configured SonicWall network security appliances, click on SonicWall Appliances in the left panel of the Directory Services Connector Configuration Tool.

The Friendly Name, Port, IP address, and Status of each appliance is displayed.

To add a SonicWall appliance to the SSO Agent:
1
Launch the Directory Services Connector Configuration Tool either from the Start menu or by double-clicking the desktop shortcut.
2
Right-click SonicWall Appliances, and then select Add.

3
In the Appliance IP field, type in the IP address of the firewall.
4
In the Appliance Port field, accept the default port of 2258 or type in a custom port. The appliance sends the SSO protocol packets to the Agent on this port.
5
In the Friendly Name field, type in a descriptive name for this appliance.
6
In the Shared Key field, do one of the following:
Type in a hexadecimal number of up to 16 characters (use an even number of characters) to use as the key for encrypting messages between the SonicWall appliance and the SSO Agent. You must also enter the same key when configuring the SSO Agent to communicate with the appliance.
Click the Generate Key button to let the computer generate a random shared key.
7
Select the Check to show Shared key as clear Text checkbox to view the key in clear text. This option is not selected by default.
8
Click OK to save the configuration.
* 
NOTE: To modify the settings of an existing appliance, click on the appliance IP address in the left pane.
9
Click OK in the Configuration saved! dialog.

Configuring SSO Agent Communication Properties

The SonicWall SSO Agent communicates with workstations using NetAPI or WMI, which both provide information about users logged into a workstation, including domain users, local users, and Windows services. Be sure that WMI or NetAPI is installed prior to configuring the SonicWall SSO Agent.

* 
NOTE: When using Single Sign-on, SSO Agent tries to identify the logged in user by querying the workstations using the NetAPI or WMI protocols. NetAPI and WMI require File & print sharing enabled on the client workstations.
To configure the communication properties of the SonicWall SSO Agent:
1
Launch the Directory Services Connector Configuration Tool either from the Start menu or by double-clicking the desktop shortcut.
* 
NOTE: The Configuration Tool communicates with the Windows service through JSON RPC. The RPC port is 127.0.0.1:12348. If the service is stopped, the Configuration Tool tries to start the service first.

2
In the left panel, right click SonicWall SSO Agent, and then select Properties. Configuration settings display in the right panel.

3
For Host IP, select an IP address from the drop-down menu. The default IP address is  0.0.0.0.

The SSO Agent binds the UDP socket at this IP address and the port number specified in the Port field. The Agent receives the SSO protocol packets from the firewall on this socket.

* 
NOTE: If the Host IP address is 0.0.0.0, the SSO Agent accepts packets from any interface.
4
In the Port field, accept the default port or type in a custom port. By default, the SSO Agent uses UDP port 2258 to receive the SSO protocol packets.
5
In the Sync Port field, accept the default port or type in a custom port. By default, the SSO Agent uses TCP port 2260 to receive the agent synchronize datagrams.
6
From the Logging Level the drop-down menu, select the level of events to be logged in the log file in the program data directory. The log file is useful for diagnostics and debugging. The default logging level is 2 - Warning.

7
In the Max Thread Count field, accept the default of 100 or type in a custom value within the indicated range.

The SSO Agent starts the configured number of threads at run time. Most of the threads are used for client probing. These threads periodically query the IP addresses that are present in the Scanner queue. After completing each query, the agent adds or updates the user or error information in its cache. The thread count adjusts the trade off between simultaneity and overall performance.

8
In the Cache Duration field, accept the default of 7200 seconds (2 hours) or type in a custom value within the indicated range.

If a user does not log off the computer properly, for example by pulling the power plug, the SSO Agent does not receive a log-off message for the user. In this case, the SSO Agent keeps the user information in its cache. After the cache duration time expires, the SSO Agent removes the user from the cache and sends a log-out notification to the firewall. The default time of 2 hours is based on the typical duration after which the log-in status is refreshed on the Domain Controller. Cache duration functions only apply to users whose session ID is not equal to zero.

Upon a user information request for any IP address from the appliance, the SSO Agent checks for the IP address in its cache. If the IP address is not present in the cache, the SSO Agent treats the request as the first request for that IP Address and adds the IP Address to its Scanner queue for further processing.

9
To save information about previously identified users when the SSO Agent service is restarted, select the Preserve Users During Restart checkbox. This option is not selected by default.

Because the SSO Agent must be restarted for Properties changes to take effect, this option allows the Agent to maintain current user information across these restarts. The SSO Agent saves the user information in an XML file that contains a timestamp. If the file is less than 15 minutes old when the SSO Agent restarts, it uses this file to fill its cache; otherwise, the SSO Agent ignores the file to avoid restoring outdated information.

10
The Scan Users checkbox is selected by default.

If Scan Users is enabled and a user is identified with a Client Probing method, the SSO Agent probes this user repeatedly until the user logs off the computer or the SSO Agent can identify this user using another method, such as DC Security Log or Server Session. When the SSO Agent detects that the user has logged off the computer, it sends a log-off notification to the firewall.

If the query returns an error for any IP address and the SSO Agent is not able to identify the user information, the agent treats the IP address as a Bad IP. This can occur for network devices such as printers, non-Windows computers, or other workstations that do not understand the query options. While processing requests in the Scanner queue, the agent skips any Bad IP addresses and adds the IP address to the back of the queue for the next fetch.

To ensure that the agent does not process any IP address that has not been polled from the appliance for a considerable amount of time, the agent maintains the session time and the time of the last request from the appliance for each IP address. This allows the agent to minimize the queue size, ensures that threads are not wasted, and prevents unnecessary traffic from the agent for IP addresses that are not polled from the appliance. The session time can be modified from Windows registry settings using the registry value, SESIONTIME.

11
In the Scan Interval field, accept the default of 60 seconds or type in a custom value within the indicated range.
12
For Client Probing Method, select one of the following options from the drop-down menu:
Disabled
Probe user using NetAPI
Probe user using WMI
Probe user using NetAPI first, then WMI (this is the default option)
Probe user using WMI first, then NetAPI

When the SSO Agent receives an IP Address request from the firewall and the user is not found in its cache, it uses the selected Client Probing Method to identify the username.

* 
NOTE: NetAPI provides faster, though possibly slightly less accurate, performance. With NetAPI, Windows reports the last login to the workstation whether or not the user is still logged in. This means that after a user logs out from his computer, the appliance still shows the user as logged in when NetAPI is used. If another user logs onto the same computer, then at that point the previous user is logged out from the SonicWall appliance.

The handling of non-responsive workstations to queries from WMI and NetAPI is optimized in SonicWall Directory Services Connector. The appliance repeatedly polls the SSO Agent with multi-user requests, and often sends more than one such request at a time. The number of concurrent requests increases when workstations do not respond to the requests, potentially overloading the Agent. To avoid this, a time-out mechanism is included in multi-user requests from the appliance. If the request does not complete within this time, the agent silently aborts it.

13
For Domain name type, select one of the following options from the drop-down menu:
NetBIOS Domain Name
FQDN Domain Name

SonicOS can handle both domain name types. The default option is NetBIOS Domain Name.

14
Click Apply.
15
Click OK.

Configuring Domain Controller Settings

The Domain Controller (DC) is a server that responds to security authentication requests (logging in, checking permissions, and so on) within the Windows domain. The SSO Agent supports two methods to identify users who logon to a Windows domain:

DC Security Log
Server Session

Using Microsoft Windows, the DC Security Log contains login and logout activity records or other security-related events specified by the Domain Controller’s audit policy.

By default, all of the DC Security Log options require a Domain Administrator account or a Local Administrator account on the Domain Controller to read the DC Security Log.

If an account with administrator privileges is not available, user identification through the DC Security Log can be configured for WMI with a non-administrator domain account. This account must have read access to the security log. For more information, refer to the Configuring a Non-Admin Domain Account for SSO Agent to Read Domain Security Logs configuration guide.

Topics:

Configuring DC Settings in Directory Services Connector

To configure the Domain Controller settings in Directory Services Connector:
1
In the Directory Connector Configuration Tool, expand SonicWall SSO Agent in the left pane.
2
Right-click Domain Controllers, and then select one of the following:

Refresh

This option refreshes the known Domain Controller information, and the right panel displays the Host Address, Friendly Name, Domain Name, NETBIOS Name, and Status of known DCs.

Add

Select this option to manually add a Domain Controller to the SSO Agent configuration. Go to Step 3.

Auto Discovery

Select this option to have the SSO Agent use DNS queries to find DCs to which the Agent host machine belongs. The right panel displays the Host Address, Friendly Name, Domain Name, NETBIOS Name, and Status of the discovered DCs

Config All

Select this option to configure the settings for all known DCs in a pop-up window.

If you selected any option except Add, go to Step 7.

3
If you selected the Add option, the right panel displays the available settings. In the IP Address field, type the Domain Controller IP address.

 
4
In the Friendly Name field, enter a descriptive name for the Domain Controller.
5
For Server Monitoring Method, select one of the following:
DC Security Log Subscription

You can select this method for getting DC event log updates if the Domain Controller and SSO Agent are installed on Windows machines that support the event subscription API. It is supported on Windows 7 and higher, and on Windows Server 2008 and higher.

DC Security Log Polling

This option causes the SSO Agent to request the event log information from the DC at the time interval indicated in the Pull every field. Accept the default of 5 seconds or type in the desired interval. The minimum is 5 seconds and the maximum is 300 seconds.

Server Session

This option causes the SSO Agent to request the server session information from the DC at the time interval indicated in the Pull every field. Accept the default of 10 seconds or type in the desired interval. The minimum is 5 seconds and the maximum is 300 seconds.

6
To test the connection to the Domain Controller using the configured IP address, click Test Connection.

If the IP address does not belong to a machine with a role of Domain Controller, the Configuration Tool displays an error message.

7
If no errors are displayed, click OK.

Setting Group Policy to Enable Audit Logon on Windows Server 2008

Audit Logon may need to be enabled on the Windows Server machine.

To enable Audit Logon on Windows Server 2008:
1
Start the Group Policy Management Console.
2
Browse to the following location: Domain Name > Domains > Domain Name > Group Policy Objects, where Domain Name is replaced with your domain.
3
Under Group Policy Objects, right-click on Default Domain Policy, and then select Edit.

The Group Policy Management Editor window displays.

4
Double-click on Audit account logon events, select Success, and then click OK.
5
Double-click on Audit logon events, select Success, and then click OK.
6
Double-click on Audit Directory Service Access, select Success, and then click OK.
7
Double-click on Audit Object Access, select Success, and then click OK.
8
Close the Group Policy window.

Setting Group Policy to Enable Audit Logon on Windows Server 2003

By default, Audit Logon is disabled on Windows Server 2003.

To enable Audit Logon on Windows Server 2003:
1
Start the Group Policy Management Console.
2
Browse to the following location: Domain Name > Domains > Domain Name > Group Policy Objects, where Domain Name is replaced with your domain.
3
Right-click on Group Policy Objects, and then select New.

4
Enter a policy name, and then click OK.
5
Expand the Group Policy Objects folder and find your new policy.
6
Right-click on the policy, and then select Edit...
7
Browse to the following location: Policy Name > Computer Configuration > Windows Settings > Security Settings > Local Policies > Audit Policy.
8
Left-click on Audit Policy. The policy settings are displayed in the right pane.

9
Double-click on Audit account logon events, select Success, and then click OK.
10
Double-click on Audit logon events, select Success, and then click OK.
11
Double-click on Audit Directory Service Access, select Success, and then click OK.
12
Close the Group Policy window.

Configuring Exchange Server Settings

For information about using an Exchange server to identify users, see About Exchange Servers.

To add an Exchange server for use by the SSO Agent:
1
Launch the SonicWall Directory Services Connector Configuration Tool.
2
Expand the SonicWall Directory Connector and SonicWall SSO Agent trees in the left column by clicking the + button.
3
Right-click Exchange Servers, and hen select Add.
* 
NOTE: You can configure settings for all known Exchange servers at the same time by selecting Config All.

4
In the Exchange Server IP field, type in the Exchange server IP address.
5
In the Friendly Name field, type in a descriptive name for the Exchange server.
6
For Server Monitoring Method, select one of the following methods for the SSO Agent to get the event logs from the server:
Use Event Subscription

This method causes the SSO Agent to request that the Exchange server automatically send any relevant events to the Agent as they occur.

Pull every <> seconds

This is the polling method. The SSO Agent requests information from the Exchange server at the configured interval.

If Pull every <> seconds is selected, accept the default polling interval of 10 seconds or type in the desired interval in the provided field. The minimum is 1 second and the maximum is 60 seconds.

7
Click OK.
8
Click OK in the popup window indicating that the configuration is saved.

Configuring Novell eDirectory Settings

For information about using Novell eDirectory to identify users, see About Novell eDirectory.

To configure Novell eDirectory settings:
1
Launch the SonicWall Directory Services Connector Configuration Tool.
2
Expand the SonicWall Directory Connector and SonicWall SSO Agent trees in the left column by clicking the + button.
3
Right click Novell eDirectory Servers and select Add.

4
In the IP Address field, type in the IP address of the Novell eDirectory server.

In the Port(1-65535) field, type in the port for the service. The default port is:

636 if the Security Connection checkbox is selected.
389 if the Security Connection checkbox is not selected.
5
In the User DN field, type in the service user’s domain name.
6
In the Password field, type in the password for the service user.
7
In the Base DN field, type in the base domain name.

The User DN and Base DN are case sensitive and should be entered in the following format:

User DN: cn=xxx,o=xxx

For example: cn=admin, o=test

Base DN: o=xxx

For example: o=test

 
8
In the Polling Interval(1-60 Sec) field, type in the number of seconds for the polling interval. The default value is 10 seconds, the minimum is 1 second, and the maximum is 60 seconds.
9
Click the Test Connection button to verify that the SSO Agent can connect with the eDirectory server.
10
Click OK.
11
Click OK in the popup dialog indicating that the configuration is saved.

Configuring Remote SSO Agents

A Single Sign-On deployment can contain up to eight SSO Agents on different servers. Each instance of the SSO Agent can exchange information with the other, remote Agents.

To configure remote SSO Agents in Directory Services Connecter:
1
Launch the SonicWall Directory Services Connector Configuration Tool.
2
Expand the SonicWall Directory Connector and SonicWall SSO Agent trees in the left column by clicking the + button.
3
Right click Remote SSO Agents and select Add.

4
In the Agent IP field, type in the IP address of the remote SSO Agent.
5
In the Sync Port field, accept the default of 2260 or type in the custom sync port.

By default, the SSO Agent uses TCP port 2260 to receive the Agent synchronize data. When an SSO Agent starts up, it sends a TCP Reset notification to all the configured remote Agents. When a remote Agent receives this reset notification, it sends its user cache to the requesting Agent. Thereafter, the remote Agent sends any incremental changes.

6
In the Friendly Name field, type in a descriptive name for the remote SSO Agent.
7
Click OK.
8
Click OK in the popup window indicating that the configuration is saved.
9
Click on Remote SSO Agents to display all the configured remote SSO Agents in the right panel. You can see the friendly name, IP address, port, and status of each remote Agent.

10
To modify the configuration of an existing remote SSO Agent, click on its IP address in the left panel, enter the desired values as in Step 4 through Step 8, and then click OK.

Using the Configuration Tool Menus

The Directory Services Connector Configuration Tool provides several menus at the top of the screen for configuring settings and viewing information.

Topics:

Using the File Menu

This File menu in the Directory Connector Configuration Tool provides the Exit option.

Click File > Exit to close the Directory Connector Configuration Tool.

Using the View Menu

The View menu in the Directory Connector Configuration Tool provides options for displaying or hiding the toolbar and status bar.

Click View > ToolBar to toggle the toolbar display. If it is currently hidden, it will be displayed. If currently displayed, it will be hidden.

Click View > StatusBar to toggle the status bar display. If it is currently hidden, it will be displayed. If currently displayed, it will be hidden.

The toolbar provides icon buttons near the top of the screen for the following:

Adding servers to the SSO Agent configuration
Removing servers from the SSO Agent configuration
Starting the Windows service
Stopping the Windows service
Refreshing the items displayed in the Configuration Tool
Viewing the SSO Agent properties
Accessing the diagnostics tool

Each button is only active when a relevant item is selected in the left panel. Not all buttons are active at the same time.

The status bar displays the current SSO Agent status along the bottom of the screen. The installed version of the SSO Agent is also displayed there.

Using the Action Menu

The Action menu in the Directory Connector Configuration Tool provides options for viewing the properties, log entries, viewing users and hosts, using the diagnostic tool, and managing services and users. The option to set the Service Logon User is available in the Action drop-down menu. It also provides options for starting and stopping the SSO Agent Windows service.

All of the Action menu options are also available on the right-click menu for the SonicWall SSO Agent from within the Configuration Tool.

Topics:

Viewing the Logs

The Action > View Logs page of the Directory Services Connector Configuration Tool causes Windows Explorer to open the program data folder that contains the SSO Agent log files.

The Agent keeps up to five logs at a time and stores them in C:\ProgramData\SonicWall\SSOAgent:

SSOAgent.log - This is the main log file.
SSOPacket.log - This is the packets log between the firewall and Agent.
Rpc.log - This is the RPC log between the Config Tool and Agent service.
SecurityEvent.log - This is the DC/Exchange security event log.
SessionTable.log - This shows the results returned by the NetSessionEnum API.

More logs are created with higher logging levels. Debug is the highest level.

In the case of troubleshooting, all files in this folder should be sent for investigation by the Support team.

* 
NOTE: When the SSO Agent service crashes, the crash dumps are located at C:\ProgramData\SonicWall.

Displaying Users and Hosts Statistics

The Action > Users and Hosts page of the Directory Services Connector Configuration Tool displays the number of event log messages parsed and the replies sent to the appliance. It also displays the number of users in the SSO Agent cache, and the total number of users who logged on and logged off. The User Information table displays the IP address, user name, user login time, time of last refresh, and the method used to identify the user.

You can search and sort the users as well as manually removing a user from the cache.

To display the Users and Hosts page, click Action and select Users and Hosts.

Using the Diagnostic Tool

The Action > Diagnostics Tool page of the Directory Services Connector Configuration Tool provides a way to find logged in user information for remote workstations. You can manually identify IP addresses using the WMI or NetAPI method by entering multiple IP addresses separated by commas or an IP address range. The results can be exported to a CSV file.

Viewing Windows Service Users

The Action > Windows Service Users page displays all the service users you configure. The users might be used by services on the end-user’s computer. The SSO Agent ignores all events whose usernames are in this list.

Adding a User

You can add a user to the service users list by clicking Add in the Add Local User section and adding the name in the Excluded user name pattern field. Local users can include a domain name.

* 
TIP: You can also add Windows service users from SonicOS (see the SonicOS Administration Guide for details).

Viewing and Configuring Service Logon User

The Action > Service Logon User page displays the current service logon user and allows you to configure it. The WMI, NetAPI, and DC Security Log methods require domain administrator privileges. The service should be run with a domain administrator account. You can set up an account name and password on this page.

Starting and Stopping the Windows Service

The Action > Start Service and Action > Stop Service pages provide a way to start and stop the Windows service for the SSO Agent.

Using the Load Test file

The Load Test feature allows you to preload a static set of IP-to-username mappings and static user configuration in a user-defined test file.

The tester can create a file named static.csv in the program installation directory, which by default is C:\Program Files\SonicWall\SSOAgent. An example static.csv is shown below:

10.0.0.0,user0

10.0.0.1,user1

10.0.0.2,domain\user2

If this file exists, the SSO Agent loads it at service start time and checks and reloads this file every 5 seconds.

You can view the test users and IP addresses in the Action > Users and Hosts screen of the Directory Services Connector Configuration Tool, in the User Information list.

Using the Help Menu

The Help menu in the Directory Connector Configuration Tool has two options:

Send Feedback

Select Send Feedback to display a popup window in which you can enter feedback about Directory Services Connector and the SSO Agent and send it to the Support team. Fill in the Subject, Email ID (your email address), Name (your name), and Comment fields, and then click Submit.

About

Select About to display a popup dialog with the installed version number of Directory Services Connector and the SSO Agent.