Tuesday, December 30, 2008

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:

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'.

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
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


Rob Tunru said...

Hi Remold,

A very nice and useful article !

Thanks for sharing the knowledge.


Rob Tunru

cbarber said...

Hi Remold,

Thanks for blogging about this! I've been hoping there would be a way to use SGD's api to improve the experience of users who don't have java. Do you think it's possible to make something like the following happen?

-Allow us to give our users a more streamlined experience
-NOT require folks to have java in order to get the best possible experience
-Have a totally custom-branded look

-Right now, say a user in integrated mode wants to start an application. He clicks "start application" and if the application is suspended he gets an error telling him to go his webtop to resume/kill the application. This confuses most users
-Say a user does make it to his webtop and finds the obscure "play" button to resume the application, maybe he then uses it for a while and then closes the application. Because he doesn't have Java, the webtop didn't update and he clicks "play" again but gets a fault error because the session cannot be found.
-All in all, it's difficult to create a simple, intuitive experience for users who don't have java

But with this API, maybe there is a better way:

Option 1: User clicks "My Desktop" shortcut on their desktop. This runs tcc on the command line with switch -application https://servername/sgd/sgd/CUSTOMPAGE.jsp. (this is just like the "Webtop" link that comes up in integrated mode, but it's now going to go to a custom page instead)

Option 2: User clicks "My Desktop" link on https://servername/sgd/sgd/CUSTOMPAGE.jsp.

1) If the user is already authenticated and tcc client is started, goes to step 3. If not, goes to step 2.

2) If was Option 1, runs the tcc client and goes to page that asks for username and password. If was Option 2, uses java applet to download/install and call the tcc client and goes to page that asks for username and password. Authenticates user.

3) Checks to see if the application is open, not open, or suspended. If:
-open: Then brings it to front
-not open: then launches it
-suspended: then resumes it


Remold Krol said...


The simple answer to the question "Is it possible" is Yes. All the information and the hooks to that information is available. I have not tested it, but there is nothing in the way to create the something you are looking for.

There are multiple options to get the job done (even more then listed below):
- Create a wrapper application for the TCC in java to directly communicate via the web services with SSGD. To use this option you must convert the java application to an executable (see: http://www.excelsior-usa.com/articles/java-to-exe.html#aot) to use it without installing the JRE on the client.
- Create a wrapper script in a non java language to communicate with SSGD in a 'client-server'configuration with the server components as JSP-pages on the SSGD server. You can code the logic you need in the JSP pages and have a 'simple' wrapper for the TCC on the client.

To make a totally custom-branded look of SSGD you can also change all the related JSP-pages. I have done that for a couple of our customers, for 1 client I even changed the language to Dutch including the relevant system messages. To start changing the Look and Feel of the pages take a look of some of my other posts:

I see just one strange thing in your proposal. Option 2 does not work without java, since it uses the java-applet in the browser.

It need a bit more thought to grasp all the things you want and to understand your needs. It looks like you have users who access via different methods, like users using only the webtop, users via integrated mode and users without java.

cbarber said...

Hi Remold,

Thanks for your post. Yes, option 2 would be for folks who have java.

I think the special sauce, the most important part is here:

3) Checks to see if the application is open, not open, or suspended. If:
-open: Then brings it to front
-not open: then launches it
-suspended: then resumes it

I'd be happy just to modify the existing jsp pages so that you can click on a URL or pass tcc a string and it will perform this operation. I just couldn't tell from the api which function calls to make so that with just 1 string, SGD will know what to do (whether to bring to front, open, or resume).


Remold Krol said...

I have not played lots with the Integrated Mode nor combined the Integrated Mode together with the API. This makes it a bit hard to tell exactly who to approach this.

When looking at the webtop.jsp and the webtopcommon.jsp (Version > 4.41) you can enumerate the webtop items via the webtopEnum class and use the method isEmulatorSession() from the parent view class to see if the application has already been started. Via the API it is a bit different and maybe simpler.

Using the API you can use the emulatorsession->search. This will give a list of all started emulator sessions. When you find the application in the list you know it has already been started. Keep in mind applications can be started more then once, depending on the application settings.

You can find more information of the API-calls/Webservices etc on the Sun Wikis including documentation and a few examples: http://wikis.sun.com/display/SecureGlobalDesktop/Web+Services+(from+4.40)