As soon as the AppGate client is started, it looks for a configuration file, and, if one exists, reads it. The Java Web Start client will also download configuration from the server, which allows the administrator to configure the first screens as well. The client will then display the Open connection dialog.

To open a connection to an AppGate server:

It is also possible to open the Connection properties dialog by pressing the 'Properties...' button. There is normally no need to do this.

When the AppGate client connects to an AppGate server for the first time, and the installation software has not installed a server host key, a dialog box may be shown.

This box asks the user to acknowledge that he is connecting to a new server. Pressing the details button will show the key fingerprint for the server. The key fingerprint will be the same for any user who connects to the same server. Therefore, the user may check the fingerprint against another installation to verify its validity before accepting it. This provides additional protection against man-in-the-middle attacks. The user must click OK in order to accept the host key and continue with the connection.

It is possible to view the host key for a server which the client is connected to. This is done by right-clicking on the server name and selecting 'Properties...' in the menu.

If the received server key does not match the stored key, the connection will fail. This is usually due to one of two events: the server software has been reinstalled and a new server key has been created, or someone is pretending to be the AppGate server (i.e. someone tries to act as a man in the middle that relays and controls the traffic to the server). Under both circumstances, please contact a system administrator to make sure nothing suspicious is going on! If there are absolutely no doubts that the server key has changed, the locally stored key can be deleted. The host keys can be found in the following directories:

The first step when connecting is to authenticate the server. Depending on the configuration, the client may present the server host key to the user for verification at the first connection (see Section 3.3.3, “First time connection”).

The server authentication process is followed by user authentication. Depending on the selected authentication method, additional dialog boxes asking for authentication information may be displayed.

When a user logs on to an AppGate server, the server checks the status of the account. If the user is already logged in, a message saying "You are already logged in" may be displayed (see Section 4.9.3, “Connection Settings” for details on how to enable/disable this message).

When the user has been successfully authenticated, information about accessible Roles, Services and server configuration parameters is downloaded.

Access to each service and role on the protected network is given, based on the evaluation of Access Rules. In other words, the services a user is granted access to during a specific session depends on the access rules that have been configured for each protected service/role and which of these rules are matched by the user at that time. The services/roles accessible to the user may therefore vary from session to session.

Roaming is a feature which allows clients to suspend the connection to the AppGate server and later to resume it again. The user does not need to re-authenticate when reconnecting. Indeed, the entire process can be completely automated and nearly invisible to the user. All established connections will remain alive while roaming. This feature is intended for mobile users who move around much in the network.

The user may change network location while roaming. The only requirement is that the user can reconnect to the AppGate server using the same name when resuming. For instance, a salesman may begin the day by logging on from his home network over a DSL connection. Then he suspends the connection and goes to the day's first customer, where he reconnects using a public wireless hot-spot. Later in the day, he may reconnect using a 3G card in his laptop. Another example is a user using the mobile client on his smartphone. Since coverage may be spotty, the phone loses network connectivity often, but roaming hides this from the user. In both cases, it is a great convenience for the users to not have to re-authenticate each time they want to resume the session.

Technically, roaming is accomplished by closing the TCP tunnel when the connection is suspended. When resuming, a new TCP connection is made to the server and the SSH data stream is redirected to this new connection. The user does not need to authenticate again, instead the client authenticates to the server, without user interaction, with the help of a random password which was made up when the user authenticated at the start of the session. In addition to knowing this password, the client must also know the encryption keys and encryption state to be able to reconnect. It is therefore impossible for a third party to break in and take over a suspended session.

To be able to use roaming, the user must have access to the roaming capability. That is, one service which the user has access to must include the roaming capability. It is also up to the administrator to set how long time a roaming user may be roaming.

Roaming can be more or less automatic. The exact level of automation is controlled by the client. The client will automatically enter the suspended state if the connection to the server is lost, assuming roaming is available. Also, the Windows client will do a suspend/resume cycle whenever the machines network configuration changes. The client may also be configured to automatically suspend the connection if no data has been sent for 60 seconds. Resuming can be manual or happen automatically when new data is sent by the client. Note that it is only the client which may resume a session. Automatic suspend/resume can be configured in the Connection properties dialog.

The maximum roaming time can be configured from AppGate Console, see Section 4.9.3, “Connection Settings”.

