Visual Guard Class Library Documentation

How to integrate Visual Guard in PowerBuilder application

To integrate Visual Guard in your PowerBuilder application you have to:

  • Add the library of Visual Guard in library list of your target.
  • Add the Dll of Visual Guard runtime in your directory project
  • Integrate Visual Guard in the code of your application.
  • Create a Visual Guard repository and declare your application by using the Visual Guard console. This repository will contain all security items (users, roles, permissions ...) of your application.
  • Generate the Visual Guard configuration files by using the Visual Guard console. These configuration files will be needed to connect your application to the repository.
  • Grant read/write permissions to the repository.

Referencing Visual Guard assemblies

In order to use Visual Guard, you must add references to Visual Guard assemblies:

  • Open the workspace of your project in PowerBuilder.
  • In the solution explorer, expand the workspace node.
  • Right-click the Target node for the workspace and select Properties… from the shortcut menu.
  • In Library List tab, select the 2 libraries Novalys.visualguard.security.pbrt.pbl, Novalys.visualguard.security.pbrte.pbl .
  • Click the OK button

If the library does not appear in this list you can use the Browse tab and select them in the directory Visual Guard Console\VG PB Runtime\PB version Description of Visual Guard libraries:

  • Novalys.VisualGuard.Security.pbrt.pbl contains the main Visual Guard classes. The contents of this PBL should not be modified by developers.
  • Novalys.VisualGuard.Security.pbrte.pbl contains the classes needed to extend the functionality of Visual Guard.
  • Novalys.VisualGuard.Security.pbrt.dll contains the base classes and SSO manager.

Make your configuration file for connection to Visual Guard Server

For connecting to Visual Guard Server you indicate in this file the URL and the Number of the Port of the server and all other parameters for Visual Guard.

  • Example of file configuration: myconfigfile.cfg

    [SECURITY]
    VGServer=http://127.0.0.1:29000|http://127.0.0.1:29001
    mergeRoles=Y 
    supportedAuthenticationModes=VG|AD|WBC
    dynamicBrowser=Y
    silentMode=Y 
    trace=Y
                            

Adding Visual Guard in your code

There is one main class in Visual Guard:

  • vg_n_cst_vgmanager : This class provides the main access point for interacting with Visual Guard. It provides authentication and authorization features, it allows to set the security of the object of your application.

You must load the security before all other code. In this case you will be sure to set the security of all the objects of your application. Visual Guard will not automatically set the security of this window. In this case, you must set the security of this window after loading the permissions of the user (see the method vg_n_cst_vgmanager.SetSecurity ).

Declare the Security Manager

All communication between Visual Guard and your application takes place through the “Security manager”.

This Manager is the User Object “vge_n_cst_vgmanager” in the PBL “Novalys.VisualGuard.Security.pbrte.pbl”.

It provides authentication and authorization features and it applies the security on the application.

The security manager has to be declared as global variable or an Instance variable in a global object.

Example:

                    // Declare the security manager as global variable
                    vge_n_cst_vgmanager guo_vgmanager
            

For PFC application declare the security manager as Instance variable in the Object “n_cst_appmanager” in the library “pfeapsrv.pbl”.

Create the Security Manager

You have to instantiate the security manager when setting up your application (for example, in the open event of the application).

Example:

                        // Create the security manager
                        guo_vgmanager = CREATE vge_n_cst_vgmanager
            

For the PFC, create the security manager in the Constructor Event of the object “n_cst_appmanager” in the library “pfeapsrv.pbl”.

Destroy the Security Manager

You have to destroy the security manager before stopping the application (the close event of the application, for example).

Example:

                        // Destroy the security manager
                        if IsValid(guo_vgmanager) then Destroy (guo_vgmanager)
            

For the PFC, destroy the security manager in the Destructor Event of the object “n_cst_appmanager” in the library “pfeapsrv.pbl”.

Declare the Configuration file (and Trace file if use) of application

Example:

                        // Declare configuration file with your parameters to connect at Visual Guard Server
                        guo_vgmanager .of_setconfigfile ("myconfigfile.cfg")
            

                        // Declare the trace file if you use tracing action execution in your application
                        guo_vgmanager .of_settracefile ("mytracefile.log")
            

Authenticating a user with your own login window

Before using the application, the user has to be authenticated. To authenticate, the user can use a Visual Guard Accounts or a Windows account (See the Visual Guard Console documentation for more detail)

The Visual Guard Account, the Windows Account and the Window By Credential Account can be authenticated using the following code, in the open event of the application or in the login window:

Example:

                        // Authenticate a Visual Guard User and load the security data
                        if isvalid(guo_vgmanager) Then
                         if guo_vgmanager.of_VerifyUser(VGlogin, VGpassword) > 0 Then
                             Open(w_Main)
                          Else
                        Return
                             End if
                        End if
            

                        // Authenticate a Windows User and load the security data
                        if isvalid(guo_vgmanager) Then
                         if guo_vgmanager.of_VerifyUser() > 0 Then
                             Open(w_Main)
                          Else
                        Return
                             End if
                        End if
            

                        // Authenticate a Windows By Credential User and load the security data
                        if isvalid(guo_vgmanager) Then
                         if guo_vgmanager.of_VerifyUser(VGlogin, VGpassword, vg_n_authenticationmode.windowsbycredential) > 0 Then
                            Open(w_Main)
                          Else
                        Return
                             End if
                        End if
            

This API allows you to:

  • Check if that the Visual Guard account , the Windows account and Windows By Credential account exists
  • Check if the user password if valid (Visual Guard account only)
  • Check if the user has a valid profile on this application
  • Load the application security related to the account profile

Secure Application Components

You can apply the security anywhere in the application, using the function “of_SetSecurity”. This function takes three parameters:

  • CallingObject: The main object from which you apply the security, usually the Window
  • CallingID: A string identifier to differentiate many calls from the same object
  • Parameters: A string containing one or more parameters to send to the security manager

In general, this function is called in the open event of the ancestor window:

                        // Trigger the security in the open Event of the ancestor window
                        if isvalid(guo_vgmanager) Then
                            guo_vgmanager.of_SetSecurity( this, "open", "")
                        End if
            

For the PFC, Add the following code:

                        // In the event “w_master.pfc_preopen” in “pfemain.pbl”:
                        if IsValid(guo_vgmanager) Then
                            guo_vgmanager.of_SetSecurity ( this, "open", "")
                        End if
            

                        // In the event “w_master.pfc_postopen” in “pfemain.pbl”:
                        if IsValid(guo_vgmanager) Then
                            guo_vgmanager.of_SetSecurity ( this, "postinit ", "")
                        End if
            

                        // In the event “u_dw.Constructor” in “pfemain.pbl”:
                        if IsValid(guo_vgmanager) Then
                            guo_vgmanager.of_SetSecurity ( this, "constructor ", "")
                        End if
            

With this code, the Visual Guard manager can apply the security for all the descendent of the calling objects.

How to use Visual Guard with the Local System

The program VGPBClient.exe and these dependencies must be copying in the current directory of the secure

PowerBuilder application using Visual Guard 2016. (Or in a path accessible by it).

The configuration of the VisualGuardConfiguration.config file of this program should be made correctly:

Modify applicationId and connectionString with your values of application:

applicationId="7e6b1582-9229-451a-a615-22ec70933353"

connectionString="server=YOURSERVERNAME\YOURSQLEXPRESS;initial catalog=visualguarddb;Trusted_Connection=True;"

Configuration PowerBuilder Application

In the configuration file of the PowerBuilder application (.cfg) write the information below:
                            [SECURITY]
                            VGServer=VGPBClient

                            TraceServeur=Y (or N, to delete or no files exchange with VGPBClient for tracing execution).
            

The exchange files between PowerBuilder application and VGPBClient are generated, by default, in the directory:

  • C:\ProgramData\Novalys\VisualGuard\FileTrsf

And following the setting of "traceServer" in file configuration (.cfg) of PowerBuilder application files are deleted after use or no.