Launching the Java Web Start Client

Launching the Java Web Start (JWS) client is a three step process:

  1. The JNLPLaunch command on GridShibCA.cgi is invoked to display a Credential Launch Form for the user asking them for parameters regarding how the JWS client should run.
  2. Submission of the Credential Launch Form invokes again with the JNLPLaunch comment, but with a number of other parameters. This causes the a page to be display that displays a status message to the user and, using javascript, automatically invokes launchGSCA.jnlp.
  3. Invocation of the launchGSCA,jnlp script generates a JNLP file that causes the JWS application on the user's system to download and launch the jar file which comprises the JWS client.
Details on each of these three steps follow.

The Credential Launch Form

The first step in the workflow is to display the form to user to get the parameters of their request. This can be accomplished GET (or POST) request to the GridShibCA.cgi web application with the following parameters:

  • command=JNLPLaunch
The request MUST be session-protected and MUST include a CSRF cookie so that the form results can pass CSRF-protection.

Credential Launch Form Submission

The Credential Launch form invokes the GridShibCA.cgi web application. The request MUST be session-protected and use POST.  The request MUST include the following parameters:

  • command=JNLPLaunch
    • Yes, same command used to generate form. The presence of the other parameters causes the web application to recognize the request as a form submission and act appropriately.
  • CSRFProtection=<string>
  • lifetime=<string>
    • The requested lifetime of the credential. Possible values are "default" or "specified".
      • If "default", then the default lifetime is request.
      • If "specified" then the value if specifiedLifetime and lifetimeUnit is used.
  • specifiedLifetime=<integer>
    • The lifetime requested by the user. The units of the value are given by lifetimeUnit.
  • lifetimeUnit=<string>
    • Currently should always be "hours" to indicate specifiedLifetime has units of hours.
  • DownloadTrustroots=<boolean>
    • If "true", the user is requesting installation of trust roots.
The result of this submission is a web page that has a form that invokes launchGSCA.jnlp. The form is automatically submitted by a javascript embedded in the page, if the user has javascript enabled, or manually submitted by the user otherwise.

Invoking launchGSCA.jnlp

The JNLP file, which caused the invocation of the JWS client by the browser, is done by invoking launchGSCA.jnlp web application. This application has the .jnlp extension since that causes all browsers to handle the outputed JNLP file correctly (see Bug 6719). 

The invocation MUST be via POST and be session-protected. It must include the following parameters:

  • CSRFProtection=<string>
  • RequestedLifetime=<integer>
    • The requested lifetime of the credential in seconds.
  • DownloadTrustroots=<boolean>
    • If "true", the user is requesting installation of trust roots.

Typically, launchGSCA.jnlp is invoked via the Credential Launch form, though any process that results in the above request could be used.