Playing around with the SSGD API (Part 2 : API-test pages)

During installation of Sun Secure Global Desktop (SSGD) a couple of extra web tools are created for SSGD Administrators/Developers. One of these web tools is an API testing tool for Developers. The base URL is:

http://[FQDN_SSGD_Server]/sgd/admin/apitest/

The webpage shown on this URL is divided in two parts. The left containing a menu where all the API-calls can be found and on the right hand side there is space for the result of the performed API-calls.



All available API-calls can be issued by using the menu. Most of the menu-items have a sub-menu with the actual API-calls. In the following example we will only use the menu-items 'webtopsession' and 'emulatorsession'.

Example:

Start an Application by using the API-test pages.

(SSGD version 4.4 and higher)

To manually start an application using API calls at least to following steps need to be performed:

1. Authenticate the user
2. Set the configuration of the TCC (The SGD Client Connector)
3. Start the TCC
4. Start the SGD Application

Authenticate the user

Since SSGD version 4.4 it is not needed to set up a new session before authentication, but the authentication can be done directly. Basically there are two types of authentication:

• System Authentication; The authentication is performed from within SSGD using the provided username and password.
• Third Party Authentication; The authentication is performed by a trusted external application/service which passed the user-ID to SSGD.

In this example we will be using the System Authentication for simplicity.

Authenticate the user by using the main API-test menu item: webtopsession
Use the function: authenticate
The only mandatory fields are 'Username' and 'Password'. Use a valid username and password and use the button 'Call' to perform the authentication.

In the right frame the result is shown with the most important attribute 'scottasessioncookie'. This attribute contains the ID of the 'webtop'-session. With the field 'Auto-fill Cookie' enabled the the session ID will be filled in automatically for all following API calls.

Set the configuration of the TCC

Before starting the SGD Client Connector (TCC) we must provide where the TCC can be downloaded, which version of the TCC must be used and which OS the user is using. This information can be specified via the setTCCConfiguration API-call (API-test main menu -> webtopsession -> setTCCConfiguration). By default all information is already filled in with the known information. (There is no need to change this information for use with the API-test tool, unless you are using SSL-offloading or using an external webserver).
Just a click on the 'Call' button is sufficient to provide all information.

Start the TCC

The TCC can be started via a separate webpage containing the TCC-Helper-plugin. This plugin is a Java-applet which will:

• Check if the correct TCC is already 'installed', if not download the TCC
• Start the TCC with the correct parameters

To create the TCC Helper webpage containing the required applet and parameters the API-call 'startTCC' can be used (API-test main menu -> webtopsession -> startTCC). Besides the 'Session Cookie' no extra information is required. The parameter 'Target' can be used to open the new webpage in a particular frame.

If all goes well the TCC will be started and we are ready to start a SSGD Application.

Start the SGD Application

An application can be started by starting an Emulator Session. We therefor switch to an other main menu item: emulatorsession.
The API-calls in the group 'emulatorsession' can be used to start, resume, suspend and list application sessions.

To start an application go to the API-call startSession (API-test main menu -> emulatorsession -> startSession). Fill in the Application Name (like: .../_ens/o=applications/cn=My Desktop) and click 'Call'.
To see which applications the user may start an API-call from the 'webtopcontent'-group must be used (searchWebtopContent), but a simple shortcut for this command is available: 'List Webtop'

The Application will start up just like it will be when clicking the Application-link in the browser-based-webtop.

Same Example in JSP-file

On the Sun wiki a example JSP-file is available which performs the same API-calls: Single sign-on JSP

By placing the attachement in the directory

/opt/tarantella/webserver/tomcat/[version]/webapps/sgd

After providing the same information from the example above in the JSP-file, the manual called API-calls can be performed automatically.

Example Summary

Perform the following API-calls to start an application:

1. webtopsession -> authenticate : Provide Username and Password
2. webtopsession -> setTCCConfiguration
3. webtopsession -> startTCC
4. emulatorsession -> startSession : Provide Application-name

Playing around with the SSGD API (Part 1: Introduction)

Sun Secure Global Desktop has a Web based Application Programming Interface (API). This API can be used to interact with the SSGD server from within a browser (by creating for instance JSP-files) or by creating a piece of java code to communicate with the SSGD server over http(s).

This opens up a lot of extra possibilities besides the already feature rich SSGD webtop, the web based Administration GUI and the other default options (like the Integrated Mode, Automatic Client Login). A few examples of features to be created using the API:

• A search page in the webtop; Let the user search for applications based on application name. might be handy if the user is presented with lots of applications.
• Remote Administration; Create applications objects from other systems (like Sun Identity Manager), create delegated administration.
• Create a webtop alike alternative without using a browser; With some java programming it is possible to re-create something with the same options as the webtop without use of a browser.
• Create a SSGD Health check; Most external hardware Load Balancer are able to check a specific webpage to verify the correct workings of the website besides the mostly used 'HTTP 200 OK' / Default HTTP check. The new health check can for instance perform the 'Tarantella status' command to enhance the health check by verifying the SSGD server is working normally.

It is my intention to explain how to work with the SSGD API in the next couple of blog posts. For the readers who do not want to wait and start playing with the API take a look at the Sun Wiki: Web Services Home Page.

Part 2 of this blog post serie will be about the API-test pages which are installed during the installation of Sun Secure Global Desktop.

SSGD Mac OS10.5 no key input possible

Today one of our customers stated that on their Mac clients the keyboard input was not passed to the applications provided by Sun Secure Global Desktop. They have searched the internet for a solution, but it is hard to find the simple fix.

Since MacOS 10.5.1 the location of the file XKeysymDB has been changed. When creating a symbolic link for this file in the 'old' location resolved the issue mentioned above.

ln -s /usr/X11/share/X11/XKeysymDB /usr/X11R6/lib/X11/XKeysymDB

Hopefully this post will make it easier to find this little fix.