After the client connects to the AppGate server and the user is authenticated, the user is asked to select one or more roles for the session. Roles are different "modes" that users are associated with, containing different sets of services. Users can select roles according to the business task they wish to accomplish. Some roles may be exclusive while others can be combined with other roles.

The default behavior is to combine all the combinable roles into one pseudo-role named "Combinable" in the role selection dialog. That is there may be a role named "Combinable" which if selected by the user activates all the combinable roles the user has access to. This behavior can be disabled by setting merge_combinable_roles to false in the client configuration.

If the role selection dialog would contain only one role (which could be the "Combinable" merged role) then role selection will happen automatically and the role selection dialog does not appear.

This figure shows the role selection dialog when the user must select one of three different non-combinable roles.

A complicated role selection dialog where the user has access to one exclusive role (named Administration) and where merging of combinable roles has been turned off could look something like this:

Based on the information downloaded from the server, AppGate Client displays a view of the services which are available to the user. Accessing a service is accomplished by double-clicking the corresponding icon. Once started the icon will change to include either a green check mark which indicates success or a yellow exclamation mark which indicates that an error occurred.

There are two possible modes, "Icons" and "Tree structure", for the service view. To select a mode, use the Preferences dialog. Double-clicking on a folder in "icon" mode will open that folder. To move back, press the 'Up' icon in the upper left corner of the service tab.

To close a connection to an AppGate server, select the server in the Close connection sub-menu (Connection - Close connection...), and click OK. Before the connection is closed, the AppGate client checks to see whether the connection is active.

The AppGate clients present a number of local configuration options to the user. These options give experienced users an opportunity to adjust the AppGate client to meet their personal preferences. Note, however, that all of these options can be pre-configured or configured from the server so that no additional work is required by the user. This section describes the advanced features of the AppGate clients.

Connection properties

To adapt connections between the AppGate client and AppGate servers to specific conditions, certain connection properties can be set. This is done in the Properties dialog.

The available configuration options are:

• Server name: The name, or IP address, of the server.

• Server port: Which port on the AppGate server to connect to. By default, port number 22 is used.

• Compression: If the connection is slow (throughput less than 1 M/bit), enabling compression may speed up the data transfer rate.

• Forward X11: This should be selected if GUI applications are to be run on Unix systems on the protected network. Selecting Forward X11 makes the application pop up graphical windows on the client host. For this to work, an X-server must be running on the same system as the AppGate client.

• Keep alive: The client can periodically send keep-alive packets to the AppGate server to ensure that the connection is not terminated due to lack of activity. This only applies to the connection between the client and the AppGate server, not to any connections to application servers behind the AppGate server.

• Poll for print jobs: If the user has access to AppGate local printing, this check box must be enabled in order to receive the print jobs. Enabling this check box causes the client to periodically poll the AppGate server to determine whether there are any print jobs for the connected user.

• Roaming: If this is checked, the client will try to enable roaming when connected to this server (see Section 3.3.5, “Roaming (Suspend/Resume)”)

• Auto resume: (requires roaming) If this is checked, the client will try to auto-resume connections to this server if the IP address of the network interface is changed, or if traffic is detected when the client is in auto-suspend.

• Auto suspend: (requires roaming) If this is checked, the client will auto-suspend after 60 seconds if no traffic is sent.

• Crypto: which encryption algorithm to use.

• Authentication: which authentication method to use in this session. All available authentication methods are listed in this drop-down list box.

• Application access control (on Unix and Mac OS X systems only): check that no other users try to use the secure tunnel. This feature requires that the local system runs the ident daemon. If no ident daemon is present, then all connections will be refused if this option has been enabled.

Proxy configuration dialog

The 'Use proxy...' button opens the proxy configuration dialog where it is possible to configure the client to use an HTTP or SOCKS proxy when connecting to the AppGate server.

The Proxy type (None, Automatic, HTTP, SOCKS4 or SOCKS5), server name, port on server to connect to, user name of the user connecting, and password of user can be configured in this dialog.

NOTE: When using a proxy, the proxy password will be transmitted in clear text over the local network.

Automatic proxy configuration only works if the client is started through Java Web Start or as an applet. For an installed client it is equal to no proxy.

Deleting servers

To delete a server that is no longer used or that has changed its name, click Delete in the Properties dialog of the server that is to be deleted. Click OK to confirm.

Adjusting service properties

