Web Terminal Integration

by Green Screens Ltd.

Some of our clients has a requirement to integrate Green Screens 5250 Web Terminal into their own web applications. Often, one of the requirements is automatic login for an already authorized user into their own web application so that the terminal will open at the required screen / program.

Green Screens 5250 Web Terminal supports Kerberos integrations, however, in some cases this is not available or customer simply does not use this feature - which is considered the safest approach.  So, we need to use alternative.

Here we will explain and show you how this can be achieved securely.

Types of web terminal url

Green Screens 5250 Web Terminal supports 3 URL formats:

  • http://localhost/terminal#$uuid=0&host=DEMO&user=QSECOFR&password=QSECOFR
  • http://localhost/terminal#!eyJ1dWlkIjoiMCIsImhvc3QiOiJERU1PIiwidXNlciI6IlFTRUNPRlIiLCJwYXNzd29yZCI6IlFTRUNPRlIifQ==
  • http://localhost/terminal?d=[LONG_HEX]&k=[LONG_HEX]

The first two uses browser hash fragment, a part of URL which is not sent over the network but can be used by JavaScript to read transferred parameters.

The Green Screens 5250 Web Terminal will use those arguments to create an encrypted URL and redirect itself to URL format in the 3rd example. Creation and redirection itself is quick, unprotected hash fragment based URL is rewritten locally in the browser.

When clients wants to integrate Green Screens 5250 Web Terminal into their own web ERP apps, especially when using IFRAME elements, using the first two methods are not secure and can reveal login username and password.

The solution is to programmatically generate encrypted URL.

Generating encrypted URL

Generation itself can be done at the server side or browser side.  The method is the same regardless which module is used. Provide all required login attributes in JSON form, convert into encrypted URL and use that instead.

How Link builder engine works?

  • Provide a URL to the Green Screens Service (example: http://localhost:8080)
  • Engine will load some server info from http://localhost:8080/services/auth including public RSA key used for encryption.
  • Provide login data such as UUID/HOST/USER/PASSOWRD/DISPLAYNAME etc.
  • Call build function
  • Server will do the following
  • generate a temporary AES key
  • encrypt the key with the server provided public RSA
  • encrypt the JSON data with the AES key
  • convert encrypted data into HEX format
  • generate connection URL

NOTE: Depending on host configuration settings, some additional parameters might be required such as browser fingerprint ID, API Key or link expiration parameter.

Generating at the server side
This is more complex but more secure if bypass sign-on data is required and workstation operator credentials are available internally from some database, LDAP etc.

The base concept is to create a backend service which will receive some token uniquely identifying an existing user on IBM i server. Use your own mechanism to retrieve IBM i username and password, which will be provided to the URL builder. Return the generated URL to the browser and use JavaScript to either open the received encrypted URL in a new tab/window or embed as an IFRAME.

The Java library and sample Java WebApp code can be found here
https://github.com/greenscreens-io/java-encrypter

The PHP library can be found here https://github.com/greenscreens-io/php-encrypter

For Node.js, browser version can be used with the latest Node.js, supporting fetch function. Check at the end of LinkBuilder.mjs file for instructions.

Generating at the browser
In some cases, client web application already has IBM i username/password inside web application itself. Of course, this is dangerous for security reasons, however we are here only to provide support for safe encrypted URL to the web 5250 terminal with bypass sign-on enabled.  

Simply include LinkBuilder.mjs file into a web page and use sample code below.
NOTE: Browser library requires HTTPS as Crypto API (window.crypto.subtle) is not available when HTTP is used.

// Creata a new builder instance
const builder = new LinkBuilder();

// set parameters (only UUID/HOST are mandatory)
builder.setUUID('0').setHost('DEMO').setUser('QSECOFR').setPassword('QSECOFR').setDisplayName('DSPJOHNDOE').setCodePage('870');

// optionally to open speciffic program
builder.setProgram('WRKACTJOB').setLibrary('QSYS');

// call build to generate encrypted URL
const url = await builder.build('http://localhost:8080');

// use generated URL
window.open(url);

The complete source is a single file, can be downloaded from here :
https://www.greenscreens.io/updates/LinkBuilder.mjs