Configuring Load Balancing

5.8.1. Entering Credentials

Thinfinity VirtualUI allows you to enable one or more authentication methods at a time. There are two possible ways to ask for credentials:

· Using the standard Web Browser authentication dialog

· Showing a log-in page

The Standard Web Browser Authentication (aka Basic Authentication) is, in the context of an HTTP/HTTPS transaction, a method for the HTTP User Agent (the Web Browser) to provide end-user credentials when a request is started. The standard Web Browser authentication dialog is provided by each Web Browser and it looks like this:

This dialog is available when you use only one of the authentication access methods that require user and password: Windows Logon, RADIUS or External DLL.

Also, you can use a login page. The login page provided (login.html) was created to dynamically show all configured authentication methods in your Thinfinity VirtualUI Server. Every login option will be present only if the proper authentication method is configured.

For example, if only the 'Windows Logon' method is configured, the page will look like this:

But if you enable all predefined methods, your login will show something like this:

You can modify this page to adapt it to your branding and/or integration needs. Check out the login.html section to learn how.

Read more:

· login.html

5.8.2. Processing End-user Credentials

Each published application without anonymous access requires the assignment of one or more Active Directory objects which define the users that can see and execute it.

Thinfinity VirtualUI implements a mapping mechanism to transform end-user credentials to AD objects. Only applications that match these AD objects will be granted access to the end-user.

When you enable an authentication method, you must add the mapping rules that will allow you to link the user ID with an AD object. This is done by specifying an external user ID mask and its linked AD objects.

Depending on the selected authentication method, Thinfinity VirtualUI uses the identification provided provided by the user to scan the mapping rule list and obtains the associated AD objects. If the matching process returns one or more AD objects, all applications with the same AD object are enabled to be seen and accessed by the end-user.

Read more:

5.8.3. Authentication Methods

Thinfinity VirtualUI allows you to use the following authentication methods.

Windows Logon

This option enables Active Directory credentials. This method is enabled by default.

RADIUS

Remote Authentication Dial-In User Service (RADIUS) is a networking protocol and software that provides centralized Authentication, Authorization, and Accounting (AAA) management for users who remotely connect to a network service, in this case the Thinfinity VirtualUI Server.

OAuth 2.0

OAuth 2.0 (or OAuth/2) is an open standard for authorization and authentication, commonly used as a way for Internet users to log into third party websites using their social network (Facebook, Google, LinkedIn, etc.) account without exposing their password.

External DLL

A custom authentication method implemented by you or a third party with our authentication API and referenced in the Thinfinity VirtualUI server.

Anonymous Authentication

You can also allow users to access applications anonymously. When this access is combined with other authentication methods, the anonymous access applications will be shown along with a 'Sign in' link for users to enter credentials.

All these methods will be enabled and configured in the Thinfinity VirtualUI Server Manager: choose the methods in the 'Authentication' tab and configure the mapping in the 'Mappings' subtab.

Read more:

· RADIUS

5.8.3.1. Windows Logon

Windows Logon means that the end-user will have to enter Windows Activate Directory credentials in order to gain access to a set of applications defined in Thinfinity VirtualUI.

The profiles matching the credentials provided in their the 'Permissions' tab will be the profiles shown to the authenticated user, along with those with the 'Allow Anonymous Access' option checked in their 'Permissions' tab

Windows Logon is enabled by default in the 'Authentication' tab of the Thinfinity VirtualUI Server Manager. Toggle its availability as an authentication method by checking or unchecking it.

Read more:

· RADIUS

5.8.3.2. RADIUS

RADIUS as an authentication method means that the user will have to enter their RADIUS credentials in order to gain access to a set of applications defined in Thinfinity VirtualUI.

RADIUS can be added in the 'Authentication' tab of the Thinfinity VirtualUI Server Manager. Toggle its availability as an authentication method by checking or unchecking it.

When you add RADIUS as an authentication method you will be required to provide the RADIUS account relevant information.

The user definition is completed through the mapping between the user ID returned by RADIUS and a user registered for this Authentication ID Mask. The RADIUS credentials are mapped to Active Directory Objects in the 'Mappings' tab. Those Active Directory objects should satisfy the permission access rules of the applications that they are expected to get access to.

Read more:

5.8.3.3. OAuth 2.0

OAuth 2.0 is a standard authentication method used mostly in social web sites. The user will have to enter their OAuth 2.0 (Facebook, Dropbox, LinkedIn, Google or other) credentials in order to gain access to a set of applications defined in Thinfinity VirtualUI.

An OAuth 2.0 authentication method can be added in the 'Authentication' tab of the Thinfinity VirtualUI Server Manager. Toggle their availability as an authentication method by checking or unchecking them.

When you add an OAuth 2.0 method you will be required to provide the relevant information. Check the complete reference in the OAuth 2.0 Authentication Method Settings. This information is also reflected in the OAuth2Models.ini file, distributed with the installation.

