How to develop delegation for Genero apps

Outlines the requirements for developing your own delegation service for applications running on Genero clients.

Developing a delegation service involves you creating the program that provides a secure process for allowing users access to your applications. The code contained in the service needs to take into account the different Genero clients that may be used to provide the applications. It will also be influenced by the different methods these clients use to launch applications.

Typically, the same code can be used by most of the clients. For the purpose of simplifying what you need to code, we can group the clients into Genero Browser Client (GBC) and "Non-GBC". The non-GBC clients consists of:
  • Genero Desktop Client (GDC)
  • Genero Mobile for Android™
  • Genero Mobile for iOS

Delegation for GBC and non-GBC clients

When the user agent launches an application, your delegation service receives a request for access to the application. Typically, you code to perform authentication or a log-in process. An HTTP code is returned to the dispatcher; allowing access or not.

For the non-GBC applications this is performed in the same request. For the GBC type application, two requests are needed to open the application:
  1. The first request (shown in the "GBC first call" workflow in the diagram ) needs to perform the authentication and fetch the GBC bootstrap page. This page gathers information about the browser and loads the GBC.
  2. The second request (the default for non-GBC clients) starts the actual Genero BDL application.
    Figure: Delegation workflow to start the application

    The diagram shows the work flow from the user agent to the delegation service via the dispatcher, to the start of the application. The steps are detailed in the text.
    The diagram represents the process of starting an application with delegation for both the GBC and non-GBC. The workflow is illustrated at a high level showing the components involved.
    GBC application bootstrap

    The GBC first call request is shown on the right hand side of the diagram, following the sequence to load the bootstrap.

    At step 1 prior to the GBC bootstrap, a call must be made first by the /ua/r/app to request to load the bootstrap.

    The dispatcher process (step A in the diagram) calls your delegate service with an additional HTTP header called X-FourJs-Environment-Parameter-Extra-BOOTSTRAP:REQUIRED. This means that you have not yet returned the bootstrap page.

    If your delegation service allows access to the application (step 2), you return the HTTP code 307 (step 3) and the bootstrap page is then loaded by the user-agent, which automatically re-sends the same /ua/r/app request to launch the application.

    Non-GBC and GBC applications
    Having the bootstrap for the GBC, the request by the /ua/r/app (shown on the workflow on the left) performs the actual launch of the application.
Once the application has started, then all subsequent requests to the application are in /ua/sua form and they no longer go through the delegation service.

Coding for delegation

In your delegate service you implement all that is required for the service. You perform your authentication, or the log in tasks you want users to perform (step 2 in the diagram). For instance, you may decide to return an HTML form for the user to enter credentials.

For the GBC type application because two requests are performed, it is recommended that you code to set a cookie with the session id on the first call, and store this information (usually in a database).

When the second request comes (for the GBC type application only, step B) you can check if the session id stored on the first call corresponds with the session id in the second request. This ensures that the first request has been successful and the application launch can go ahead.

On the second request also the presence of an additional HTTP header called X-FourJs-Environment-Parameter-Extra-BOOTSTRAP means that the bootstrap page has been loaded.

At step 3 you must also code to return all the X-FourJs-Environment-* variables that the uaproxy needs to start the application.
Note: There is no need to set them at the bootstrap request stage because the proxy is not started at this stage.
For an example of coding a simple delegation service, see the "ex_simplesso" service on the Four Js Genero GitHub page.