After AppGate Client is connected, it can be configured to take appropriate measures so that protected services are easily accessible. For instance, a client application that can be used to connect to a protected service can be started, a terminal window that handles the result of a remote command popped up, or a specific local unit can be allocated for a protected disk. These local configuration values, e.g. the command that starts the client application, or the local unit to be allocated, can be overridden by the user to more closely comply with his personal preferences.

To adjust service properties, right-click on the icon representing the service, and select Properties in the menu that pops up.

All of the services have the following configurable options:

• Change Icon... - Clicking this button will bring up a window for choosing a new icon. AppGate Client can only display GIF and JPEG images as icons, therefore only GIF and JPEG files may be chosen.

• Start automatically - Turning this option on causes the service to start automatically when the user logs in. Turning it off means that the service must be started manually by double-clicking the icon.

• Hide - Turning this option on causes the service to be invisible when the user logs in. Turning it off makes the service visible.

Services that contain client commands and NetBIOS components may be further configured by the client, as explained below. In the Properties box for the service the user must right-click on the name of the component to modify and select Properties.

Services containing client commands

Services that contain client command components are typically used to run applications on client machines. AppGate applications are arbitrary client applications connected to protected server applications through the AppGate system. When started through the AppGate client, these applications are provided access to the protected services. This is achieved through the use of IP accesses.

The command that is executed on the client machine may be changed by the user if necessary.

Changing the command results in a client application other than the default one being started. The associated IP access cannot be changed. Changing the command to start a client application that does not use the local ports of the pre-configured IP accesses is therefore meaningless.

The edited command is saved automatically in the configuration file of the client when the AppGate client is closed and will be used the next time the connection is established.

Services containing share access components

Share access components are protected disk or printer shares mapped to and accessible from the local file system. To provide access to a protected share, a virtual NetBIOS server is created. From the user's point of view, it will look as if the share is located on this virtual server. For instance, the virtual server is specified in Windows Explorer. The name of the virtual server is given in the form of AGnn___service.

NOTE: It is recommended that all protected shares mapped through the AppGate client are also disconnected through the AppGate client. While the client is running, protected shares should not be removed using Windows Explorer, as that may confuse the client.

Disk shares are mapped to one of the local units 'A:' to 'Z:'. The character '*' is used to denote the first free local unit that is found. Printer shares are mapped to 'LPT1:', 'LPT2:', or 'LPT3:'. The local unit to be used is pre-configured on the server, but can be overridden locally by right-clicking on the icon, choosing Properties, manually deleting the old drive letter, and inserting the desired one.

Preferences dialog

Some aspects of AppGate Client can be changed through the Preferences dialog, which are accessed through the main menu by choosing 'Connection - Preferences...'.

The Preferences dialog has three sections, Appearance settings, Advanced settings and RDP Client settings.

• 'Show access details tab' makes AppGate Client show the access details tab. This is explained further below.

• 'Show hidden services' makes AppGate Client show services which are normally hidden. This is explained further below.

• 'Show unavailable services' makes AppGate Client show services that are configured, but unavailable for some reason.

• 'Minimize when connected' makes the client minimize itself to the toolbar after a successful connection has been made.

• 'Minimize immediately' makes the client show only the connection dialog when started, and it will minimize itself to the toolbar after a successful connection has been made.

• The service view can be changed to use a tree view instead of the normal icon view by selecting 'Tree view' under 'View'.

• The look-and-feel of AppGate Client can be changed by selecting one in the 'Look and Feel' selector.

• 'Write to hosts file' turns on/off hosts file writing.

• 'Use device firewall' enables/disables AppGate Client's use of the AppGate Device Firewall.

• 'View share map/unmap dialogs' enables/disables the pop-up dialog when mapping/unmapping Windows shares.

• Clicking on the 'Open debug window' button makes AppGate Client show an additional window with debug information. The debug level can be changed by changing the value in the field for 'Debug level'.

• 'Local devices' check boxes controls whenever local disk drives and printers should be visible to the RDP session.

• 'Remote computer sound' enables/disables playing of sounds coming from the RDP session on the local computer.

• 'Experience' allows the user to balance the user experience of the RDP session with bandwidth needs. The more the RDP sessions looks and feels like a login on a local computer, the more bandwidth is needed.

Access details

IP access components allow traffic between an application on the local host and the corresponding server application on a remote server. The AppGate client uses IP access components to provide users with access to services on protected networks. This section explains the basics of IP access components and how they are used by applications to access protected services.

By default, the Access details tab is hidden, but it can be made visible by selecting 'View access details' under the 'Appearance' tab in the Preferences dialog.

Unless IP tunneling is used, the AppGate client handles IP access components according to the SSH protocol specification. This is done by forwarding all data that is sent to pre-configured ports on the local machine to the AppGate server. The AppGate server then forwards the data to the correct protected server. To handle this task, an SSH IP access component is denoted by:

• A port number on the local machine, i.e., the port number used by the application that is run, such as port 80 for a web browser.

• The name of the destination host, which is the protected server situated behind the AppGate server, where the server application is located.

• The destination port number, which is the port number on the destination host that the server application uses to handle connections.

The Access details tab shows all of the available IP access components. The Access details tab is common to all simultaneous AppGate connections.

NOTE: FTP services, which are a special type of IP accesses used to transfer files, differ from ordinary IP accesses in that no destination host or destination port are specified. The lack of these two parameters is due to the fact that all FTP requests are handled by the FTP proxy on the AppGate server.

IP access components, Reverse IP access components, ICMP, FTP proxy or web access components can be activated and deactivated from the access details tab. Also, when the user starts an application from a service tab, its associated access components will automatically be enabled and marked as active in the access details tab.

Using local ports in the way that the SSH protocol specifies restricts the number of simultaneous tunnels from each local port to a single one. This means that it is not possible to connect to multiple server applications that require the same local port to be used. For instance, the user cannot browse two different web servers at the same time, since that requires two different IP accesses, both from local port 80, to be established (unless the AppGate server web proxy is used).

Changing local port numbers

Changing the local port number is only applicable if the Port Forward method is used. If IP tunneling is used, there is no local TCP listener and thus no local port number that can be changed.

Services that contain client command components typically start an application on the client machine. In this case, a local port number is specified for the application to communicate with. Sometimes it may be necessary to change the local port number to avoid conflicts. However, it must be done in accordance with the application configuration. Changing the port numbers without knowledge of the consequences should be avoided - most likely, a random change means that the associated application will not be able to run.

Local port numbers can only be edited while the corresponding IP accesses are inactive. All edited port numbers are displayed in blue text, and saved for future sessions. To reset a default local port number, right-click the local field, and select Default in the pop-up menu.

IP access status

To verify the state of an IP access, right-click on the Local port field and select State in the pop-up menu. AppGate Client checks the status of the port and then pops up a dialog displaying the result. The state of an IP access is described by the two parameters, ssh state and application state.

The SSH state parameter describes whether or not the IP access has been established through AppGate Client using the SSH protocol, and whether or not the client accepts new connections to the configured local port. The states are:

• Not listening: AppGate Client does not manage this IP access.

• No further connections accepted: the IP access is established through AppGate Client, but AppGate Client does not accept any new connections to the local port that is used.

• Listening: new connections accepted: the IP access is established, and managed by AppGate Client, and the IP access can be used to connect to the configured remote host.

If the SSH state of an IP access is Listening, the current connections to the port are listed as part of the state report.

There are two ways that an application can be configured to use a specific IP access. These configuration alternatives are stated with the Application state parameters as:

• Configured by AppGate Client: client applications are automatically configured by AppGate Client to use the IP access to connect to the desired server. This is done by configuring the hosts file on the client machine.

• Not configured: either the forwarding is inactive, or the applications must be configured by the user to be able to connect to the configured server.

The local print capability enables users to securely print documents, which have been generated by servers protected by the AppGate server, on their local printers. This section only describes it from the perspective of AppGate Client. To enable local print in AppGate Client, the 'Poll for print jobs' check box must be selected (see the section called “Connection properties”). When this box is selected, the client will poll the specified AppGate server for any print jobs currently available for the client.

The 'Poll for print jobs' option is a per-server option and it must be chosen for each server where print jobs may be present.

If a print job is available for the connected client on the server, the job(s) will be shown in the 'Print jobs' tab of the client window while the client is connected to the AppGate server.

To print a job, simply select it by clicking on it and the printer the job should be sent to. All Windows clients will supply a list of the currently defined printers. All other operating systems require the user to specify the printer name and the print command to be used.

Select the appropriate printer and click 'Print'. If the client should always print the jobs submitted to it without waiting for user interaction, check the 'Auto print' check box in the client. This is a global setting, and will apply to all servers to which a client who polls for print jobs connects.

To remove a print job from the queue without printing it, select the print job by clicking on it and click the 'Remove' button. To stop a print job in progress, select the print job and click on the 'Stop' button.

The TCP forwarding proxy is a way to establish dynamic port forwarding. The TCP proxy allows users to connect to many different hosts using the same port number. The configuration and usage of the TCP forwarding proxy is slightly different from the other definable port forwardings in the AppGate system. This section provides a brief explanation of how the TCP forwarding proxy may be used.

 host:port 

The AppGate server can use X.509 certificates instead of ordinary host keys. The advantage of this is that the host certificate can be verified without first having the actual host key. A host certificate can also be revoked by the use of Certificate revocation lists. To use certificates instead of host keys, a valid root CA certificate has to be copied to the client, and the configuration parameters host_cert_ca_files and host_cert_crl_dist_points have to be added to the client's agclient.properties file. If an HTTP proxy must be used to retrieve the CRLs, the parameters host_cert_crl_proxy_host and host_cert_crl_proxy_host also have to be added. The use of host certificates can be enforced by setting the hostkey_handling parameter to "refuse" and removing any stored hostkeys from the clients. Since no new host keys will be accepted, only hosts identified by a valid certificate which can be verified will be accepted.

If the Entrust authentication method will be used, an Entrust client must be installed independently of the AppGate client. The Entrust client is third party software and is not included in the AppGate package. The Entrust client may be installed either before or after the AppGate client is installed.

In order to get Entrust working with the AppGate client, the Entrust IPSec Negotiator Toolkit engine must be installed (the file kmpapi32.dll must be present). Also, the entrust.ini file must be modified so that FIPS mode is disabled - this is done by making sure that the following line is present in the file entrust.ini:

 FipsMode=0 

If the Certificate authentication method is to be used, X.509 certificates must be installed independently of the AppGate client software. AppGate supports the use of generic X.509 certificates stored in one of the following places:

The AppGate clients automatically search the Microsoft Certificate Store (on Windows) and any Netscape/Mozilla profile for certificates. All found certificates will be included in the drop-down list in the connection dialog. Certificates not found automatically must be configured manually.

Manual configuration of certificates is done in the Connection properties dialog. The needed entries will appear when the authentication method is set to 'Certificate'. The client will remember the choices made here, so users should only need to do this once (if at all).

To use a certificate stored in a PKCS#12 file, check 'Certificate file' and specify the name of the file in the entry field. The '...' button opens a file browser.

If 'System certificate' is selected, the field to the right of the radio button must be filled with the name of the certificate. To do this, click the '...' button to the right, and the 'Certificates' window will open. In the 'Certificates' window, one or more sources may be selected. When one of these is selected, a list of available certificates is displayed in the tree below. Only one certificate may be selected for authentication. When 'Windows Native' is selected, the default location used by Microsoft is 'MY'. This location may be changed by selecting the 'Load' button to the right of 'Windows Native'. When 'Netscape Directory' is selected, and a proper directory configured, a list of available Netscape profiles is provided to choose from.

SmartTrust and Generic PKCS11 libraries require special configuration. Please contact AppGate support for instructions.

To be able to map network shares from the AppGate client, there are a couple of Windows settings on the client computer that must be correct. When the client starts, it runs some diagnostic tests in the background to check for some common problems with the configuration. If any of the diagnostic tests fail, and the user selects a role which contains share access components, a warning will be given to the user. The client will also set the attribute ag_client_share_capable to either 'ok' or a string that indicates the problem. Below is a list of the problems that the tests will detect and solutions to these problems.

Note that share access does not work on Windows Vista.

'Enable NetBIOS over TCP' must be checked and 'Enable LMHOSTS lookup' must be checked.

These two settings must be checked in windows. You will find them under Start -> Control panel -> Network Connections -> Local Area Connection -> Properties -> Internet Protocol (TCP/IP) -> Properties -> Advanced -> WINS:

You must also check the "Client for Microsoft Networks", see the next item below.

The Client for Microsoft Networks service is not running

You must have the Client for Microsoft Networks available and checked in the Windows network settings. You should find it in the list of items under Start -> Control panel -> Network Connections -> Local Area Connection -> Properties.

If it's not in the list, you can click the "Install...", select "Client" and click "Add..".