The user definition is completed through the mapping between the user ID returned by the selected OAuth 2.0 method (in the examples mentioned it's always the email) and a user registered for this Authentication ID Mask. The OAuth 2.0 method's credentials are mapped to Active Directory Objects in the 'Mappings' tab. Those Active Directory objects should satisfy the permission access rules of the applications that they are expected to get access to.

Read more:

· CSS for SSO options

5.8.3.3.1. OAuth2Models.ini

OAuth2Models.ini is a file is distributed with the Thinfinity VirtualUI installation that has all the information of the default available logins:

[Google]

ClientID =

ClientSecret =

AuthorizationParameters = scope=https://www.googleapis.com/auth/userinfo.email&approval_prompt=auto

AuthorizationURL = https://accounts.google.com/o/oauth2/auth

TokenValidationURL = https://accounts.google.com/o/oauth2/token

ProfileValidationURL = https://www.googleapis.com/oauth2/v1/userinfo

UsernameField = email

[Facebook]

ClientID =

ClientSecret =

AuthorizationParameters = scope=email

AuthorizationURL = https://www.facebook.com/dialog/oauth

TokenValidationURL = https://graph.facebook.com/oauth/access_token

ProfileValidationURL = https://graph.facebook.com/me?

UsernameField = email

[LinkedIn]

ClientID =

ClientSecret =

AuthorizationURL = https://www.linkedin.com/uas/oauth2/authorization

AuthorizationParameters = state=HIJK98sDT88jnS23S&scope=r_emailaddress

TokenValidationURL = https://www.linkedin.com/uas/oauth2/accessToken

ProfileValidationURL = https://api.linkedin.com/v1/people/~:(emailAddress)?format=json

UsernameField = emailAddress

[Dropbox]

ClientID =

ClientSecret =

AuthorizationURL = https://www.dropbox.com/1/oauth2/authorize

AuthorizationParameters =

TokenValidationURL = https://api.dropboxapi.com/1/oauth2/token

ProfileValidationURL = https://api.dropboxapi.com/1/account/info

UsernameField = email

Use this file as a template and edit it in order to add new authentication methods or ask your authentication provider for different data.

Read more:

5.8.3.3.2. CSS for SSO Options

In the login.css file, included in the 'web\css' folder of the Thinfinity VirtualUI installation, you will find the style for the login buttons.

#google { background-color:#4285F4; }

#google .imgbtn { background-image: url(../images/sso/google.png); }

#facebook { background-color:#2f4e9e; }

#facebook .imgbtn { background-image: url(../images/sso/facebook.png); }

#yahoo { background-color:#6839af; }

#yahoo .imgbtn { background-image: url(../images/sso/yahoo.png); background-size: 30px; }

#linkedin { background-color:#00A0DC; }

#linkedin .imgbtn { background-image: url(../images/sso/linkedin.png); }

#dropbox { background-color:#007ee6; }

#dropbox .imgbtn { background-image: url(../images/sso/dropbox.png); background-size: 30px; }

You can change the logo and/or background color of the login buttons for the Oauth 2.0 authentication methods.

Each pair of entries corresponds to one authentication method. The ID (#google, #facebook) must match the Virtual Path established in the Oauth 2.0 Authentication Method Settings. With the installation, these parameters are matching by default, but make sure to change it in both places if you do.

The first line of each pair defines the button color, and the second one the button image.

Read more:

· RADIUS

5.8.3.4. External DLL

Thinfinity VirtualUI allows you to integrate your own custom authentication method. In order to do this, use the Thinfinity VirtualUI Authentication API.

The External DLL authentication method can be added in the 'Authentication' tab of the Thinfinity VirtualUI Server Manager. Toggle its availability as an authentication method by checking or unchecking it.

When you add an External DLL authentication method you will be required to reference the .dll in the 'External DLL' option. Check the complete reference in the External DLL Authentication Method Settings.

The user definition is completed through the mapping between the user ID returned by the external DLL and an Active Directory Objects mapped for this Authentication ID Mask.

Read more:

5.8.3.4.1. Authentication API

Thinfinity VirtualUI provides you with an API that you can use to develop your own authentication method and integrate it with VirtualUI.

Choose the code sample of your language of preference and add it to your implementation:

Delphi:

function ValidateUser(

const UserName, Password, Metadata: PWideChar;

SecurityRole, WinUser, WinPass, CustomData: PWideChar;

var Handled: Boolean): Cardinal; stdcall;

Input:

Username & Password

The credentials that you are trying to validate with the external authentication

Metadata

A JSON with the remote browser/user information: URL, IP, Cookie UBRWID and the product's name

Output:

SecurityRole

Specifies the Windows mapping of the authenticated user (UserName and Password). This SecurityRole can either be a Windows user or group, and it will be used to check which profiles it has access to

WinUser, WinPass

(optional) Credentials of a mapped Windows user. Will be used to run the application instance.

CustomData

(optional) Data for passing on to the application

Handled

Returns whether the login could be handled by the DLL.

C++:

THINFINITY_API DWORD __stdcall ValidateUser(LPWSTR lpUserName, LPWSTR lpPassword, LPWSTR lpMetadata, LPWSTR lpSecurityRole, LPWSTR lpWinUser, LPWSTR lpWinPass, LPWSTR lpCustomData,

PBOOLEAN pHandled)

Input:

lpUserName & lpPassword

The credentials that you are trying to validate with the external authentication

lpMetadata

A JSON with the remote browser/user information: URL, IP, Cookie UBRWID and the product's name

Output:

lpSecurityRole

Specifies the Windows mapping of the authenticated user (UserName and Password). This SecurityRole can either be a Windows user or group, and it will be used to check which profiles it has access to

lpWinUser, lpWinPass

(optional) Credentials of a mapped Windows user. Will be used to run the application instance.

lpCustomData

Data for passing on to the application

pHandled

Returns whether the login could be handled by the DLL.

C#:

[DllExport("ValidateUser", CallingConvention = CallingConvention.StdCall)] [return: MarshalAs(UnmanagedType.I4)] public static Int32 ValidateUser( [In, MarshalAs(UnmanagedType.LPWStr)] string lpUserName, [In, MarshalAs(UnmanagedType.LPWStr)] string lpPassword, [In, MarshalAs(UnmanagedType.LPWStr)] string lpMetadata,

[In, Out, MarshalAs(UnmanagedType.LPWStr)] StringBuilder lpSecurityRole, [In, Out, MarshalAs(UnmanagedType.LPWStr)] StringBuilder lpWinUser, [In, Out, MarshalAs(UnmanagedType.LPWStr)] StringBuilder lpWinPass, [In, Out, MarshalAs(UnmanagedType.LPWStr)] StringBuilder lpCustomData, [Out] bool pHandled);

Input:

lpUserName & lpPassword

Specifies the Windows mapping of the authenticated user (UserName and Password). This SecurityRole can either be a Windows user or group, and it will be used to check which profiles it has access to

lpMetadata

A JSON with the remote browser/user information: URL, IP, Cookie UBRWID and the product's name

Output:

lpSecurityRole

The authenticated username

lpWinUser, lpWinPass

(optional) Credentials of a mapped Windows user. Will be used to run the application instance.

lpCustomData

Data for passing on to the application

pHandled

Returns whether the login could be handled by the DLL.

Read more:

5.9. Virtualization

In Thinfinity VirtualUI, each application instance may run under a unique Windows User ID or under a shared one. In the first case, the application may access private folders and private registry entries but, as most applications provide their own credential system (usually based on a database), it is a common practice to run the application instance under a single shared Windows User ID. In this case, all application instances share the same user profile’s folders and the same “current user” key in the registry.

Additionally, in both cases, all users may have access to shared folders that it might be desirable to hide from them.

Thinfinity VirtualUI addresses these potential drawbacks by providing the File System and Registry Virtualization feature.

The main purposes of the Registry and File System virtualization are:

· To show only relevant folders.

· To provide private folders based on the application's credential system.

· To provide registry keys based on the application's credential system.

Read more:

5.9.1. File System Virtualization

File System Virtualization helps developers publish only relevant shared folders and provide authentication-based private folders. Additionally, shared folders can be redirected to safer places in the disk and/or be write protected.

Virtualization involves two steps. The first one is the File System mapping design, when the developer creates the relationship between real paths and the redirected path tree that the end-user will see and access. The second one, the inclusion of the created mapping definition into the application program.

The file system mapping definition is a set of one to one redirection rules that link a real folder to the redirected folder path.

There are two types of redirection:

· Shared: for all connected users. It can be defined as readonly.

· Private: for a single identified user.

The configuration is done through the The File System Virtualization Editor, which will be installed with the Standard or server component installation.

Read more:

5.9.1.1. Creating File System Redirections

In order to add a path in the Virtualization Editor, right click on the main area of the screen and choose 'New Path...'.

This will bring up the 'Edit Directory' dialog.

Field

Description

Mode

Choose 'Shared' if you want this mapping to apply to all users.

Choose 'Private' if you only want this mapping to apply to a single user.

Read Only

Only available for Shared Mode. Check this option to make the mapped directory read only for the user.

5.9.1.2. The .vdir Files

Once you are done adding, editing and/or deleting paths, save this configuration by selecting 'File' - 'Save' in the main menu of the Filesystem Virtualization Editor. This configuration will be stored in a vdir file. The Filesystem Virtualization Editor allows you to create different vdir files to be used in your application.

Read more:

5.9.1.3. Testing the File System Virtualization

You can test the Filesystem virtualization outside VirtualUI (the virtualization service must be running, though). In order to test the Filesystem virtualization, choose the 'File' - 'Test' option from the main menu. This will bring up the 'Launch Application' dialog:

Field

Description

User

Type in a testing user name. Later on, you can test using another user and verify that the files stored for each user are isolated.

Program

Choose a program with which to test the Filesystem virtualization. It has to be a program capable of opening files.

After selecting a user and a program to test, press the 'Launch' button. When you access the Windows file system through this application, you should only be seeing the mapped directories, by their original names.

Read more:

5.9.2. Registry Virtualization

Registry Virtualization allows developers to store end-user information in the Windows Registry in a secure and isolated way and to provide authentication-based registry entries.

Additionally, shared registry entries can be redirected to safer places in the Windows Registry.

Similarly to File System Virtualization, Registry Virtualization also involves two steps. The first one is the mapping definition, when the developer creates the relationship between an original registry entry and a redirected registry entry. The second one, the inclusion of the created mapping definition into the application program.

The registry mapping definition is a set of one to one redirection rules that link a real entry to the redirected entry.

There are two types of redirection:

· Shared: for all connected users.

· Private: for a single identified user.

Private redirection entries include the identified user ID appended to the redirected entry.

The configuration is done through the Registry Virtualization Editor, which will be installed with the Standard or server component installation.

Read more:

5.9.2.1. Creating Registry Redirections

In order to add a registry redirection, right click on one of the Server trees and choose 'Add Redirection'.

This will bring up the 'Edit Key Redirection' dialog:

Field

Description

Mode

Choose 'Shared' if you want this key redirection to apply to all users.

Choose 'Private' if you only want this key redirection to apply to a single user.

Source

Choose the source registry key you want to redirect.

Destination

Choose a registry destination key.

Editing Redirections

In order to edit a key redirection, right click on it and choose 'Edit Redirection'.

You will then be able to edit the redirection in the 'Edit Key Redirection' dialog.

Deleting Redirections

In order to delete a redirection, right click on it and choose 'Delete Redirection'.

Read more:

5.9.2.2. The .vreg Files

Once you are done adding, editing and/or deleting redirections, save this configuration by selecting 'File' - 'Save' in the main menu of the Registry Virtualization Editor. This configuration will be stored in a vreg file. The Registry Virtualization Editor allows you to create different vreg files to be used with the product.

Read more:

5.9.2.3. Testing Registry Virtualization

In order to test the registry virtualization, choose the 'File' - 'Test' option from the main menu. This will bring up the 'Launch Application' dialog:

Field

Description

User

Type in a testing user name. Later on, you can test using another user and verify that the registry changes stored for each user are isolated.

Program

Choose a program with which to test the registry virtualization. It has to be a program that uses the registry.

After selecting a user and a program from the test, press the 'Launch' button. This will open the selected application and create a unique key for the user in the redirected key. All the activity of this application in the registry for the source key will be reflected in the redirected key.

Read more:

5.9.3. Implementing Virtualization in Your Application

In order to apply the virtualization filters created with the Filesystem Virtualization Editor or the Registry Virtualization Editor, you have to add some code to your application.

After virtualui.Start(), load and apply the created filters with the current user credentials

Delphi:

virtualui.RegistryFilter.User := 'user identification';

virtualui.RegistryFilter.CfgFile := 'file.vreg';

virtualui.RegistryFilter.Active := true;

virtualui.FilesystemFilter.User := 'user identification';

virtualui.FilesystemFilter.CfgFile := 'file.vdir';

virtualui.FilesystemFilter.Active := true;

C#:

virtualui.Start();

virtualui.RegistryFilter().User = “user identification”;

virtualui.RegistryFilter().CfgFile = “file.vreg”;

virtualui.RegistryFilter().Active = True;

virtualui.FilesystemFilter().User = “user identification”;

virtualui.FilesystemFilter().CfgFile = “file.vdir”;

virtualui.FilesystemFilter().Active = True;

C++:

virtualui->Start();

virtualui->RegistryFilter()->User = “user identification”;

virtualui->RegistryFilter()->CfgFile = “file.vreg”;

virtualui->RegistryFilter()->Active = True;

virtualui->FilesystemFilter()->User = “user identification”;

virtualui->FilesystemFilter()->CfgFile = “file.vdir”;

virtualui->FilesystemFilter()->Active = True;

In order to disable registry or filesystem filtering, set the Active property to false.

Read more:

5.10. OEM Licensing

If your product qualifies for OEM licensing, we will provide you with a Thinfinity VirtualUI OEM Licensing Library that enables OEM-licensed Companies to create and revoke end-user Thinfinity VirtualUI licenses.

There are two prerequisites:

· The application that uses the OEM Licensing Library (Thinfinity.VirtualUI.OEM.dll) must be digitally signed.

· You must have a valid OEM key.

To get an OEM key, you must provide Cybele Software with a digital certificate's thumbprint. On each licensing request, three parameters will be used to validate the requestor:

· The OEM-licensed Company's e-mail.

· The provided OEM key.

· The digital certificate's fingerprint, taken from the digital certificate that signs the executable making the OEM library call.

The generated OEM key and the digital certificate's thumbprint, along with your customer identification (e-mail), will be used to securely validate the licensing requests your application will make.

Read more:

5.10.1. How to Create and Revoke Licenses

visThe OEM library provides two functions to create a license and two functions to revoke a license:

· CreateLicenseW (Unicode version) and CreateLicenseA (ANSI version).

· RevokeLicenseW (Unicode version) and RevokeLicenseA (ANSI version).

In order to test the license creation and activation process, you can enable the SandboxMode in the OEM.ini file.

[LICENSE]

SandboxMode = True

The OEM.ini file should be placed in both the bin32 and bin64 paths under the Thinfinity VirtualUI installation folder and in the user's application executable file folder.

The software will first look for the file in the executable's directory (either the application's or any server's). If it doesn't find it there, there are two alternatives:

For the virtualizer, which is in ibin, it will search in bin64 and, afterwards, in bin32
For the rest of the cases. it searches for it in the parent directory. That is, if something runs in bin32 or bin64 it can use an oem.ini from their parent directory.

Adding External Methods

In a Delphi program we must first declare the external functions in their ANSI or Unicode version.

ANSI:

function CreateLicenseA(const email, oemkey, customerid: PAnsiChar;

units: DWORD; serial: PAnsiChar): integer; stdcall;

external 'Thinfinity.VirtualUI.OEM.dll';

function RevokeLicenseA(const email, oemkey, serial: PAnsiChar): integer; stdcall;

external 'Thinfinity.VirtualUI.OEM.dll';

Unicode:

function CreateLicenseW(const email, oemkey, customerid: PWideChar;

units: DWORD; serial: PWideChar): integer; stdcall;

external 'Thinfinity.VirtualUI.OEM.dll';

function RevokeLicenseW(const email, oemkey, serial: PWideChar): integer; stdcall;

external 'Thinfinity.VirtualUI.OEM.dll';

In order to access external library functions in a C# program, please declare:

[DllImport("Thinfinity.VirtualUI.OEM.dll",

CallingConvention = CallingConvention.StdCall, CharSet = CharSet.Unicode)]

private static extern int CreateLicenseW(string email, string oemkey,

string customerid, int units, StringBuilder serial);

[DllImport("Thinfinity.VirtualUI.OEM.dll",

CallingConvention = CallingConvention.StdCall, CharSet = CharSet.Unicode)]

private static extern int RevokeLicenseW(string email, string oemkey, string serial);

Read more:

5.10.1.1. Creating Licenses

In order to create a new Thinfinity VirtualUI license you must use the corresponding CreateLicense method with the following parameters:

Email

OEM-licensed Company´s e-mail

OEMKey

OEM Key.

CustomerID

Arbitrary customer identification for the new license. This can be an e-mail address, a serial number or any other customer identification.

Units

Number of units to enable in this license. Each unit contains a predefined number of concurrent users. If your OEM license has 5 users per unit, and you assign 2 units to the product license, the customer will have 10 concurrent users in total.

Serial

out

Serial number of the successfully generated license.

A call to the CreateLicense function will return one of the following error codes:

No error. The "Serial" parameter will contain the generated serial number.

-1

General error in license server.

-2

Incorrect Email or OEM Key.

-3

No more units available.

-4

OEM License expired.

-5

General error. Cannot create license.

-10

Invalid response received from license server.

-20

Malformed response received from license server.

-100

General error in library.

-101

Application invalid: not digitally signed.

>200

HTTP status code.

The following example shows how to create a license using Delphi. Please note that you must replace CreateLicenseW by CreateLicenseA when using ANSI chars.

procedure CreateLicense;

var

result: Integer;

serial: WideString;

begin

serial := StringOfChar(' ', 128);

result := CreateLicenseW(PChar('OEM_EMAIL'), PChar('OEM_KEY'),

PChar('CUSTOMER_ID'), UNIT_COUNT, PWideChar(serial)); // Check result

end;

And this is how you create it using C#:

private void CreateLicense()

{

StringBuilder sn = new StringBuilder(128);

int result = CreateLicenseW("OEM_EMAIL", "OEM_KEY",

"CUSTOMER_ID", UNIT_COUNT), sn);

string serial = "";

// Check result

if (result == 0)

{

serial = sn.ToString().Trim();

}

else

{

// Error

}

Note: In all these examples, please replace 'OEM_EMAIL' and 'OEM_KEY' with your Company's OEM registration, 'CUSTOMER_ID' with the Customer identification and 'UNIT_COUNT' with the desired value.

Read more:

5.10.1.2. Revoking Licenses

The RevokeLicense function is used to revoke a previously generated license. These are its parameters:

Email

OEM-licensed Company's e-mail

OEMKey

OEM License Key.

Serial

Serial number to revoke.

This function will return one of the following error codes:

No error. The license was revoked.

-1

General error in license server.

-2

Incorrect Email or OEMKey.

-3

Incorrect Serial number.

-4

Incorrect Serial number.

-5

General error. Cannot revoke license.

-10

Invalid response received from license server.

-20

Malformed response received from license server.

-50

Error in HTTP request.

-100

General error in library.

-101

Application invalid: not digitally signed.

>200

HTTP status code.

Here's how to revoke a license using Delphi:

procedure RevokeLicense;

var result: Integer;

begin

result := RevokeLicenseW(PChar('OEM_EMAIL'), PChar('OEM_KEY'), PChar('SERIAL_NUMBER'); // Check result

end;

And here's how to revoke a license using C#:

private void RevokeLicense() {

int result = RevokeLicenseW("OEM_EMAIL", "OEM_KEY", "SERIAL_NUMBER"); // Check result

}

Note: Please replace 'OEM_EMAIL' and 'OEM_KEY' with your Company's OEM registration information, and replace 'SERIAL_NUMBER' with the Serial to revoke.

Read more:

· Enabling Multiple RDS Accounts

5.11. Silent Install Options

The VirtulalUI installation can be run in 'silent' mode, that is, without the need for user interaction. This can be useful if you are a system administrator and you want to automate the VirtualUI installation or if you are deploying it over your local network. Also, if you have an OEM Licensing model you will probably use a silent install.

Thinfinity VirtualUI Line Switches

In order to perform a silent installation, use this command line:

c:\Thinfinity_VirtualUI_Setup_x64.exe /s /v/qn

These are additional command line switches that you can pass on to the setup file:

Variable

Description

Default value

VFMX_SERVER_MODE

Determines whether the server components will be installed

TRUE

VFMX_DEV_MODE

Determines whether the development components will be installed

TRUE

VIRTUALIZATION

Determines whether the Virtualization components will be installed. In order for this option to be enabled, VFMX_SERVER_MODE cannot be FALSE.

FALSE

STDLBMODE

Values:

- LBMODE: Load balancing mode

- STDMODE: Standard mode.

STDMODE

SM_TYPE

Values:

- SM_Complete : Installs Server and Gateway components

- SM_Broker: Installs only Server components

- SM_Gateway: Installs only Gateway components.

Note: In order for this option to be enabled, STDLBMODE has to be set to LBMODE.

EMAIL

Complete this variable with your registration email. Also make sure to include the SERIAL parameter in order for the registration to work.

SERIAL

Complete this variable with your registration serial. Also make sure to include the EMAIL parameter in order for the registration to work.

The VFMX_SERVER_MODE, VFMX_DEV_MODE and VIRTUALIZATION parameters correspond to these installation wizard options:

The STDLBMODE and SM_TYPE parameters correspond to these installation wizard options:

The default installation will install Thinfinity VirtualUI Server in standard mode and the development components, but not the virtualization components.

Examples

· Installing Thinfinity VirtualUI in Standard Mode with Virtualization Components and without Development Environment:

c:\Thinfinity_VirtualUI_v2_Setup_x64.exe /s /v"/qn VIRTUALIZATION=\"TRUE\" VFMX_DEV_MODE=\"FALSE\""

· Installing Thinfinity VirtualUI Development environment only:

c:\Thinfinity_VirtualUI_v2_Setup_x64.exe /s /v"/qn VFMX_SERVER_MODE=\"FALSE\""

· Installing Thinfinity VirtualUI in Load Balancing mode using Gateway and Server roles and including licensing:

C:\Thinfinity_VirtualUI_v2_Setup_x64.exe /s /v"/qn EMAIL=\"myemail@mydomain.com\" SERIAL=\"45EI-09IJ-OOA6-3GH5-IT5E-E4ER-KIP9-A669\" STDLBMODE=\"LBMODE\" SM_TYPE=\"SM_Complete\""

Scaling and Load Balancing

Scaling and load balancing come into play when one machine is not capable of managing all the required resources. Too many concurrent connections or virtualized application that handle a lot of graphics, sound or other elements that require a great availability of resources may cause an overload.

Thinfinity VirtualUI provides components that allow you to distribute the workload across multiple Windows sessions, as well as multiple servers. You can scale the application availability in terms of applications instances —and user accesses— and failover scenarios in order to achieve optimal resource utilization and avoid overload.

Some of the benefits of load balancing:

· Avoids the overload by distributing the connections among different servers

· Minimizes response time

· More reliability (redundancy)

· Failover control

Read more:

Scaling and Load Balancing Configurations

If you arrive to the conclusion that your Thinfinity VirtualUI environment would benefit from using Load Balancing, you can choose between different scenarios. This decision is an essential step in planning the hardware scheme and configuring the system to work in a distributed way.

Scenario 1: Multiple RDS accounts

This architecture involves only one computer. Each RDS session creates a Server instance which can, in turn, handle application instances separately. The VirtualUI Broker administrates the server instances: checks up on them to see if they are functional, and works together with the Gateway to distribute the connections.

Scenario 2: Multiple Servers with Load Balancing

In this simple scenario, a single Gateway distributes the connection load between a number of Servers.

Scenario 3: Multiple Gateways and Servers with Load Balancing

This example combines a external load balancing DNS Server with multiple Gateways. The scheme is composed by multiple Servers, multiple Gateways and the DNS Server, its domain name associated to all the available Gateways' IPs.

Scenario 4: Multiple RDS accounts and multiple Servers with Load Balancing

Combine load balancing with multiple RDS sessions to get the most out of your architecture.

Read more:

· Installing Components

· Configuring Load Balancing

Installing components

In this section you will learn how to set up Thinfinity VirtualUI's components in a load-balancing network configuration.

Choose the Load Balancing mode in the Server Installation Options screen:

Two or more servers will participate in the load balancing/fault-tolerance scenario. These are the two possible roles for an installation:

Reverse Gateway Role: Under this role, VirtualUI responds to all web-page requests and, when a connection is solicited, it selects the appropriate Brokerto forward that request to.

In case any established connection fails, or a Broker falls down, the Gateway will be able to reconnect to the Broker that has the highest availability at the moment.

All the system settings and profiles are centralized and shared between the Servers.

Before configuring a distributed environment, you should go over some steps:

Plan which machines will work under the Broker Role, and which under the Gateway Role and DNS Servers.
Make sure all the Gateway Roles IP addresses are public to the web browsers that will access Thinfinity VirtualUI.

Read more:

Enabling Multiple RDS Accounts

In order to enable multiple RDS accounts, go to the 'Sessions' tab and and select the "One Browser per Windows session: option:

One Browser per Session options

Options

Description

Allow running third-party applications

Check this option to enable Thinfinity VirtualUI to run directly under a Windows Interactive session.

Use these credentials

Check this option to enable Thinfinity VirtualUI to run under a specific Windows account.

User name

Enter the username for the Remote Desktop Services session you want Thinfinity VirtualUI to run applications under.

Password

Enter the password for the Remote Desktop Services session you want Thinfinity VirtualUI to run applications under.

Test

Test the credentials entered to verify that the username and password are correct and can access RDS.

Use VirtualUI's logged-in credentials

Check this option to enable Thinfinity VirtualUI to run under the logged in User's credentials.

The accounts must have administrator permissions or should have access to the following folders :

* FileSystem:

- C:\ProgramData\Cybele Software\Thinfinity\VirtualUI

- C:\Users\Public\Documents\Cybele Software\Thinfinity\VirtualUI

* RDP Access to the Machine is also required for the configured accounts to properly work.

Starting from 2.5.30.0, VirtualUI includes two different types of session handling modes. These options are only availble if you select the "Run under this account" option.

****

Note: In order to use this feature, Thinfinity VirtualUI must be installed in a Windows Server where the Remote Desktop Session Host (RD Session Host) role service is installed.

Read more:

· Scaling and Load Balancing

Configuring Load Balancing

In order to configure a load balancing scenario, you need at least one Gateway installation and two Server installations.

Configuring the Gateway Roles

Under this role, VirtualUI responds to all web-page requests and, when a connection is solicited, it selects the appropriate Server to forward that request to.

To configure the Gateway, open the Gateway Manager. Set the IP and port where the Gateway will run. If you only have one gateway, this is where the users will connect to. If you use more than one Gateway in your architecture, you will use this IP in the DNS server you set up to distribute the connection between the Gateways.

Also, set the Network ID. All the Gateway and Server installations involved in a Load Balancing architecture share the same network ID.

Configuring the Server Roles

Under this role, VirtualUI only processes forwarded connections. The Broker is responsible for establishing and processing the connections assigned by the Gateway.

To configure the Broker, open the Server Manager and go the 'Broker' tab. Press the 'Add' button to add a gateway to the Gateway List.

This means that now this server's resources can be accessed through the listed gateways.

· Make sure that the Network ID is the same for all the gateways and servers involved in this load balancing architecture.

Then, go to the 'Applications' tab:

Set the 'Database Path' field in a network location that you can access from the other Server role installations.

Once you share the database path, all the information in the 'Applications' tab will be shared with other VirtualUI installations. Make sure you modify the Applications information from one installation at a time, as all changes will be reflected in the other installations.

Also, make sure all the Gateways' IPs are public to the locations that will access Thinfinity VirtualUI through a web browser.

· Configuring the 'General' tab

· Configuring the 'Sessions' tab

· Configuring the 'Applications' tab

· Configuring the 'Licenses' tab

Sharing your License

Now that all your instances are working in Load Balancing , it's time to share your license over multiple servers.

The License Server Manager lets you register your licenses remotely, and you can use it to share your licenses over multiple servers across multiple installations .

Read more:

· Installing the License Server Manager

· Add a License

· Sharing your License over multiple Severs

Installing the License Server Manager

In order to install the License Server Manager, please , follow these steps :

1.Download the installer from this link:

http://www.cybelesoft.com/downloads

Execute the installer on the target machine.
The InstallShield Wizard will be displayed. Click on "Next".

Select "I accept the terms in the license agreement", and click on "Next".

Click on "Install".

Once the installation is complete, you will be given the option to start the License Server Manager .

Read more:

· Add a License

· Sharing your License over multiple Severs

Add a Licence

Pressing the 'Add' button and the appropriate product will open the Product Registration Wizard. In this case , we are going to chose "Thinfinity VirtualUI 2.5":

Select this option to receive a 30 day trial serial.

Select this option to register your Cybele Software, Inc product.

Select this option to register a license offline.

Get a new Trial Serial Number

This option will allow you to request a 30 day trial license with unlimited access. You will be prompt to enter a valid name and e-mail address.

Once you filled this information hit 'Next' and check your in-box for the serial key.

Read more:

· Activate a Serial Number Online

· Activate a Serial Number Offline

****

Activate a Serial Number Online

This is how the "Activate a Serial Number Online" windows looks:

E-mail

Enter the e-mail address you've registered with.

Serial

Enter the serial information we provided you.

Licensing Server URL

If you installed the License Server administrator, enter the License Server URL. Otherwise leave this blank.

If the license information is incorrect, you will see this warning: "The license information is invalid". In this case, please verify the following:

That you are entering the exact email and Serial number sent to you. The best practice to do this correctly is to copy - paste it, being careful not to include any space after or before.
That you have a working internet connection. If you intend to install it in a machine with no internet connection, you can try the Offline activation. If you have internet restrictions because of a proxy, please verify the license server manager has the proxy's information configured in the Communications tab.

If you need additional help, contact us.

If the license information is correct, the License Manager will let you know that "The new license has been installed successfully" and its information will be show in the License Manager.

Read more:

· Get a new Trial Serial Number

· Activate a Serial Number Offline

****

Activate a Serial Number Offline

Manual Activation is an activation option only for those cases when you want to activate your product in a machine that has no internet connection, or an internet connection restricted by heavy security policies that block a regular activation.

· If you haven't tried a regular activation, follow these instructions: Activate a Serial Number Online.

· If your internet restrictions are caused by a proxy, you will need to add the proxy information in the Communications tab

Before you continue with the steps to perform a manual activation, please contact us.

Once you've selected Activate a Serial Number Offline. You will see the following pop up:

Serial

Enter the license Serial number to generate the manual activation key

Generate Manual Key

After you have entered the serial number, press this button to generate the Manual Activation Key.

Manual Activation Key

Manual License

The support team will reply with the Manual License, a code that you will enter in the field above.

Press this button once you have performed the previous steps to complete your license activation.

Read more:

· Get a new Trial Serial Number

· Activate a Serial Number Online

Sharing your License over multiple Severs

Now that we have added a license to the License Server Manager, we need to bind that License to all the Brokers that are Load Balanced.

· In order to do this, you need to open the Thinfinity VirtualUI Server manager, navigate to the "Licenses" tab , and click on the "Manage" button.

· Click on the "Add" button :

· Select "Activate a Serial Number online" and press "Next" :

· Type in your license information ( E-mail + Serial ) , and add the License Server URL and Port number in the "Licensing Server URL" field :

· If the License Server is available and has that Serial number registered, then the license will be registered successfully :

· Repeat the proccess for all the Brokers you want to share the same license.

Read more:

· Installing the License Server Manager

· Add a License

Enhanced Browser and DPI Support

Among the wide range of valid resolutions that Thinfinity VirtualUI offers, the most commonly used —for its flexibility and simplicity— is “Fit to Browser”. This configuration allows you to adjust the remote application to fit the available browser size. However, when it comes to accessing a desktop from different devices, the sometimes huge differences between screen sizes and pixel resolutions (i.e. iPhone 4 vs a 27 inch iMac Retina Display) make it impossible to have a simple rule to determine the best remote desktop size. Even when the application is adjusting properly to the available size, the screen rendered might still look tiny or disproportionate, making the user experience not as satisfactory as expected.

Tailoring "Fit to Browser"

Now, using a new configurable browser detection ruleset, we can tailor the way we want to see of the remote desktop/application on every device. This ruleset allows you to specify rules that will detect the web browser, device and display characteristics, and set parameters that adjust the remote desktop/application resolution according to your own taste.

The main characteristics that need to be taken into account are:

· The browser User Agent, that tells about the web browser and device

· The device pixel ratio, that tells about the real display resolution

· The device display size

· The display orientation (landscape or portrait)

The browser detection ruleset is stored in a file with entries that contain specifications (rules) that match general or specific devices. Each entry (model) can inherit matching parameters (properties) from a more general model. For example, you can define an iOS model and an iPhone4 can inherit the iOS model properties.

A default ruleset file named BrowserRules.ini is installed in the Thinfinity VirtualUI program folder. Then, if it doesn’t exist there yet, it is copied to "\programData\Cybele Software\Thinfinity\VirtualUI\" and renamed as Thinfinity.VirtualUI.BrowserRules.ini. You can safely customize this file as it won’t be overridden with a program update.

The structure of this file is as follow:

[default]
min-width = 640
min-height = 480
max-width = 2560
max-height = 1600
max-device-pixel-ratio = 1
[mobile]
parent-model = default
match-mobile = true
max-device-pixel-ratio = 2

Note: for these settings to apply, the connection’s ‘Resolution’ property must be set to ‘Fit to browser’, and the BrowserRules.ini file must be pointed in the application profile.

Configure this setting in for your application in the 'General' tab of the Application Profile, or the 'General' tab of the Application Profile in the development server.

Read more:

· Model Inheritance

· Property Reference

· The Calculation Process

Model Inheritance

A section defines a model, and each model contains a set of properties divided in two groups: matching properties and applying properties.

Models are organized in an inheritance tree. The relationship between models is defined by a special property rule called parent-model, present in all models except in the [default] model, which is the tree's root node and includes some basic properties.

Every other model must directly or indirectly inherit from the [default] model. Also, each model contains its own rules that match general or specific devices, and inherits all specifications (including matching parameters) from its ancestors.

When more than one criteria is met for a device, a scoring system is used to resolve this conflict.

This is the in-the-box models tree:

Read more:

· Property Reference

· The Calculation Process

Property Reference

Properties can be divided in two groups: matching properties and applying properties.

Matching properties are those used to test the browser and device properties (such as the browser user agent, the device pixel ratio, the display orientation width and height, etc.) in order to choose the best model for each case.

match-device-pixel-ratio

Matches any device with a specific pixel ratio.

match-mobile

Matches any mobile device.

match-orientation

Matches any device with the specified orientation: landscape or portrait.

match-screen-height-range

Matches any device with a screen height in the specified range. This range is expressed as From-To (for example, 900-1200).

match-screen-width-range

Matches any device with a screen width in the specified range. This range is expressed as From-To (for example, 400-600).

match-screen-height

Matches any device with a specified screen height.

match-screen-width

Matches any device with a specified screen width.

match-user-agent

Matches devices by comparing the device browser user agent to the string value supplied. This string is a regular expression.

Applying properties are those used to determine the final size and resolution.

Use the parent-model property to set the parent model:

parent-model

Establish the parent model for this model.

The following properties deal with the display resolution:

device-pixel-ratio

Overrides the original device pixel ratio, scaling the content accordingly.

max-device-pixel-ratio

This property determines the maximum device pixel ratio accepted. The lesser of the device’s device pixel ratio and this value is applied to scale the display.

The following properties deal with the screen size of the remote desktop, in pixels. You can determine it by setting the actual height and width, or by establishing maximum and minimum values for these properties.

height

Remote desktop height.

width

Remote desktop width.

max-height

Remote desktop maximum height.

max-width

Remote desktop maximum width.

min-height

Remote desktop minimum height.

min-width

Remote desktop minimum width.

The following properties allow you to specify device screen areas that will never be used for displaying the remote connection, such as when a browser or device bar cannot be hidden and uses up screen space. These margins will be excluded for screen size calculations.

margin-left

Width of an area at the left of the device screen that will not be used for displaying the remote desktop.

margin-bottom

Width of an area at the bottom of the device screen that will not be used for displaying the connection.

margin-right

Width of an area at the right of the device screen that will not be used for displaying the connection.

margin-top

Width of an area at the top of the device screen that will not be used for displaying the connection.

Miscellaneous properties:

use-full-screen

For mobile only. If the device’s browser supports the full-screen mode, this property indicates the remote desktop size should be calculated to occupy the whole screen. When not in full screen, the content will be scaled.

Read more:

· The Calculation Process

The Calculation Process

In order to choose a model from the ruleset, Thinfinity uses the client device type, dimensions, resolution, orientation and browser:

If match-mobile exists, it tests if device is a mobile.
If match-user-agent exists, it tests the browser’s User Agent.
If match-device-pixel-ratio exists, it tests the device’s pixel ratio.
If match-orientation exists, it tests the device’s orientation.
If match-screen-width-range or match-screen-height-range exist, it tests to see if the screen size is in range.
If match-screen-width or match-screen-height exist, it tests the exact screen size.

Once the model is selected, the parameters are applied in this way:

If the width and height properties exist, then it applies them.
If the browser width is less than the min-width, it applies min-width.
If the browser height is less than the min-height, it applies min-height.
If the browser width is greater than the max-width, it applies max-width.
If the browser height is greater than the max-height, it applies max-height.
If a specific device-pixel-ratio was specified, it applies it.
If a max-device-ratio was specified, it takes the minimum of the real device pixel ratio and max-device-ratio property and applies it.

Read more:

· Sending Command Line Arguments in the VirtualUI URL

Examples

This example shows a possible ruleset and how it will affect different devices:

[default]
min-width = 640
min-height = 480
max-width = 2560
max-height = 1600
max-device-pixel-ratio = 1
[mobile]
parent-model = default
match-mobile = true
max-device-pixel-ratio = 2
[ipad]
parent-model = mobile
match-user-agent = ipad
[iphone4]
parent-model = mobile
match-user-agent = iphone
match-screen-width = 480
match-screen-height = 320
device-pixel-ratio = 1.5

In this case, when connecting with an ipad, the following models will be matched:

[default]: This model applies to all devices.

[mobile]: The ipad will match the match-mobile property.

[ipad]: The ipad will match the user agent keyword ‘ipad’ specified in the match-user-agent property.

The resulting properties for this device will be:

min-width = 640
min-height = 480
max-width = 2560
max-height = 1600
max-device-pixel-ratio = 2

Using the same ruleset, when connecting with an iphone4, the following models will be matched:

[default]: This model applies to all devices.

[mobile]: The iphone will match the match-mobile property.

[iphone4]: The ipad will match the user agent keyword ‘iphone’ specified in the match-user-agent property, together with the match-screen-width and match-screen-height properties. An iphone6, with a screen width of 667px, and a screen height of 375px, would match the ‘iphone’ user agent keyword, but not the size.

The resulting properties for this device will be:

min-width = 640
min-height = 480
max-width = 2560
max-height = 1600
max-device-pixel-ratio = 2
device-pixel-ratio = 1.5

One-Time URL

Thinfinity VirtualUI offers a special access method called “One-Time URL”. This mechanism was designed to create a temporary, unique url to provide one-time access to a specific application. This temporary url is disposed as soon as it is used or after a specified period of time has elapsed.

These are the main scenarios where the One-Time URL access method is most useful:

· External authentication methods.

· One-time invitations to run a program (i.e. application demos/presentations).

Read more:

· How it Works

· Creating a One-Time URL

How it Works

The One-Time URL is a unique, disposable URL leading to a specific VirtualUI application. What makes it useful is that it allows for passing credentials and/or custom data to the application through an independent secure channel, hidden to the end user.

A usual scenario involves a backend service (ie. a web server), where the user’s credentials are validated. This backend service communicates with a VirtualUI Server to request the creation of a One-Time URL, passing information about the application to run, credentials and custom data. This information is stored temporarily and indexed by a unique access key. Also a random passcode is created and used to encrypt the stored information. This access key and passcode are returned to the backend service to build the final One-Time URL.

Once the user is directed to the provided URL (automatically or by clicking on a link), VirtualUI validates the access key and passcode and starts the application passing the associated data. Finally, this key and associated data are removed from memory and therefore the URL becomes invalid. The same happens if the URL was not used for the amount of time specified in the creation request.

Read more:

· Creating a One-Time URL

Creating a One-Time URL

The VirtualUI Server processes a One-Time URL creation request in the form of an http(s) request, as follows:

serverurl + "/ws/oturl/get?apikey=" + apikey + "&accesskey=" + accesskey +

"&virtualpath=" + virtualpath

"&userid=" + userid + "&password=" + password +

"&customdata=" + customData +

"&plen=" + passlen + "&expires=" + expires

"&arguments=" + arguments ,

where:

serverurl

optional

VirtualUI Server address (protocol, domain and port)

apikey

required

VirtualUI installation [API] key. Find this information in Thinfinity.VirtualUI.Server.ini at C:\ProgramData\Cybele Software\Thinfinity\VirtualUI

accesskey

required if not using virtualpath

Identifies the application that will be run. Complete this parameter with the 'access key' parameter found in the application’s profile in the VirtualUI Server Manager.

virtualpath

required if not using accesskey

Uses the VirtualPath of the application, configured in the application profile editor.

userid

optional

A valid user that meets the criteria set in the application profile’s 'Permission' tab.

password

optional

The password of the user specified in the 'userid' parameter.

customdata

optional

Use this field to send any information you may need to make available to the application. This is the right place to pass sign-on credentials. This information will be accessible in the application through the BrowserInfo.CustomData property.

plen

optional

Length of the passcode to be returned.

expires

optional

Ticket expiration time, in minutes.

arguments

optional

Arguments passed to the application.

Note: The user indicated in the 'userid' parameter is a user validated within VirtualUI to access the application. This is an Active Directory user that was either added individually, or as part of a group of users in the 'Permissions' tab of the profile that will be accessed. In a regular non-one-time-URL implementation, the end user would authenticate by providing these credentials. However, when using a one-time-URL, this information is used internally by the application and the user can be authenticated somehow else.

If the request is unsuccessful, the following HTTP codes can be received:

400: Invalid parameters

401: Userid/password invalid

If the request is successful, the HTTP call returns a 200 HTTP status code, and a JSON consisting of two fields:

{
 "key": "LnJwsxGHp5d@6MHeiEswRdfxFCiIcLAUttRS$9FSUs-Utz3o",
 "pass":"1U4KRLN0"
}

With this information, the backend can build the final URL, following this format:

http(s)://server-url/oturl.html?key=[accesskey]&pass=[passcode]

Here's an example that uses the JSON shown above:

http(s)://server-url/oturl.html?key=LnJwsxGHp5d@6MHeiEswRdfxFCiIcLAUttRS$9FSUs-Utz3o&pass=1U4KRLN0

Passing Command Line Arguments to VirtualUI Apps

An application can accept command line arguments when invoked. This allows the user to send additional information to the application when it is executed.

When an application is launched, the OS passes the command line arguments to the application as a collection of string values, using a white-space as separator.

Applications receive external arguments on a regular basis: when you open a document by clicking on its icon, the OS selects the associated executable program and calls it, sending the full document filename to the program as an argument.

Thinfinity VirtualUI allows you to send external arguments to applications in a transparent way, which works exactly like sending arguments from the command line.

· Combining Application Profile and URL Command Line Arguments

Setting Command Line Arguments in the Application Profile

bt - current position

Thinfinity VirtualUI enables external argument definition from the VirtualUI Server Manager. When you create an application profile, you can specify the execution arguments in the General tab panel of the Application Profiles editor.

These arguments will be received by the application as a list of string values, using the white-space character as argument delimiter.

In Delphi you can get command line arguments using the System.ParamCount and System.ParamStr methods. ParamCount returns the number of arguments, and ParamStr(index) returns each argument, with ParamStr(0) always being the path and name of the invoked program. Here is a way you can show the received arguments list:

Writeln(Format('Arguments = %d', [ParamCount]))
 for p := 1 to ParamCount do
 Writeln(Format('argument %d = "%s"', [p, ParamStr(p)]);

In C++, both the argument counter and the argument list will be received in the two main() function arguments. Like in Delphi, the first argument in the string array is the path and name of the program itself:

void main(int argCounter, char* arguments[]) {
 cout << "Arguments = " << argCounter << endl;
 for(int i = 1; i < argCounter; i++)
 cout << "arguments[" << i << "] = " << arguments[i] << endl;
}

You can also write the main function header in this way:

void main(int argCounter, char** arguments) { ... }

Unlike Delphi and C++, C# excludes the name and path of the program from the arguments collection. Also, C# offers two ways to get the arguments, by using a traditional for:

public static void Main(string[] arguments)
{
 Console.WriteLine("Arguments = {0}", args.Length);
 for(int i = 0; i < arguments.Length; i++)
 {
 Console.WriteLine("Arguments[{0}] = [{1}]", i, arguments[i]);
 }
}

or by using the foreach:

foreach(string s in arguments)
{
 Console.WriteLine(s);
}

· Combining Application Profile and URL Command Line Arguments

Sending Command Line Arguments in the VirtualUI URL

VirtualUI allows you to send external arguments in the url. Instead of passing static arguments from the application profile definition, using this feature you can send dynamic application arguments in a simple way. The only requirement to be met is that the arguments must be url encoded.

To build the url you need:

· The communication protocol (http or https).

· The Thinfinity VirtualUI server domain or IP address, and port.

· The application virtual path.

Build the url like this:

protocol://server.address:port/virtualpath/?arguments

As an example, we will send the "one", "two" and "three" argument values to the TestArguments program:

http://192.168.0.229:6580/TestArguments/?one%20two%20three

The following image shows the submit result:

· Combining Application Profile and URL Command Line Arguments

Building the URL in Javascript

When necessary, modern browsers encode URLs automatically, but it is convenient to do it by code. The Javascript lines below show how to build the URL used in the previous example:

var buildURL = function(server, virtualpath, arguments) {

return server + "/" + virtualpath + "/" + encodeURIComponent(arguments.join(' '));

}

var baseURL = "http://192.168.0.229:6580/";

var applicationPath = "TestArguments";

var arguments = ["one", "two", "three"];

var url = buildURL(baseURL, applicationPath, arguments);

· Sending Command Line Arguments in the VirtualUI URL

· Combining Application Profile and URL Command Line Arguments

Combining Application Profile and URL Command Line Arguments

If you have defined command line arguments in the application profile and need to send new arguments to the application by url, don't worry. Thinfinity VirtualUI merges both argument lists, first adding the application profile arguments, and then the arguments that were passed in the url.

· Sending Command Line Arguments in the VirtualUI URL

· The OnRecorderChanged Event

Recording and Playing Sessions

Thinfinity® VirtualUI introduces this feature to help users have a record of their own VirtualUI web-enabled applications' sessions.

In order to enable your application to store sessions of a running VirtualUI-enabled application and then play them, VirtualUI includes a new Recorder component, available for all the supported programming languages. Later, you can play this session from the browser using a special VirtualUI application profile, or you could also implement your own custom session player using the SDK in any of the supported languages.

Read more:

· Recording a Session

· Playing Recorded Sessions

· Creating your Own Player

Recording a Session

Set the record filename to the VirtualUI.Recorder component and call its Rec() method to record an application session. The VirtualUI.Recorder object is used in both the recording and the playing process. These operations can be presented, for example, as two buttons in the application: "Rec" and "Stop".

In order to record a session, follow these steps:

Choose a file name and location for storing the session. Don't include the extension: sessions will be stored automatically as .dat and .idx.

Set the Filename as follows:

Delphi code:

VirtualUI.Recorder.Filename := 'C:\Sessions\VirtualUISession';

C++ code:

VirtualUI m_VirtualUI = new VirtualUI();

...

m_VirtualUI->Recorder()->Filename(L"C:\Sessions\VirtualUISession");

C# code:

private VirtualUI vui = new VirtualUI();

...

vui.Recorder.Filename = "C:\Sessions\VirtualUISession";

You can specify more than one track for each session. This allows you to, for example, store different application operations. Later, you can play play the complete session or a specific track. These tracks are indicated during the sessions recording. Call the Rec() method and pass the track name as an argument in the Label parameter:

Delphi code:

VirtualUI.Recorder.Rec('Track 1');

C++ code:

m_VirtualUI->Recorder()->Rec(L"Track 1");

C# code:

vui.Recorder.Rec(“Track 1”);

In order to stop the recording, call the Stop method:

Delphi code:

VirtualUI.Recorder.Stop('Track 1');

C++ code:

m_VirtualUI->Recorder()->Stop();

C# code:

Afterwards, you can start another recording with the Rec method. If you keep the same track name, the recording will resume and the session will be stored after the previous session in the same file, in a new track. Change the track name to avoid ending up with two tracks with the same name in the same session recording.

Read more:

· The OnRecorderChanged Event

· Play Recorded Sessions

· Create Your Own Player

The OnRecorderChanged Event

Use the VirtualUI OnRecorderChanged event to listen for any change in the Recorder status.

These are the possible status values:

State

It reports the Recorder state:

The following examples shows how to assign an event handler to this event in the most used languages:

Delphi code:

procedure TMainForm.RecorderChanged(Sender: TObject);

var msg: string;

begin

msg := '';

case VirtualUI.Recorder.State of

Inactive: msg := 'Recorder is inactive';

Playing: msg := 'Recorder is Playing';

Recording: msg := 'Recording session';

end;

ShowMessage(msg);

end;

...

VirtualUI.OnRecorderChanged := Mainform.RecorderChanged;

C++ code:

m_VirtualUI->OnRecorderChanged = RecorderChanged;

void RecorderChanged(void) {

CString stateStr;

switch (m_VirtualUI->Recorder()->State()) {

case Inactive: stateStr = _T("Recorder is inactive"); break;

case Playing: stateStr = _T("Recorder is Playing"); break;

case Recording: stateStr = _T("Recording session"); break;

}

MessageBox(0, stateStr, L"OnRecorderChanged called", 0);

}

C# code:

private void RecorderChanged(object sender, RecorderChangedArgs e)

{

string message = "";

switch (vui.Recorder.State) {

case RecorderState.Inactive:

message = "Recorder is inactive";

break;

case RecorderState.Playing:

message = "Recorder is playing";

break;

case RecorderState.Recording:

message = "Recording session";

break;

}

MessageBox.Show(message, "OnRecorderChanged called");

}

...

vui.OnRecorderChanged += RecorderChanged;

Read more:

· Recording a Session

· Playing Recorded Sessions

· Creating Your Own Player

Recover Browser Information with BrowserInfo

When using VirtualUI, it is often necessary to be aware of some features and capabilities of the device from which end users are accessing our application.

The VirtualUI class has a property called BrowserInfo, which contains data about the browser being used. This information can assist us in delivering the best possible user experience.

In the list below we will find a detailed reference of the information that BrowserInfo will deliver:

Information relative to the available screen space:

The following C# example shows how to center a window of our application on this virtual desktop as needed, previously controlling its size if it exceeds the available space:

using Cybele.Thinfinity;...

...

private VirtualUI vui;

public Form1()

{

InitializeComponent();

vui = new VirtualUI();}

private void CenterThisWindow(object sender, EventArgs e)

{

this.WindowState = FormWindowState.Normal;

if (vui.BrowserInfo.ViewHeight < (this.Height + 20)) {

this.Height = vui.BrowserInfo.ViewHeight - 20;

}

if (vui.BrowserInfo.ViewWidth < (this.Width + 20))

{

this.Width = vui.BrowserInfo.ViewWidth - 20;

}

this.Top = (vui.BrowserInfo.ViewHeight - this.Height) / 2;

this.Left = (vui.BrowserInfo.ViewWidth - this.Width) / 2;

}

Change Browser Behavior Using ClientSettings

The table below shows a detailed reference of the ClientSettings interface current properties:

As mentioned previously, these properties were created to provide a better end-user experience when using touch devices.

The properties that we have presented above will help us define the ideal settings to enjoy the best possible and intuitive user experience for our application.

The following example shows how to recognize a touch or mobile device, and to change the pointer behavior when it's detected. Warning: The detection list is not complete:

vui = new VirtualUI();

userAgent = vui.BrowserInfo.UserAgent.ToLower();

if ((userAgent.IndexOf("touch") != -1) || (userAgent.IndexOf("mobile") != -1) ||

(userAgent.IndexOf("iphone") != -1) || (userAgent.IndexOf("ipod") != -1) ||

(userAgent.IndexOf("ipad") != -1) || (userAgent.IndexOf("android") != -1) ||

(userAgent.IndexOf(" cros ") != -1)) {

vui.ClientSettings.MouseMoveGestureStyle = MouseMoveGestureStyle.MM_STYLE_ABSOLUTE;

vui.ClientSettings.MouseMoveGestureAction = MouseMoveGestureAction.MM_ACTION_WHEEL;

}

End-User Authentication

Read the following sections to learn how to implement the available authentication methods in VirtualUI web-enabled applications.

Read more:

Entering Credentials

Thinfinity VirtualUI allows you to enable one or more authentication methods at a time. There are two possible ways to ask for credentials:

· Using the standard Web Browser authentication dialog

· Showing a log-in page

For example, if only the 'Windows Logon' method is configured, the page will look like this:

But if you enable all predefined methods, your login will show something like this:

Read more:

Processing End-user Credentials

Each published application without anonymous access requires the assignment of one or more Active Directory objects which define the users that can see and execute it.

Thinfinity VirtualUI implements a mapping mechanism to transform end-user credentials to AD objects. Only applications that match these AD objects will be granted access to the end-user.

Read more:

Authentication Methods

Thinfinity VirtualUI allows you to use the following authentication methods.

Windows Logon

This option enables Active Directory credentials. This method is enabled by default.

RADIUS

OAuth 2.0

External DLL

A custom authentication method implemented by you or a third party with our authentication API and referenced in the Thinfinity VirtualUI server.

Anonymous Authentication

All these methods will be enabled and configured in the Thinfinity VirtualUI Server Manager: choose the methods in the 'Authentication' tab and configure the mapping in the 'Mappings' subtab.

Read more:

· RADIUS

Windows Logon

Windows Logon means that the end-user will have to enter Windows Activate Directory credentials in order to gain access to a set of applications defined in Thinfinity VirtualUI.

Windows Logon is enabled by default in the 'Authentication' tab of the Thinfinity VirtualUI Server Manager. Toggle its availability as an authentication method by checking or unchecking it.

Read more:

· RADIUS

RADIUS

RADIUS as an authentication method means that the user will have to enter their RADIUS credentials in order to gain access to a set of applications defined in Thinfinity VirtualUI.

RADIUS can be added in the 'Authentication' tab of the Thinfinity VirtualUI Server Manager. Toggle its availability as an authentication method by checking or unchecking it.

When you add RADIUS as an authentication method you will be required to provide the RADIUS account relevant information.

Read more:

OAuth 2.0

Read more:

· CSS for SSO options

****

OAuth2Models.ini

OAuth2Models.ini is a file is distributed with the Thinfinity VirtualUI installation that has all the information of the default available logins:

[Google]

ClientID =

ClientSecret =

AuthorizationParameters = scope=https://www.googleapis.com/auth/userinfo.email&approval_prompt=auto

AuthorizationURL = https://accounts.google.com/o/oauth2/auth

TokenValidationURL = https://accounts.google.com/o/oauth2/token

ProfileValidationURL = https://www.googleapis.com/oauth2/v1/userinfo

UsernameField = email

[Facebook]

ClientID =

ClientSecret =

AuthorizationParameters = scope=email

AuthorizationURL = https://www.facebook.com/dialog/oauth

TokenValidationURL = https://graph.facebook.com/oauth/access_token

ProfileValidationURL = https://graph.facebook.com/me?

UsernameField = email

[LinkedIn]

ClientID =

ClientSecret =

AuthorizationURL = https://www.linkedin.com/uas/oauth2/authorization

AuthorizationParameters = state=HIJK98sDT88jnS23S&scope=r_emailaddress

TokenValidationURL = https://www.linkedin.com/uas/oauth2/accessToken

ProfileValidationURL = https://api.linkedin.com/v1/people/~:(emailAddress)?format=json

UsernameField = emailAddress

[Dropbox]

ClientID =

ClientSecret =

AuthorizationURL = https://www.dropbox.com/1/oauth2/authorize

AuthorizationParameters =

TokenValidationURL = https://api.dropboxapi.com/1/oauth2/token

ProfileValidationURL = https://api.dropboxapi.com/1/account/info

UsernameField = email

Use this file as a template and edit it in order to add new authentication methods or ask your authentication provider for different data.

Read more:

****

CSS for SSO Options

In the login.css file, included in the 'web\css' folder of the Thinfinity VirtualUI installation, you will find the style for the login buttons.

#google { background-color:#4285F4; }

#google .imgbtn { background-image: url(../images/sso/google.png); }

#facebook { background-color:#2f4e9e; }

#facebook .imgbtn { background-image: url(../images/sso/facebook.png); }

#yahoo { background-color:#6839af; }

#yahoo .imgbtn { background-image: url(../images/sso/yahoo.png); background-size: 30px; }

#linkedin { background-color:#00A0DC; }

#linkedin .imgbtn { background-image: url(../images/sso/linkedin.png); }

#dropbox { background-color:#007ee6; }

#dropbox .imgbtn { background-image: url(../images/sso/dropbox.png); background-size: 30px; }

You can change the logo and/or background color of the login buttons for the Oauth 2.0 authentication methods.

The first line of each pair defines the button color, and the second one the button image.

External DLL

Thinfinity VirtualUI allows you to integrate your own custom authentication method. In order to do this, use the Thinfinity VirtualUI Authentication API.

The user definition is completed through the mapping between the user ID returned by the external DLL and an Active Directory Objects mapped for this Authentication ID Mask.

Read more:

· Enhanced Browser and DPI Support

****

File System Virtualization

The file system mapping definition is a set of one to one redirection rules that link a real folder to the redirected folder path.

There are two types of redirection:

· Shared: for all connected users. It can be defined as readonly.

· Private: for a single identified user.

The configuration is done through the The File System Virtualization Editor, which will be installed with the Standard or server component installation.

Read more:

Creating File System Redirections

In order to add a path in the Virtualization Editor, right click on the main area of the screen and choose 'New Path...'.

This will bring up the 'Edit Directory' dialog.

Paths can also be expressed using the environment variables defined in Windows:

%public%, %home%, %documents%, etc

For example, you can redirect %userprofile% to %userprofile%\users as a private redirection; "user1"’s files will therefore be stored in c:\users\username\users*user1*

Or you can map c:\temp to %userprofiles%\temp as a shared redirection.

Editing Paths

In order to edit a path, right click on it and choose 'Edit Path'.

You will then be able to edit the path in the 'Edit Directory' dialog.

Deleting Paths

In order to delete a path, right click on it and choose 'Delete Path'.

Read more:

The .vdir Files

Once you are done adding, editing and/or deleting paths, save this configuration by selecting 'File' - 'Save' in the main menu of the Filesystem Virtualization Editor.

This configuration will be stored in a vdir file. The Filesystem Virtualization Editor allows you to create different vdir files to be used in your application.

Read more:

Testing the File System Virtualization

Read more:

Advanced Features

Take a look at the Thinfinity VirtualUI advanced features:

· End-User Authentication

· One-Time URL

· Passing Command Line Arguments to VirtualUI Apps

· Recording and Playing Sessions

· Scaling and Load Balancing

· Printing

· Virtualization

· OEM Licensing

5.6. Recover Browser Information with BrowserInfo

When using VirtualUI, it is often necessary to be aware of some features and capabilities of the device from which end users are accessing our application.

The VirtualUI class has a property called BrowserInfo, which contains data about the browser being used. This information can assist us in delivering the best possible user experience.

In the list below we will find a detailed reference of the information that BrowserInfo will deliver:

Attribute

Description

Username

Returns the logged-on username.

IPAddress

Returns the client's ip address.

Location

Returns the URL of the current application.

UniqueBrowserId

Identifies an instance of a browser. Each time an end-user opens the application from a different browser window, this identifier will be have a different value.

UserAgent

Returns the browser's User Agent string. This value is very important to identify which browser type is used, if the remote device is a mobile, etc.

Information relative to the available screen space:

Attribute

Description

BrowserWidth

Returns the width of the HTML element containing the VirtualUI viewer, in pixels.

BrowserHeigth

Returns the height of the HTML element containing the VirtualUI viewer, in pixels.

ScreenWidth

Returns the width of the end-user's device screen, in pixels.

ScreenHeight

Returns the height of the end-user's device screen, in pixels.

ScreenResolution

Returns the application screen resolution defined in the application profile.

ViewWidth

Returns the width of the VirtualUI viewer, in pixels.

ViewHeight

Returns the height of the VirtualUI viewer, in pixels.

Orientation

Returns the browser's orientation.

The following C# example shows how to center a window of our application on this virtual desktop as needed, previously controlling its size if it exceeds the available space:

using Cybele.Thinfinity;...

...

private VirtualUI vui;

public Form1()

{

InitializeComponent();

vui = new VirtualUI();}

private void CenterThisWindow(object sender, EventArgs e)

{

this.WindowState = FormWindowState.Normal;

if (vui.BrowserInfo.ViewHeight < (this.Height + 20)) {

this.Height = vui.BrowserInfo.ViewHeight - 20;

}

if (vui.BrowserInfo.ViewWidth < (this.Width + 20))

{

this.Width = vui.BrowserInfo.ViewWidth - 20;

}

this.Top = (vui.BrowserInfo.ViewHeight - this.Height) / 2;

this.Left = (vui.BrowserInfo.ViewWidth - this.Width) / 2;

}

5.7. Change Browser Behavior Using ClientSettings

There is also a Javascript Clientsettings object version. Learn how to use it.

The table below shows a detailed reference of the ClientSettings interface current properties:

Property

Use

CursorVisible

Used to set the mouse pointer to 'show' or 'hide'.

Type: Boolean

Default value: True

Available in all Library Versions.

MouseMoveGestureStyle

Defines whether the mouse movement is read as relative or absolute in touch devices.

Type: Enum

Values:

MM_STYLE_RELATIVE = 0

MM_STYLE_ABSOLUTE = 1

Default value: MM_STYLE_RELATIVE

Available in all Library Versions.

MouseMoveGestureAction

Indicates if the dragging should be interpreted as scrolling or turning of the mouse wheel, affecting only the component on which the action is triggered.

Type: Enum

Values:

MM_ACTION_MOVE = 0,

MM_ACTION_WHEEL = 1

Default value: MM_ACTION_MOVE

Available in all Library Versions.

UseViewportSize

Indicates which measure values will be used to define the application's screen size.

Type: Boolean

Values:

True: use the viewport size

False: use a window screen based size.

Default value: False

Available only in Javascript.

DockMenu

Manages the visibility of the bottom menu and its options.

Available only in Javascript

Enabled

Boolean. Enables/disables the complete Dock Menu.

Type: Boolean

Default value: True

Pinned

Indicates when the DockMenu is pinned (visible, fixed) or unpinned (with autohide)

Type: Boolean

Default value: False

Items

Name/value pairs item collection.

WindowList

Enables/disables the "Windows list" option.

Type: Boolean

Default value: True

ErrorReporting

Enables/disables the "Error Reporting" option.

Type: Boolean

Default value: True

Keyboard

Enables/disables the "Keyboard" option (mobile only).

Type: Boolean

Default value: True

FullScreen

Enables/disables the "Full Screen" option (mobile only, if supported).

Type: Boolean

Default value: True

As mentioned previously, these properties were created to provide a better end-user experience when using touch devices.

The properties that we have presented above will help us define the ideal settings to enjoy the best possible and intuitive user experience for our application.

The following example shows how to recognize a touch or mobile device, and to change the pointer behavior when it's detected. Warning: The detection list is not complete:

vui = new VirtualUI();

userAgent = vui.BrowserInfo.UserAgent.ToLower();

if ((userAgent.IndexOf("touch") != -1) || (userAgent.IndexOf("mobile") != -1) ||

(userAgent.IndexOf("iphone") != -1) || (userAgent.IndexOf("ipod") != -1) ||

(userAgent.IndexOf("ipad") != -1) || (userAgent.IndexOf("android") != -1) ||

(userAgent.IndexOf(" cros ") != -1)) {

vui.ClientSettings.MouseMoveGestureStyle = MouseMoveGestureStyle.MM_STYLE_ABSOLUTE;

vui.ClientSettings.MouseMoveGestureAction = MouseMoveGestureAction.MM_ACTION_WHEEL;

}

Read more about using ClientSettings from Javascript.

5.8. End-User Authentication

Read the following sections to learn how to implement the available authentication methods in VirtualUI web-enabled applications.

Read more:

5.8.1. Entering Credentials

Thinfinity VirtualUI allows you to enable one or more authentication methods at a time. There are two possible ways to ask for credentials:

· Using the standard Web Browser authentication dialog

· Showing a log-in page

This dialog is available when you use only one of the authentication access methods that require user and password: Windows Logon, RADIUS or External DLL.

For example, if only the 'Windows Logon' method is configured, the page will look like this:

But if you enable all predefined methods, your login will show something like this:

You can modify this page to adapt it to your branding and/or integration needs. Check out the login.html section to learn how.

Read more:

· login.html

5.8.2. Processing End-user Credentials

Each published application without anonymous access requires the assignment of one or more Active Directory objects which define the users that can see and execute it.

Thinfinity VirtualUI implements a mapping mechanism to transform end-user credentials to AD objects. Only applications that match these AD objects will be granted access to the end-user.

Read more:

5.8.3. Authentication Methods

Thinfinity VirtualUI allows you to use the following authentication methods.

Windows Logon

This option enables Active Directory credentials. This method is enabled by default.

RADIUS

OAuth 2.0

External DLL

A custom authentication method implemented by you or a third party with our authentication API and referenced in the Thinfinity VirtualUI server.

Anonymous Authentication

All these methods will be enabled and configured in the Thinfinity VirtualUI Server Manager: choose the methods in the 'Authentication' tab and configure the mapping in the 'Mappings' subtab.

Read more:

· RADIUS

5.8.3.1. Windows Logon

Windows Logon means that the end-user will have to enter Windows Activate Directory credentials in order to gain access to a set of applications defined in Thinfinity VirtualUI.

Windows Logon is enabled by default in the 'Authentication' tab of the Thinfinity VirtualUI Server Manager. Toggle its availability as an authentication method by checking or unchecking it.

Read more:

· RADIUS

5.8.3.2. RADIUS

RADIUS as an authentication method means that the user will have to enter their RADIUS credentials in order to gain access to a set of applications defined in Thinfinity VirtualUI.

RADIUS can be added in the 'Authentication' tab of the Thinfinity VirtualUI Server Manager. Toggle its availability as an authentication method by checking or unchecking it.

When you add RADIUS as an authentication method you will be required to provide the RADIUS account relevant information.

Read more:

5.8.3.3. OAuth 2.0

Read more:

· CSS for SSO options

5.8.3.3.1. OAuth2Models.ini

OAuth2Models.ini is a file is distributed with the Thinfinity VirtualUI installation that has all the information of the default available logins:

[Google]

ClientID =

ClientSecret =

AuthorizationParameters = scope=https://www.googleapis.com/auth/userinfo.email&approval_prompt=auto

AuthorizationURL = https://accounts.google.com/o/oauth2/auth

TokenValidationURL = https://accounts.google.com/o/oauth2/token

ProfileValidationURL = https://www.googleapis.com/oauth2/v1/userinfo

UsernameField = email

[Facebook]

ClientID =

ClientSecret =

AuthorizationParameters = scope=email

AuthorizationURL = https://www.facebook.com/dialog/oauth

TokenValidationURL = https://graph.facebook.com/oauth/access_token

ProfileValidationURL = https://graph.facebook.com/me?

UsernameField = email

[LinkedIn]

ClientID =

ClientSecret =

AuthorizationURL = https://www.linkedin.com/uas/oauth2/authorization

AuthorizationParameters = state=HIJK98sDT88jnS23S&scope=r_emailaddress

TokenValidationURL = https://www.linkedin.com/uas/oauth2/accessToken

ProfileValidationURL = https://api.linkedin.com/v1/people/~:(emailAddress)?format=json

UsernameField = emailAddress

[Dropbox]

ClientID =

ClientSecret =

AuthorizationURL = https://www.dropbox.com/1/oauth2/authorize

AuthorizationParameters =

TokenValidationURL = https://api.dropboxapi.com/1/oauth2/token

ProfileValidationURL = https://api.dropboxapi.com/1/account/info

UsernameField = email

Use this file as a template and edit it in order to add new authentication methods or ask your authentication provider for different data.

Read more:

5.8.3.3.2. CSS for SSO Options

In the login.css file, included in the 'web\css' folder of the Thinfinity VirtualUI installation, you will find the style for the login buttons.

#google { background-color:#4285F4; }

#google .imgbtn { background-image: url(../images/sso/google.png); }

#facebook { background-color:#2f4e9e; }

#facebook .imgbtn { background-image: url(../images/sso/facebook.png); }

#yahoo { background-color:#6839af; }

#yahoo .imgbtn { background-image: url(../images/sso/yahoo.png); background-size: 30px; }

#linkedin { background-color:#00A0DC; }

#linkedin .imgbtn { background-image: url(../images/sso/linkedin.png); }

#dropbox { background-color:#007ee6; }

#dropbox .imgbtn { background-image: url(../images/sso/dropbox.png); background-size: 30px; }

You can change the logo and/or background color of the login buttons for the Oauth 2.0 authentication methods.

The first line of each pair defines the button color, and the second one the button image.

Read more:

· RADIUS

5.8.3.4. External DLL

Thinfinity VirtualUI allows you to integrate your own custom authentication method. In order to do this, use the Thinfinity VirtualUI Authentication API.

The user definition is completed through the mapping between the user ID returned by the external DLL and an Active Directory Objects mapped for this Authentication ID Mask.

Read more:

5.8.3.4.1. Authentication API

Thinfinity VirtualUI provides you with an API that you can use to develop your own authentication method and integrate it with VirtualUI.

Choose the code sample of your language of preference and add it to your implementation:

Delphi:

function ValidateUser(

const UserName, Password, Metadata: PWideChar;

SecurityRole, WinUser, WinPass, CustomData: PWideChar;

var Handled: Boolean): Cardinal; stdcall;

Input:

Username & Password

The credentials that you are trying to validate with the external authentication

Metadata

A JSON with the remote browser/user information: URL, IP, Cookie UBRWID and the product's name

Output:

SecurityRole

Specifies the Windows mapping of the authenticated user (UserName and Password). This SecurityRole can either be a Windows user or group, and it will be used to check which profiles it has access to

WinUser, WinPass

(optional) Credentials of a mapped Windows user. Will be used to run the application instance.

CustomData

(optional) Data for passing on to the application

Handled

Returns whether the login could be handled by the DLL.

C++:

THINFINITY_API DWORD __stdcall ValidateUser(LPWSTR lpUserName, LPWSTR lpPassword, LPWSTR lpMetadata, LPWSTR lpSecurityRole, LPWSTR lpWinUser, LPWSTR lpWinPass, LPWSTR lpCustomData,

PBOOLEAN pHandled)

Input:

lpUserName & lpPassword

The credentials that you are trying to validate with the external authentication

lpMetadata

A JSON with the remote browser/user information: URL, IP, Cookie UBRWID and the product's name

Output:

lpSecurityRole

Specifies the Windows mapping of the authenticated user (UserName and Password). This SecurityRole can either be a Windows user or group, and it will be used to check which profiles it has access to

lpWinUser, lpWinPass

(optional) Credentials of a mapped Windows user. Will be used to run the application instance.

lpCustomData

Data for passing on to the application

pHandled

Returns whether the login could be handled by the DLL.

C#:

Input:

lpUserName & lpPassword

Specifies the Windows mapping of the authenticated user (UserName and Password). This SecurityRole can either be a Windows user or group, and it will be used to check which profiles it has access to

lpMetadata

A JSON with the remote browser/user information: URL, IP, Cookie UBRWID and the product's name

Output:

lpSecurityRole

The authenticated username

lpWinUser, lpWinPass

(optional) Credentials of a mapped Windows user. Will be used to run the application instance.

lpCustomData

Data for passing on to the application

pHandled

Returns whether the login could be handled by the DLL.

Read more:

5.9. Virtualization

Additionally, in both cases, all users may have access to shared folders that it might be desirable to hide from them.

Thinfinity VirtualUI addresses these potential drawbacks by providing the File System and Registry Virtualization feature.

The main purposes of the Registry and File System virtualization are:

· To show only relevant folders.

· To provide private folders based on the application's credential system.

· To provide registry keys based on the application's credential system.

Read more:

5.9.1. File System Virtualization

The file system mapping definition is a set of one to one redirection rules that link a real folder to the redirected folder path.

There are two types of redirection:

· Shared: for all connected users. It can be defined as readonly.

· Private: for a single identified user.

The configuration is done through the The File System Virtualization Editor, which will be installed with the Standard or server component installation.

Read more:

5.9.1.1. Creating File System Redirections

In order to add a path in the Virtualization Editor, right click on the main area of the screen and choose 'New Path...'.

This will bring up the 'Edit Directory' dialog.

Field

Description

Mode

Choose 'Shared' if you want this mapping to apply to all users.

Choose 'Private' if you only want this mapping to apply to a single user.

Read Only

Only available for Shared Mode. Check this option to make the mapped directory read only for the user.

5.9.1.2. The .vdir Files

Read more:

5.9.1.3. Testing the File System Virtualization

Field

Description

User

Type in a testing user name. Later on, you can test using another user and verify that the files stored for each user are isolated.

Program

Choose a program with which to test the Filesystem virtualization. It has to be a program capable of opening files.

Read more:

5.9.2. Registry Virtualization

Registry Virtualization allows developers to store end-user information in the Windows Registry in a secure and isolated way and to provide authentication-based registry entries.

Additionally, shared registry entries can be redirected to safer places in the Windows Registry.

The registry mapping definition is a set of one to one redirection rules that link a real entry to the redirected entry.

There are two types of redirection:

· Shared: for all connected users.

· Private: for a single identified user.

Private redirection entries include the identified user ID appended to the redirected entry.

The configuration is done through the Registry Virtualization Editor, which will be installed with the Standard or server component installation.

Read more:

5.9.2.1. Creating Registry Redirections

In order to add a registry redirection, right click on one of the Server trees and choose 'Add Redirection'.

This will bring up the 'Edit Key Redirection' dialog:

Field

Description

Mode

Choose 'Shared' if you want this key redirection to apply to all users.

Choose 'Private' if you only want this key redirection to apply to a single user.

Source

Choose the source registry key you want to redirect.

Destination

Choose a registry destination key.

Editing Redirections

In order to edit a key redirection, right click on it and choose 'Edit Redirection'.

You will then be able to edit the redirection in the 'Edit Key Redirection' dialog.

Deleting Redirections

In order to delete a redirection, right click on it and choose 'Delete Redirection'.

Read more:

5.9.2.2. The .vreg Files

Read more:

5.9.2.3. Testing Registry Virtualization

In order to test the registry virtualization, choose the 'File' - 'Test' option from the main menu. This will bring up the 'Launch Application' dialog:

Field

Description

User

Type in a testing user name. Later on, you can test using another user and verify that the registry changes stored for each user are isolated.

Program

Choose a program with which to test the registry virtualization. It has to be a program that uses the registry.

Read more:

5.9.3. Implementing Virtualization in Your Application

In order to apply the virtualization filters created with the Filesystem Virtualization Editor or the Registry Virtualization Editor, you have to add some code to your application.

After virtualui.Start(), load and apply the created filters with the current user credentials

Delphi:

virtualui.RegistryFilter.User := 'user identification';

virtualui.RegistryFilter.CfgFile := 'file.vreg';

virtualui.RegistryFilter.Active := true;

virtualui.FilesystemFilter.User := 'user identification';

virtualui.FilesystemFilter.CfgFile := 'file.vdir';

virtualui.FilesystemFilter.Active := true;

C#:

virtualui.Start();

virtualui.RegistryFilter().User = “user identification”;

virtualui.RegistryFilter().CfgFile = “file.vreg”;

virtualui.RegistryFilter().Active = True;

virtualui.FilesystemFilter().User = “user identification”;

virtualui.FilesystemFilter().CfgFile = “file.vdir”;

virtualui.FilesystemFilter().Active = True;

C++:

virtualui->Start();

virtualui->RegistryFilter()->User = “user identification”;

virtualui->RegistryFilter()->CfgFile = “file.vreg”;

virtualui->RegistryFilter()->Active = True;

virtualui->FilesystemFilter()->User = “user identification”;

virtualui->FilesystemFilter()->CfgFile = “file.vdir”;

virtualui->FilesystemFilter()->Active = True;

In order to disable registry or filesystem filtering, set the Active property to false.

Read more:

5.10. OEM Licensing

There are two prerequisites:

· The application that uses the OEM Licensing Library (Thinfinity.VirtualUI.OEM.dll) must be digitally signed.

· You must have a valid OEM key.

To get an OEM key, you must provide Cybele Software with a digital certificate's thumbprint. On each licensing request, three parameters will be used to validate the requestor:

· The OEM-licensed Company's e-mail.

· The provided OEM key.

· The digital certificate's fingerprint, taken from the digital certificate that signs the executable making the OEM library call.

The generated OEM key and the digital certificate's thumbprint, along with your customer identification (e-mail), will be used to securely validate the licensing requests your application will make.

Read more:

5.10.1. How to Create and Revoke Licenses

visThe OEM library provides two functions to create a license and two functions to revoke a license:

· CreateLicenseW (Unicode version) and CreateLicenseA (ANSI version).

· RevokeLicenseW (Unicode version) and RevokeLicenseA (ANSI version).

In order to test the license creation and activation process, you can enable the SandboxMode in the OEM.ini file.

[LICENSE]

SandboxMode = True

The OEM.ini file should be placed in both the bin32 and bin64 paths under the Thinfinity VirtualUI installation folder and in the user's application executable file folder.

The software will first look for the file in the executable's directory (either the application's or any server's). If it doesn't find it there, there are two alternatives:

For the virtualizer, which is in ibin, it will search in bin64 and, afterwards, in bin32
For the rest of the cases. it searches for it in the parent directory. That is, if something runs in bin32 or bin64 it can use an oem.ini from their parent directory.

Adding External Methods

In a Delphi program we must first declare the external functions in their ANSI or Unicode version.

ANSI:

function CreateLicenseA(const email, oemkey, customerid: PAnsiChar;

units: DWORD; serial: PAnsiChar): integer; stdcall;

external 'Thinfinity.VirtualUI.OEM.dll';

function RevokeLicenseA(const email, oemkey, serial: PAnsiChar): integer; stdcall;

external 'Thinfinity.VirtualUI.OEM.dll';

Unicode:

function CreateLicenseW(const email, oemkey, customerid: PWideChar;

units: DWORD; serial: PWideChar): integer; stdcall;

external 'Thinfinity.VirtualUI.OEM.dll';

function RevokeLicenseW(const email, oemkey, serial: PWideChar): integer; stdcall;

external 'Thinfinity.VirtualUI.OEM.dll';

In order to access external library functions in a C# program, please declare:

[DllImport("Thinfinity.VirtualUI.OEM.dll",

CallingConvention = CallingConvention.StdCall, CharSet = CharSet.Unicode)]

private static extern int CreateLicenseW(string email, string oemkey,

string customerid, int units, StringBuilder serial);

[DllImport("Thinfinity.VirtualUI.OEM.dll",

CallingConvention = CallingConvention.StdCall, CharSet = CharSet.Unicode)]

private static extern int RevokeLicenseW(string email, string oemkey, string serial);

Read more:

5.10.1.1. Creating Licenses

In order to create a new Thinfinity VirtualUI license you must use the corresponding CreateLicense method with the following parameters:

Email

OEM-licensed Company´s e-mail

OEMKey

OEM Key.

CustomerID

Arbitrary customer identification for the new license. This can be an e-mail address, a serial number or any other customer identification.

Units

Serial

out

Serial number of the successfully generated license.

A call to the CreateLicense function will return one of the following error codes:

No error. The "Serial" parameter will contain the generated serial number.

-1

General error in license server.

-2

Incorrect Email or OEM Key.

-3

No more units available.

-4

OEM License expired.

-5

General error. Cannot create license.

-10

Invalid response received from license server.

-20

Malformed response received from license server.

-100

General error in library.

-101

Application invalid: not digitally signed.

>200

HTTP status code.

The following example shows how to create a license using Delphi. Please note that you must replace CreateLicenseW by CreateLicenseA when using ANSI chars.

procedure CreateLicense;

var

result: Integer;

serial: WideString;

begin

serial := StringOfChar(' ', 128);

result := CreateLicenseW(PChar('OEM_EMAIL'), PChar('OEM_KEY'),

PChar('CUSTOMER_ID'), UNIT_COUNT, PWideChar(serial)); // Check result

end;

And this is how you create it using C#:

private void CreateLicense()

{

StringBuilder sn = new StringBuilder(128);

int result = CreateLicenseW("OEM_EMAIL", "OEM_KEY",

"CUSTOMER_ID", UNIT_COUNT), sn);

string serial = "";

// Check result

if (result == 0)

{

serial = sn.ToString().Trim();

}

else

{

// Error

}

Note: In all these examples, please replace 'OEM_EMAIL' and 'OEM_KEY' with your Company's OEM registration, 'CUSTOMER_ID' with the Customer identification and 'UNIT_COUNT' with the desired value.

Read more:

5.10.1.2. Revoking Licenses

The RevokeLicense function is used to revoke a previously generated license. These are its parameters:

Email

OEM-licensed Company's e-mail

OEMKey

OEM License Key.

Serial

Serial number to revoke.

This function will return one of the following error codes:

No error. The license was revoked.

-1

General error in license server.

-2

Incorrect Email or OEMKey.

-3

Incorrect Serial number.

-4

Incorrect Serial number.

-5

General error. Cannot revoke license.

-10

Invalid response received from license server.

-20

Malformed response received from license server.

-50

Error in HTTP request.

-100

General error in library.

-101

Application invalid: not digitally signed.

>200

HTTP status code.

Here's how to revoke a license using Delphi:

procedure RevokeLicense;

var result: Integer;

begin

result := RevokeLicenseW(PChar('OEM_EMAIL'), PChar('OEM_KEY'), PChar('SERIAL_NUMBER'); // Check result

end;

And here's how to revoke a license using C#:

private void RevokeLicense() {

int result = RevokeLicenseW("OEM_EMAIL", "OEM_KEY", "SERIAL_NUMBER"); // Check result

}

Note: Please replace 'OEM_EMAIL' and 'OEM_KEY' with your Company's OEM registration information, and replace 'SERIAL_NUMBER' with the Serial to revoke.

Read more: