C H A P T E R  6

SGD Client and Webtop

This chapter describes how to install, configure, and run the Sun Secure Global Desktop (SGD) Client. Webtop configuration is also covered.

This chapter includes the following topics:


Supported Client Platforms

The following table lists the supported client platforms for the SGD Client. Also included are the supported browsers, and the supported desktop menu systems when the SGD Client is operating in Integrated mode.


Supported Client Platform Supported Browsers Integrated Mode Support
Microsoft Windows Vista (Intel® x86 32-bit) Internet Explorer 7

Mozilla Firefox 2

Mozilla Firefox 3

Microsoft Windows Start Menu
Microsoft Windows XP Professional (Intel x86 32-bit) Internet Explorer 7

Mozilla Firefox 2

Mozilla Firefox 3

Microsoft Windows Start Menu
OpenSolaris version 2008.11 or later on x86 platforms Mozilla Firefox 2

Mozilla Firefox 3

Sun Javatrademark Desktop System (Java Desktop System) Launch Menu
Solaris 10 OS on SPARC® platforms Mozilla Firefox 2

Mozilla Firefox 3

Java Desktop System Launch Menu
Solaris 10 OS on x86 platforms Mozilla Firefox 2

Mozilla Firefox 3

Java Desktop System Launch Menu
Solaris 10 OS Trusted Extensions on x86 platforms Mozilla Firefox 2

Mozilla Firefox 3

Not supported
Mac OS X 10.5 latest version Safari 2

Mozilla Firefox 2

Mozilla Firefox 3

Not supported
Red Hat Desktop latest version (Intel x86 32-bit) Mozilla Firefox 2

Mozilla Firefox 3

Gnome or KDE Start Menu
Ubuntu latest version (Intel x86 32-bit) Mozilla Firefox 2

Mozilla Firefox 3

Gnome Start Menu

For OpenSolaristrademark operating system client platforms, the libXm.so.4 library must be present in the /usr/lib directory on the client. A copy of this library is included in the /opt/tarantella/lib directory on the SGD host.

Beta versions or preview releases of browsers are not supported.

Browsers must have the JavaScripttrademark programming language enabled.

To support the following functionality, browsers must have Javatrademark technology enabled:

If Java technology is not available, the SGD Client can be downloaded and installed manually.

The following are the supported plug-ins for Java technology:



Note - Java Plugin tool version 1.6.0 is the only supported plug-in for Microsoft Windows Vista platforms.



When users start more than one user session using the same client device and browser, the user sessions join rather than the new session ending the existing session. For user sessions to join in this way, the browser must be configured to allow permanent cookies. If permanent cookies are not allowed, user sessions always end and this might cause application windows to disappear.

For best results, client devices must be configured for at least 256 colors.


The SGD Client

The SGD Client is the part of SGD that is installed on client devices. The SGD Client is required to run applications.

This section includes details of how you can install and run the SGD Client.

This section includes the following topics:

Overview of the SGD Client

The SGD Client can operate in either of the following ways:

Depending on the client platform, users see an icon in the System tray or Workspace switcher when the SGD Client is running.

The SGD Client performs the following functions:

Configuring the SGD Client

The SGD Client needs to be configured so that it can connect to an SGD server. The connection settings for the SGD Client are defined in a client profile. The client profile is stored on the client device.

The client profile controls things such as the Uniform Resource Locator (URL) that the SGD Client connects to when it starts, and the operating mode of the SGD Client.

See Client Profiles for more information about how SGD uses client profiles and the settings you can configure for a client profile.

The SGD Client Helper

When using a browser with Java technology enabled, the SGD Client is supported by the SGD Client Helper.

The SGD Client Helper is a Java applet that performs the following functions:

  • Downloads and installs the SGD Client. This only applies if automatic installation is used. See also Automatic Installation of the SGD Client.

  • Obtains proxy server settings from the browser and sends them to the SGD Client. This depends on the settings in the user’s client profile.

  • Starts the SGD Client. This only happens when a user starts a browser and goes to the login URL.

  • Responds to instructions received from the SGD Client. For example, prompting the browser to redraw the screen.

Use of the SGD Client Helper is optional. See How to Access SGD Without Using Java Technology.

Installing the SGD Client

The SGD Client can be installed in the following ways:

Automatic Installation of the SGD Client

If you are using a browser with Java technology enabled, the SGD Client is installed automatically when you visit the http://server.example.com/sgd URL, where server.example.com is the name of an SGD server.



Note - If you use Internet Explorer on Microsoft Windows Vista platforms, you must add the SGD server to the list of Trusted Sites in Internet Explorer’s Security Settings before the SGD Client can be automatically downloaded and installed.



With automatic installation of the SGD Client, different versions of the SGD Client are installed in separate directories. This means the following:

The SGD Client is installed in the following directories:

If you want to use automatic installation and have more control over where the SGD Client is installed, you can develop your own web application for installing the SGD Client and use SGD web services to specify the installation location.

See the Sun Secure Global Desktop 4.5 Installation Guide for more details about automatic installation of the SGD Client.

procedure icon  How to Enable Automatic Installation for Roaming User Profiles

To enable the SGD Client to be installed automatically in a directory that is roamed, perform the following procedure on each SGD server in the array.

Ensure that no users are logged in to the SGD server, and that there are no application sessions, including suspended application sessions, running on the SGD server.

  1. Log in as superuser (root) on the SGD host.

  2. Edit the webtopsession.jsp file.

    The file is located on the SGD host at:

    /opt/tarantella/webserver/tomcat/6.0.18_axis1.4/webapps/sgd/resources/jsp/webtopsession.jsp

    Change the tccRoaming line in webtopsession.jsp, as follows:

    String tccRoaming = "true";

  3. Restart the SGD web server.

    Use the following command:


    # tarantella restart webserver
    

Manual Installation of the SGD Client

With manual installation, you have full control over where the SGD Client is installed.

You download and install the SGD Client from the SGD web server Welcome Page. The SGD web server Welcome Page is at http://server.example.com, where server.example.com is the name of an SGD server.

Click the Install the Sun Secure Global Desktop Client link on the Welcome Page. The Sun Secure Global Desktop Client download page has instructions for downloading and installing the SGD Client.

On Microsoft Windows client devices, the default installation directory is: C:\Program Files\Sun\Secure Global Desktop Client. A shortcut for the SGD Client is also added to the Windows Start Menu.



Note - Manual installation is not available for all supported client platforms.



See the Sun Secure Global Desktop 4.5 Installation Guide for more details about manual installation of the SGD Client.

Running the SGD Client From the Command Line

Typically, users log in to SGD by starting a browser and visiting the http://server.example.com/sgd URL, where server.example.com is the name of an SGD server.

Connecting to SGD in this way, automatically downloads and starts the SGD Client. However, you can also start the SGD Client from the command line and connect to an SGD server. From the command line, you can run the SGD Client either using a browser or in Integrated mode.

You start the SGD Client with the tcc command on Microsoft Windows client platforms, or the ttatcc command on UNIX, Linux, or Mac OS X client platforms, as follows:

tcc
  [ -profile name ]
  [ -loginurl url ]
  [ -preferredlanguage lang ]
  [ -logdir file ]
  [ -use-java ]
  [ -version ]

The following table lists the supported arguments for the tcc and ttatcc commands.


Argument Description
-profile name The name of the profile to use when starting the SGD Client.

Currently there is only one profile for each SGD server, called Default.

To specify the profile for a particular server, use -profile server.example.com::Default where server.example.com is the name of an SGD server.

Note - Profile names are case sensitive.

-loginurl URL The login URL. This overrides the URL defined in the profile.

Use a fully qualified domain name.

-preferredlanguage lang The language to use in any dialogs and messages displayed by the SGD Client. This overrides the language defined in the profile. The following are the supported languages:
  • en for English

  • de for German

  • fr for French

  • ja for Japanese

  • ko for Korean

  • zh_CN for Simplified Chinese

  • zh_TW for Traditional Chinese

-logdir file The directory where the SGD Client log file is created.
-use-java Enable the detection of Java technology in the SGD Client.
-version Displays the version number of the SGD Client.
-help Displays help information. This option is only available on UNIX, Linux, or Mac OS X client platforms.



Note - The arguments are case-sensitive.



The command line does not allow you to supply a user name and password. However, the SGD Client can be configured to log a user in automatically. This is called Integrated mode. See Setting Up the SGD Client for Integrated Mode for more details.

Command-Line Examples

The command line for the SGD Client can be used to create your own shortcuts and shell scripts.



Note - If either the Connect on System Login or the Add Applications to Start Menu options are enabled in a user’s profile, the SGD Client automatically adds shortcuts for itself in the user’s desktop Start Menu. Supported Client Platforms has details of which desktop systems are supported.



The following are some examples of running the SGD Client from the command line.

Starting the SGD Client Without Any Arguments

The following example starts the SGD Client and uses the settings defined in the Default profile, available from the user’s profile cache.


$ ttatcc

If there is no profile, or the profile does not contain a login URL, the SGD Client starts but it cannot connect to an SGD server.

If the user has previously connected to more than one SGD server, the SGD Client connects to the last SGD server the user connected to, using the profile for that server.

Use this command to start the SGD Client if the user always connects to the same SGD server.

Connecting to a Particular SGD Server

The following example starts the SGD Client and uses the settings defined in the profile for server.example.com, available from the user’s profile cache.


$ ttatcc -profile server.example.com::Default

If there is no profile available in the cache for server.example.com, the SGD Client prompts for connection settings.

Use this command to start the SGD Client if the user might connect to different SGD servers.

Overriding the Login URL

The following example starts the SGD Client and uses the settings defined in the Default profile, available from the user’s profile cache, but connects to the specified URL.


$ tcc -loginurl url

Depending on the URL, this can be used to start an application.

Use this command to start the SGD Client and connect to a single SGD server, but connect to different web applications on that server.

Web Services Developer Options

The SGD Client also supports the following command-line arguments. These arguments are useful only when developing applications with SGD web services.


Argument Description
-port tcp The port on which the SGD Client connects to the SGD server. Usually, this is Transmission Control Protocol (TCP) port 5307 when the user has a secure connection to SGD.
-baseroute The base network route the SGD Client uses to traverse a SOCKS proxy server.
-firewalltraversal Indicates that the SGD server is using firewall traversal. Connections to the SGD server and the webtop both use the same port, usually TCP port 443.
-connectioncookie cookie Supplies the cookie used by the SGD server to identify the user session which the SGD Client is being used for.
-portfile file The name of a file where the SGD Client writes its listening port number.
-psn For use with Mac OS X client devices only. Ensures an X server is running.
-server server The fully-qualified Domain Name System (DNS) name of the SGD server.
-no-browser Do not start a browser when starting the SGD Client.



Note - The arguments are case-sensitive.



Accessing SGD Without Using Java Technology

By default, SGD uses the SGD Client Helper, a Java technology applet, to perform the following functions:

If your organization prefers not to use Java technology, additional configuration is required. You must download the SGD Client manually, install it, and then configure the SGD Client to connect to an SGD server. This is described in the following procedure.

procedure icon  How to Access SGD Without Using Java Technology

  1. Manually download and install the SGD Client.

    You download the SGD Client from the SGD web server Welcome Page, for example at http://server.example.com, where server.example.com is the name of an SGD server.

    Click the link to Install the Sun Secure Global Desktop Client.

    The download page and the Sun Secure Global Desktop 4.5 Installation Guide have details of how to install the SGD Client.

  2. Start the SGD Client and connect to SGD.

    1. Start the SGD Client from the shortcut in the desktop Start menu.

      The first time you start the SGD Client, it prompts you for the URL to connect to. This is normally http://server.example.com/sgd, where server.example.com is the name of an SGD server. The SGD Client also prompts you for the proxy server settings to use.

      When the SGD Client connects, it starts your default browser and displays the SGD login page.

      Alternatively, you can start the SGD Client from the command line. See Running the SGD Client From the Command Line for more details.

    2. Log in to SGD.

      The SGD webtop is displayed.

  3. Edit the profile for your client device.

    On the webtop, click the Edit button in the Applications area of the webtop. Go to the Client Settings tab and edit the client profile.

    See also Client Profile Settings.

    1. Configure the operating mode of the SGD Client.

      You can access SGD either by using a browser or by using Integrated mode.

      Integrated mode gives users the best user experience when Java technology is unavailable. Select the Add Applications to Start Menu check box. See also Integrated Mode.

      To use automatic logins to minimize the use of a browser, select the Automatic Client Login check box. See Authentication Token Authentication.

      Whenever the SGD Client needs to display a page in a browser, for example to display a webtop or a login page, it always starts the default browser.

      To update the webtop display, users might have to manually reload the page.

    2. Configure the proxy server settings.

      You must specify the proxy server settings in the profile, because these settings cannot be obtained from the browser. See Configuring Client Proxy Settings.

    3. Click Save.



    Note - SGD Administrators can preconfigure many of these settings for users, by editing the profile for an organization or organizational unit.



  4. Log out of SGD.


Client Profiles

This section includes details on how to manage and configure client profiles for the SGD Client.

This section includes the following topics:

Client Profiles and the SGD Client

A client profile is a group of configuration settings that control the SGD Client. The settings in a client profile include the following:



Note - The SGD Client can only connect to an SGD server if they both have the same major and patch version number. For example, version 4.40.917.



There is one client profile, a single group of settings, for each SGD server that the user connects to. The profile is downloaded when the user connects to an SGD server. If the SGD Client has been installed manually, the user is prompted for initial connection information the first time the SGD Client is started.



Note - Client profiles are not the same as user profiles. User profiles control webtop content and other SGD-specific settings, such as printing.



This section includes the following topics:

Managing Client Profiles

SGD Administrators manage client profiles with the SGD administration tool, Profile Editor. The Profile Editor tool is only available to SGD Administrators.

SGD Administrators can create, edit, and delete client profiles for the following objects:

Each of these objects can only have one client profile. The client profile is stored on the SGD server.

The default system client profile is the profile for the System Objects organization. This client profile can be edited, but it cannot be deleted.

Users can edit their own client profiles from the webtop. Click the Edit button in the Applications area of the webtop and then go to the Client Settings tab.

Users can only edit the client profile for the SGD server they are currently connected to. The client profile for a user is stored on the client device, not the SGD server.



Note - Anonymous users cannot edit client profiles. This is because these users are temporary. See Anonymous User Authentication for more details.



procedure icon  How to Configure Client Profile Editing for Users

  1. Enable profile editing for SGD.

    Profile editing for SGD is enabled by default.

    1. In the Administration Console, go to the Global Settings -> Client Device tab.

    2. In the Profile Editing section, ensure the Editing check box is selected.

      The check box is selected by default.



    Note - If profile editing is disabled, it is disabled for all users, including SGD Administrators. However, SGD Administrators can still create and edit client profiles using the Profile Editor application.



  2. Configure profile editing in the organizational hierarchy.

    Profile editing can be configured for organizations, organizational units, or user profiles.

    Profile editing can be inherited from a parent object in the organizational hierarchy, so that SGD Administrators can enable or disable profile editing for many users without having to edit each user profile. By default, profile editing is enabled for all users.

    1. In the Administration Console, go to the User Profiles tab and select an object in the organizational hierarchy.

    2. Go to the Client Device tab.

    3. Enable Client Profile Editing as follows:

      • Select the Override Parent’s Setting, or the Override Global Setting check box.

        Selecting this check box allows you to override the profile editing setting from any parent object. For example, profile editing can be disabled for an OU, but enabled for a user profile in that OU.

      • Select the Enabled check box.

        Selecting the check box enables profile editing for the user profile, or for all users in the organization unit or organization.

        The initial state of this check box is the setting of the parent object.

    4. Click Save.

Client Profile Settings

The following table lists the settings available in a client profile, with a description of what the setting does.


Setting Description
Login URL The SGD URL to use for the profile. This is usually http://server.example.com/sgd, where server.example.com is the name of an SGD server.

If the user runs SGD by displaying the webtop in a browser, the URL is loaded automatically in the user’s default browser, so that they can log in and access their webtop.

In Integrated mode, the URL is only loaded in the user’s default browser if the user needs to log in to SGD.

Always use a fully qualified domain name.

The URL in a client profile can be overridden by a command-line argument. See Running the SGD Client From the Command Line.

The default Login URL is http://server.example.com:80/sgd/index.jsp.

Connect on System Login If enabled, the SGD Client is started automatically with this client profile whenever the user logs in to their client device.

If enabled, the SGD Client creates an application shortcut or symbolic link for itself in the startup folder of the desktop system. The links are created in the following locations:

  • Microsoft Windows. The Windows startup folder for the current user. This is usually C:\Documents and Settings\username\Start Menu\Programs\Startup

  • KDE. $HOME/.kde/autostart

  • Gnome. $HOME/.config/autostart

  • Sun Java Desktop System. $HOME/.config/autostart

This setting is disabled by default.

Add Applications to Start Menu Controls how users interact with SGD.

If enabled, the applications a user can run are displayed in the desktop Start or Launch Menu on the client device. This is called Integrated mode. Users do not have any of the controls that are available on a webtop, for example controls for suspending and resuming applications.

If disabled, the applications a user can run are displayed on a webtop in a browser.

This setting is disabled by default.

Automatic Client Login If enabled, the SGD Client tries to log the user in using an authentication token as soon as it starts.

You can only enable this option if the Add Applications to Start Menu setting is enabled.

This setting is disabled by default.

See Integrated Mode for more details.

Alternative PDF Viewer The application command for an alternative Portable Document Format (PDF) viewer to use with PDF printing.

If the application is not on the user’s PATH, type the full path to the application.

This setting only applies to UNIX, Linux, and Mac OS X platform client devices.

Logging Controls the amount of information that is output to the SGD Client log file.

The output is logged to a text file in the same directory as the SGD Client.

The default is Errors only.

Preferred Language The default language to use when the SGD Client is started from the command line. For example, when the SGD Client is in Integrated mode.

The language selected is used for messages displayed by the SGD Client, the login dialog, and the webtop.

See Setting the Language for the Webtop for details.

The default is en.

Check for Local X Server If enabled, the SGD Client checks whether there is an X server running on the client device.

Enabling this option can improve performance when starting X applications that are configured to display using an X server on the client device. If a local X server is not available, an independent window is used instead.

This setting only applies to Windows client devices.

This setting is disabled by default.

Proxy Settings Settings that control how the SGD Client determines what proxy servers to use.

Use Default Web Browser Settings means use the proxy server settings configured in the user’s default browser.

Manual Proxy Settings enable you to define the proxy server settings in the profile. You can specify an Hypertext Transfer Protocol (HTTP) proxy server.

If the proxy settings are determined from a browser, the settings are stored and used the next time the SGD Client starts.

If Establish Proxy Settings on Session Start is enabled, the SGD Client obtains the proxy settings from the browser every time it starts. The stored proxy settings are not used. If Automatic Client Login is selected, the Establish Proxy Settings on Session Start setting is disabled.

By default, the Use Default Web Browser Settings check box is selected and the Establish Proxy Settings on Session Start check box is not selected.

Connection Failure Settings that control what the SGD Client does if the connection to an SGD server is lost, whether to always reconnect, to never reconnect, or to ask the user.

If the SGD Client reconnects, these settings control how many attempts are made to reconnect and the time in seconds between each attempt.

If the SGD Client is unable to reconnect, the user session ends and any running applications are ended or suspended, depending on the resumability setting of the application.

The default settings are to Always Attempt to Reconnect, and make 6 attempts at 10 second intervals.


About the Profile Cache

Client profiles created by SGD Administrators are stored on the SGD server where they are created. The profiles are then copied to all the SGD servers in the array, so that they are available for editing on any SGD server.

When a user first logs in to SGD, the SGD Client downloads the client profile to a profile cache on the client device. The client profile that is downloaded is the first match of the following:

When a user edits and saves a client profile, they override the client profile defined by an SGD Administrator, or the system default client profile, and create a user-specific client profile that is only saved in the profile cache on the client device.



Note - Users must log out of SGD and log in again for changes to their client profile to take effect.



The profile cache is specific to each user who logs in to SGD from the client device and is stored in the following locations:



Note - If a Windows user has a roaming user profile, see How to Enable Automatic Installation for Roaming User Profiles .



The same profile cache is used by the SGD Client, whether it has been installed manually or automatically.

The profile cache is updated each time the user edits a client profile, or each time the user logs in, if they are using the client profile defined by an Administrator.



caution icon

Caution - If a user has not edited their client profile, any manual changes made to the profile.xml file are lost when the user next logs in.



The profile cache contains one client profile for each SGD server the user connects to.

Users can restore a client profile to the default settings by editing the client profile and clicking the Reset button. This resets the client profile to the settings defined for the system default client profile on the System Objects object.

Microsoft Windows Users With Roaming User Profiles

Users with Microsoft Windows client devices can have roaming user profiles. Roaming user profiles provide the user with the same working environment, no matter which Microsoft Windows computer they use. If Microsoft Windows users have roaming user profiles, the SGD client profile is automatically adjusted to allow for this, as follows:

The following settings from the SGD client profile are stored in the location of the user’s roaming profile:


Setting Profile Entry
Login URL <url>
Add Applications to Start Menu <mode>
Automatic Client Login <autologin><AT>
Connect on System Login <autostart>
Connection Failure <reconnect_mode>

<reconnect_attempts>

<reconnect_interval>


The settings that are stored with the user’s roaming profile are controlled by the properties file /opt/tarantella/var/serverconfig/local/roamingattributes.properties.

Roaming user profiles are not enabled by default. See How to Enable Automatic Installation for Roaming User Profiles for details of how to configure SGD to use roaming profiles.


Integrated Mode

This section describes how you can access SGD from the desktop Start or Launch Menu on the client device. Operating SGD in this way is called Integrated mode.

When users first connect to an SGD server, they usually start a browser and go to the http://server.example.com/sgd URL, where server.example.com is the name of an SGD server. They can then log in to SGD and display a webtop. However, once users have logged in, the SGD Client can be configured to use Integrated mode. When the SGD Client operates in Integrated mode, the links for starting applications are displayed in the desktop Start or Launch Menu, instead of on the webtop. This means that users can run remote applications in the same way as local applications. Depending on how you configure Start Menu integration, there might be no need to use a browser.

Use Integrated mode if your organization prefers not to use Java technology on the client device. See also Accessing SGD Without Using Java Technology.



Note - See Supported Client Platforms for details of the desktop systems that are supported for Integrated mode.



This section includes the following topics:

Working in Integrated Mode

When the SGD Client is in Integrated mode, the user logs in to SGD by clicking the Login link on their desktop Start or Launch Menu.

FIGURE 6-1   Logging In From the Desktop Start Menu

Screen capture showing Integrated mode log
in option on the desktop Start or Launch Menu.


If the user has logged in to more than one SGD server, there is a Login link for each server in the Start or Launch Menu.



Note - To use Integrated mode, you must log in using the Start or Launch Menu. Integrated mode is not available if you start a browser and log in.



Once the user has logged in to SGD, the Start or Launch Menu is updated with the links for the applications they can run through SGD.

FIGURE 6-2   Application Links in the Desktop Start Menu

Screen capture showing Integrated mode application
links in the desktop Start or Launch Menu.


To start an application, the user clicks the application’s link on the Start or Launch Menu. To start another instance of the application, the user clicks the link again.

Working in Integrated mode simplifies session management. Unlike the webtop, there are no controls for suspending and resuming applications. Instead, when the user logs out, the SGD Client automatically suspends or ends all running application sessions. When the user logs in again, the SGD Client automatically resumes all suspended sessions.

In Integrated mode, users cannot start applications with a different user name and password, by pressing and holding down the Shift key when clicking the application’s link. See Users Can Start Applications With Different User Names and Passwords.

Printing is simplified too. Printing is always “on” and print jobs go straight to the printer the user has selected. Unlike the webtop, print jobs cannot be managed individually.

If the user needs to display a webtop, for example to be able to edit their profile, resume a suspended application, or manage printing, they can click the Webtop link on the Start Menu. The user is not prompted to log in, as they already have a user session. The webtop is displayed in their default browser.

If the user has arranged any of their webtop content to display in groups, those groups are also used in the Start or Launch Menu. If the group is configured to hide webtop content, the content does not display in the Start or Launch Menu.

To log out of SGD, the user clicks the Logout link on the Start or Launch Menu.

Setting Up the SGD Client for Integrated Mode

Setting up Integrated mode for the SGD Client involves the following configuration steps:

  1. Enable at least one other authentication mechanism.

    The user must log in and be authenticated by another authentication mechanism so that SGD can store a user identity and user profile when the user generates an authentication token.

    You can use third-party authentication, or any of the other system authentication mechanisms, apart from anonymous user authentication.

    See Secure Global Desktop Authentication.

  2. Configure SGD for authentication token authentication.

    In Integrated mode, if you configure the SGD Client to log in users in automatically to SGD, an authentication token is used to authenticate the user.

    See Authentication Token Authentication.

  3. Enable client profile editing.

    Client profile editing must be enabled, to allow users to generate authentication tokens. You can enable profile editing for all users, or just for users that require authentication tokens.

    See How to Configure Client Profile Editing for Users.

  4. Configure the client profile for Integrated mode.

    Integrated mode must be enabled in the client profile. Other settings in the client profile also affect how Integrated mode works.

    See Configuring the Client Profile for Integrated Mode.

  5. Applications might have to be configured to give users the best experience.

    See Configuring Applications for Integrated Mode.

Authentication Token Authentication

Authentication token authentication enables users to log in to SGD if the SGD Client submits a valid authentication token.

Authentication token authentication can only be used when the SGD Client is operating in Integrated mode and a user has an authentication token.

Authentication token authentication is disabled by default.

This section includes the following topics:

How Authentication Token Authentication Works

When the SGD Client starts, it submits an authentication token to SGD. The user does not enter a user name or password.

If the authentication token is invalid or the SGD Client does not submit a token, the user is not logged in. The SGD login screen is displayed in a browser, so that the user can log in using another system authentication mechanism.

If the SGD Client submits a valid authentication token, the user is logged in.

User Identity and User Profile

The SGD server stores the authentication token against the identity of the user when they generated their authentication token. This means the user identity and user profile used are those of the authentication mechanism that originally authenticated the user. See Chapter 2 for details of the SGD authentication mechanisms.

Authentication Tokens and Security

When a user generates an authentication token and saves their client profile, the SGD server sends the authentication token to the SGD Client. The SGD Client stores the token in the profile cache on the client device. See About the Profile Cache.

To ensure an authentication token cannot be intercepted and used by a third party, use secure HTTP over Secure Sockets Layer (HTTPS) web servers and enable SGD security services.

When a user generates an authentication token, SGD maintains a record of the tokens issued in a token cache. SGD stores the authentication token using the current identity of the user when the token was generated.

When a user logs in with an authentication token, the authentication token enables SGD to “remember” the user’s original identity and user profile. All user sessions and application sessions are managed using the original user identity and user profile.

If the original login becomes invalid, for example because the UNIX system account is disabled or the password has expired, the user can still log in automatically if they have a valid token. However, they cannot run any applications using the invalid credentials.

procedure icon  How to Enable Authentication Token Authentication

  1. In the Administration Console, display the Secure Global Desktop Authentication Configuration Wizard.

    On the Global Settings -> Secure Global Desktop Authentication tab, click the Change Secure Global Desktop Authentication button.

  2. On the Third-Party/System Authentication step, ensure the System Authentication check box is selected.

  3. On the System Authentication - Repositories step, select the Authentication Token check box.

  4. On the Review Selections step, check your authentication configuration and click Finish.

    The Secure Global Desktop Authentication Configuration Wizard closes.

  5. On the Secure Global Desktop Authentication tab, select the Token Generation check box.

  6. Click Save.

Administering Authentication Tokens

SGD Administrators can use the Administration Console or the tarantella tokencache command to administer authentication tokens. The following administration tasks can be done:

  • Viewing the tokens in the token cache

  • Deleting tokens from the token cache

  • Preventing users from generating new tokens

If token generation is enabled, users can generate a new authentication token from the webtop.

procedure icon  How to View Authentication Tokens

You can view the entries in the token cache that belong to a particular user identity or user profile.

  •   Use the Administration Console to view the authentication tokens for a user.

    •   On the Caches -> Tokens tab, use the search to find a user identity if needed.

    •   On the Sessions tab, click a user identity and then click the Token tab.

    •   On the User Profiles tab, select a user profile and then click the Tokens tab.



    Tip - On the command line, you can use the tarantella tokencache list command to show all entries in the token cache.



procedure icon  How to Delete Authentication Tokens

Deleting a token from the token cache makes the token stored on a client device invalid. If the SGD Client presents an invalid token, the user is prompted to log in with a user name and password. The user must then generate another authentication token if they want to log in automatically.

  •   Use the Administration Console to delete authentication tokens.

    •   On the Caches -> Tokens tab, use the search feature to find a user identity, if needed.

      Select the check box next to a token and click Delete.

    •   On the User Sessions tab, click a user identity and then go to the Token tab.

      Click Delete.

    •   On the User Profiles tab, click a user profile and then go to the Tokens tab.

      Select the check box next to a token and click Delete.



    Tip - On the command line, you can use the tarantella tokencache delete command to delete token cache entries. You can run the tarantella tokencache delete command on any SGD server in the array. The change is replicated to the other servers in the array.



procedure icon  How to Disable Token Generation

Use this procedure to prevent SGD from issuing new authentication tokens. If authentication token authentication is still enabled, users with existing authentication tokens can still log in to SGD.

  1. In the Administration Console, go to the Global Settings -> Secure Global Desktop Authentication tab.

    Deselect the Token Generation check box and click Save.

  2. On the command line, use the following command:


    $ tarantella config edit --login-autotoken 0
    

procedure icon  How to Generate a New Authentication Token

If a user needs to generate a new authentication token, they must edit their client profile.

  1. Click the Edit button in the Applications area of the webtop and then go to the Client Settings tab.

  2. Clear the Automatic Client Login box.

  3. Click Save.

  4. Check the Automatic Client Login box.

  5. Click Save.

    See Setting Up the SGD Client for Integrated Mode for more details about using an authentication token to log in to SGD.

Troubleshooting Automatic Logins

To troubleshoot problems with automatic logins, use the following log filters:

server/login/*:autologin%%PID%%.log
server/login/*:autologin%%PID%%.jsl
server/tokencache/*:autologin%%PID%%.log
server/tokencache/*:autologin%%PID%%.jsl

The server/login/* filter enables you to see when authentication tokens are used for authentication and when they fail.

The server/tokencache/* filter enables you to see errors with operations on the token cache. For example, to see why a token is not added to the token cache.

See Using Log Filters to Troubleshoot Problems With an SGD Server for more information on configuring and using SGD log filters.

Configuring the Client Profile for Integrated Mode

The following settings in a client profile are applicable when using Integrated mode.


Setting Description
Add Applications to Start Menu Enables Integrated mode.

Causes the SGD Client to add icons to the user’s desktop Start or Launch Menu.

Automatic Client Login Enables automatic logins to SGD.

If this is disabled, users must log in with a browser. This means they see a webtop and have applications in their desktop Start or Launch Menu.

If this is enabled, an authentication token is generated when the client profile is saved.Only users can select this check box.

Connect on System Login If enabled, the SGD Client connects each time the user logs into the desktop system.

If Automatic Client Login is also enabled, this gives users a single sign-on experience.

Proxy Settings Proxy server settings can be configured in the client profile itself or obtained from the user’s browser.

Configuring the settings in the client profile itself reduces the need for a browser.

See Configuring Client Proxy Settings for more details.


SGD Administrators can configure all these settings apart from the Automatic Client Login.

When configuring Integrated mode, ensure that the login URL in the client profile contains a fully qualified domain name.

All of the available client profile settings for Integrated mode can be configured by both SGD Administrators and users, except for the Automatic Client Login setting.

The Automatic Client Login setting enables automatic logins to SGD, and can only be configured by individual users. This is because when Automatic Client Login is first enabled, SGD generates a unique authentication token for the user when the client profile is saved. The authentication token is stored in the profile cache on the user’s client device. This means that users must be able to edit their client profiles, in order to generate an authentication token.

If a user logs in to different SGD servers, they must log in to each SGD server and edit their client profile.

If a user edits their client profile, they must log out of SGD and log in again for the changes to take effect.

To use automatic logins, users click the SGD Login link in their desktop Start menu. If the Connect on System Login check box in the client profile is selected, the SGD Client logs in automatically when a user logs in to their desktop.

Configuring Applications for Integrated Mode

For applications that are configured with a Window Type of Independent Window, closing the window might end or suspend the application session, depending on the setting of the application’s Window Close Action attribute.

In Integrated mode, there are no controls for suspending and resuming individual application instances. Applications that are configured to be always resumable are automatically suspended when you log out and resumed when you log in. In the Administration Console, application objects that are always resumable have an Application Resumability setting of General in the Launch tab.

While in Integrated mode, you can only resume a suspended session by displaying a webtop and using the session controls for the application.

You might also want to configure the Number of Instances attribute, to limit the number of instances of applications that users can run.


Webtops

The webtop is a JavaServer Pagestrademark (JSPtrademark) technology web application. The standard webtop can be customized, or you can develop your own using the SGD web services.

This section describe how you can make changes to the default SGD webtop and includes the following topics:

Setting the Language for the Webtop

By default, the SGD web server Welcome Page at http://server.example.com, where server.example.com is the name of an SGD server, is displayed in English.

To change the default language of the SGD web server Welcome Page, amend the symbolic link /opt/tarantella/webserver/apache/2.2.10_openssl‑0.9.8i_jk1.2.27/htdocs/index.html, so that it links to another index page in this directory. For example, to make the default Welcome Page display in Japanese, link to the index_ja.html page.

When users log in using a browser at the http://server.example.com/sgd URL, where server.example.com is the name of an SGD server, the default language used for messages displayed by the login dialog and the webtop is controlled by the defaultlanguage parameter setting in the following file: /opt/tarantella/webserver/tomcat/6.0.18_axis1.4/webapps/sgd/WEB-INF/web.xml

To change the default language, edit this file and replace the parameter value en with the language identifier for one of the following supported languages:


Language Identifier
English en
French fr
German de
Japanese ja
Korean ko
Simplified Chinese zh_CN
Traditional Chinese zh_TW

Save changes to the web.xml file and restart the SGD web server.

The default language is also controlled by the Preferred Language in the user’s client profile. Whenever the SGD Client is started from the command line, for example when the SGD Client is in Integrated mode, the language specified in the profile is used for messages displayed by the SGD Client, the login dialog, and the webtop. SGD Administrators can set the default language by editing the profiles in their organizational hierarchy. See also Client Profile Settings.



Note - To be able to display text for a locale, users must also have appropriate fonts installed on their client device.



Overriding the Default Language for the Webtop

Individual users can override the default language for the webtop in the following ways:

  • On the SGD web server Welcome Page, click one of the flags at the top of the page, to select a preferred language. Then click Log in to access a webtop in that language.

    The SGD web server Welcome Page is at http://server.example.com, where server.example.com is the name of an SGD server.

  • Specify a different preferred language in the client profile.

  • Log in to SGD using a URL that specifies the preferred language. The URL is http://server.example.com/sgd/index.jsp?langSelected=lang, where lang is a supported language identifier for SGD and server.example.com is the name of an SGD server. Users can manually type this URL in their browser.

  • Run the SGD Client from the command line and use the -preferredlanguage lang command line argument to set the language, where lang is a supported language identifier for SGD. This argument can used in shortcuts and shell scripts.



Note - When you override the default language, the login URL specified in the user’s client profile does not need to be changed. This is usually http://server.example.com/sgd, where server.example.com is the name of an SGD server.



Relocating the Webtop

The webtop is a JSP software application that you can relocate to your own JSP technology container. The JSP technology container can be on the same host as an SGD server or on a different host.

To use your own JSP technology container, the container must support the following:



Note - Once you relocate the webtop to your JSP technology container, you have to manually upgrade the webtop as shown in this procedure for each new release of SGD.



If you use third-party authentication, you might want to configure a new trusted user for the relocated webtop. See Trusted Users and Third-Party Authentication.

procedure icon  How to Relocate the Webtop to Your Own JSP Technology Container

  1. Reconfigure the ports used by the SGD web server.

    If your JSP technology container is on the same host as an SGD server, you might have to reconfigure the ports used by the SGD web server.

    1. Change the ports that the SGD web server listens on.

      The SGD web server might be listening on the standard HTTP or HTTPS ports, TCP ports 80 or 443, depending on the ports selected for the SGD installation.

      Configure your web server to listen on TCP ports 80 or 443 and configure the SGD web server to use different ports, by editing the /opt/tarantella/webserver/apache/2.2.10_openssl‑0.9.8i_jk1.2.27/conf/httpd.conf file.

    2. Change the ports used by the Tomcat component of the SGD web server.

      The Tomcat component of the SGD web server uses port TCP ports 8005 and 8009. If these ports are used elsewhere, for example by your JSP technology container, you must change the Tomcat configuration.

      Edit the /opt/tarantella/webserver/tomcat/6.0.18_axis1.4/conf/server.xml file and change the server shutdown port on TCP port 8005 and the AJP 1.3 Connector port on TCP port 8009.

  2. Copy the webtop web application to your JSP technology container.

    Copy all the files in the following directories into the web applications directory on the new host:

    • /opt/tarantella/webserver/tomcat/6.0.18_axis1.4/webapps/sgd

    • /opt/tarantella/webserver/tomcat/6.0.18_axis1.4/webapps/axis



    Note - These directories contain symbolic links. Make sure you preserve the links when you copy the directories.



    Copy all the files in the /opt/tarantella/webserver/tomcat/6.0.18_axis1.4/shared/lib directory to the shared library directory on the new container.

    Copy all the files in the /opt/tarantella/webserver/tomcat/6.0.18_axis1.4/shared/classes directory to the shared classes directory on the new container.

  3. Copy the required library and class files.

    The webtop requires some additional library and class files, which must be copied to your container.

    Copy the following Javatrademark Archive (JAR) files from the /opt/tarantella/webserver/tomcat/6.0.18_axis1.4/common/lib directory to the global library directory on your container:

    • axis.jar

    • commons-discovery-0.2.jar

    • commons-logging-1.0.4.jar

    • jaxrpc.jar

    • saaj.jar

    • xerces.jar

  4. Configure the web services endpoints.

    The webtop uses the Simple Object Access Protocol (SOAP) protocol, over HTTP, to access the services provided by an SGD server. The webtop uses a Resources.properties file to determine the server and port to send the web services requests to. This is currently set to http://localhost.

    1. Edit the Resources.properties file.

      On the new host, edit the Resources.properties file in the shared classes directory. For example, for a Tomcat JSP technology container, this file is located in shared/classes/com/tarantella/tta/webservices/client/apis directory. Replace http://localhost:port with http://server.example.com:port, where server.example.com is the DNS name of an SGD server and port is the port that the SGD web server listens on. Do this for each of the web services listed in the properties file.

    2. Secure the SOAP connections.

      If the webtop is relocated to a different host or you are using SGD security services, secure the SOAP connections to an SGD server. See Securing SOAP Connections to an SGD Server.

  5. Restart your JSP technology container.

    You must restart your JSP technology container, to apply the global library and class file changes.

  6. Restart the SGD web server.

    If you made any configuration changes to the SGD web server, you must restart it to apply the changes.

  7. Log in to the relocated webtop.