How to integrate Visual Guard .Net in a WinForm application

To integrate Visual Guard in your application you must:

• Add the assemblies of Visual Guard .Net as references of your project.
• Insert the code to enable the security in the Dotnet application.
• Create a Visual Guard .Net 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.
  

Integration Demo

This demo shows how to integrate Visual Guard .Net in a Winform 2.0 application

Referencing Visual Guard assemblies

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

• Open the solution of your project in Visual Studio.
• In the solution explorer, expand the project node.
• Right-click the References node for the project and select Add Reference from the shortcut menu.
• In .Net tab, select the 3 assemblies named Novalys.VisualGuard.Security, Novalys.VisualGuard.Security.WinFrom, Novalys.VisualGuard.Security.<RepositoryType> (File, SQLServer or Oracle), then click the Select button, and then click the OK button.

Note: In the list of assemblies, Visual Studio can display different versions of the Visual Guard assemblies. You must select the assembly corresponding to the version of the framework used in your project.

If the assemblies do not appear in this list you can use the Browse tab and select them in the directory <Visual Guard installation directory>/bin/2.0 for .Net 2.0 applications or <Visual Guard installation directory>/bin/1.1 for .Net 1.1 applications

• Novalys.VisualGuard.Security contains the main Visual Guard .Net classes.
• Novalys.VisualGuard.Security.Files contains the classes needed to access a file based repository.
• Novalys.VisualGuard.Security.SQLServer contains the classes needed to access a repository stored in a Microsoft SQLServer database (SQLServer 2000 or higher).
• Novalys.VisualGuard.Security.Oracle contains the classes needed to access a repository stored in an Oracle database (8i or higher).
• Novalys.VisualGuard.Security.WinForm contains all classes based on WinForm control. This assembly is needed only if you use the forms provided by Visual Guard to authenticate, change a password or select a role. If you want to use your own form you do not need to add a reference to this assembly.
  

Adding Visual Guard in your code

There are 2 main classes in Visual Guard:

• Novalys.VisualGuard.Security.VGSecurityManager: This class provides the main access point for interacting with Visual Guard. It provides authentication and authorization features, it allows you to set the security of your application object.
  
• Novalys.VisualGuard.Security.WinForm.VGLoginForm: This class is the default authentication form provided by Visual Guard. This class is very easy to use and is fully integrated with Visual Guard. You can use your own form to authenticate a user. In this case you must call the Authenticate method provided by the VGSecurityManager class.

You must load the security before any other code. This ensures that you set the security of all the objects of your application. If you load your main form before authenticating a user, Visual Guard will not automatically set the security of this form. In this case, you must set the security of this form after loading the permissions of the user (see the method VGSecurityManager.SetSecurity).

Authenticating a user in VB.Net project where the application framework is enabled

It is recommended that you use the event MyApplication_Startup in order to load the security. When the user is not authenticated or authorized, you should set the property e.Cancel to true in order to stop the application. The following example demonstrates how to use the login form provided by Visual Guard to authenticate the user.

Imports Novalys.VisualGuard.Security.WinForm
Imports System.Reflection
Imports Microsoft.VisualBasic.ApplicationServices
Namespace My
   Partial Friend Class MyApplication

      Private Sub MyApplication_Startup(ByVal sender As Object, ByVal e As StartupEventArgs) Handles Me.Startup
         Dim form As VGLoginForm = New VGLoginForm()
         If form.ShowDialog() <> DialogResult.OK Then
            e.Cancel = True
            Return
         End If
      End Sub
   End Class

End Namespace

Authenticating a user in your own login form

The following example demonstrates how to authenticate a user. This code can be inserted in the click event of the OK button in a login form:

[C#]
VGAuthenticationState state = VGSecurityManager.Authenticate(user.Text, password.Text);
if (state.IsFailed())
{
   this.DialogResult = Dialog.None
   if (state.IsCanceled) return;
   if (state.IsCredentialInvalid)
   {
      if (state.IsLastBadLogin)
      {
         MessageBox.Show("Invalid user or password. The next bad login will lock your account.");
      }
      else
      {
         MessageBox.Show("Invalid user or password.");
      }
   }
   else if (state.IsUserNotAuthorized)
   {
      MessageBox.Show("user not authorized to log on the application.");
   }
   else if (state.IsUserAccountExpired)
   {
      MessageBox.Show("your account is no more valid. Contact your administrator.");
   }
   else if (state.IsUserAccountNotYetAvailable)
   {
      MessageBox.Show("your account is not yet available.");
   }
   else if (state.IsUserAccountLockedOut)
   {
      MessageBox.Show("your account is locked. Contact your administrator.");
   }
   else if (state.MustChangePasswordAtNextLogon)
   {
      MessageBox.Show("Your password is not secure enough.
         You must change it.")ChangePassword
         form =
             New ChangePassword();

      if (form.ShowDialog() == DialogResult.OK) {
      passwordTextBox.Text = form.NewPassword: goto
      Reauthenticate; }
   }
}
else
{
    if (!state.IsPasswordSecure)
    {
MessageBox.Show("Your
    password is not enough secure. You must change
       it.") ChangePassword
       form
              = New ChangePassword form.ShowDialog();
                        }
}

[Visual Basic]
Reauthenticate:
Dim state As VGAuthenticationState = VGSecurityManager.Authenticate(userTextBox.Text, passwordTextBox.Text)
If state.IsFailed() Then
   Me.DialogResult = DialogResult.None
   If state.IsCanceled() Then Return
   If state.IsCredentialInvalid() Then
      If state.IsLastBadLogin() Then
      MessageBox.Show("Invalid user or password. The next bad login will lock your account.")
      Else
         MessageBox.Show("Invalid user or password.")
      End If
   ElseIf state.IsUserNotAuthorized() Then
      MessageBox.Show("user not authorized to log on to the application")
   ElseIf state.IsUserAccountExpired() Then
      MessageBox.Show("your account is no more valid. Contact your administrator")
   ElseIf state.IsUserAccountNotYetAvailable() Then
      MessageBox.Show("your account is not yet available.")
   ElseIf state.IsUserAccountLockedOut() Then
      MessageBox.Show("your account is locked. Contact your administrator.")
   ElseIf state.MustChangePasswordAtNextLogon Then
   ' The user must change the password before reauthenticating
   MessageBox.Show("You must change your password")
   Dim form As ChangePassword = New ChangePassword
   If form.ShowDialog() = DialogResult.OK Then
      passwordTextBox.Text = form.NewPassword
      GoTo Reauthenticate
      End If
   End If
Else
   Me.DialogResult = DialogResult.OK
   If Not state.IsPasswordSecure() Then
      MessageBox.Show("password is not secure enough. You must change it.")
      Dim form
      As ChangePassword
      = New ChangePassword
            form.ShowDialog()   End If
End If

Using the default login form provided by Visual Guard

If you prefer, you can use the default login form provided by Visual Guard. In this case you can use the following code:

[C#]
Novalys.VisualGuard.Security.WinForm.VGLoginForm login = New Novalys.VisualGuard.Security.WinForm.VGLoginForm();
login.HeaderDescription = login.HeaderDescription + Environment.NewLine + "(the default user is \"jsmith\" and its password \"pwd\")";
login.UserName = "jsmith";
If (login.ShowDialog() == DialogResult.OK)
{
   login.Dispose();
   Application.Run(new MDIForm());
}

[Visual Basic]
Dim login As New Novalys.VisualGuard.Security.WinForm.VGLoginForm
login.HeaderDescription = login.HeaderDescription + Environment.NewLine + "(the default user is ""jsmith"" and its password ""pwd"")"
login.UserName = "jsmith"
If login.ShowDialog() = DialogResult.OK Then
   login.Dispose()
   Application.Run(New MDIForm)
End If

Loading the security for a user authenticated by an external system (based on Windows Logon or another Single Sign-on)

In some cases you may not want to use the Visual Guard authentication mechanism. For example, you can use the Windows logon. In this case you must use the VGSecurityManager.LoadSecurity method. This method will check the authorization of a user and will load the permissions granted to this user.

This example demonstrates how to use the Windows logon to identify the user:

[Visual Basic]
Dim state As VGAuthorizationState
state = VGSecurityManager.LoadSecurity (System.Security.Principal.WindowsIdentity.GetCurrent())
If state.IsFailed Then
   If state.IsUserNotFound Then
      MessageBox.Show("Your are not declared in the security repository")
   ElseIf state.IsUserNotAuthorized Then
      MessageBox.Show("Your are not authorized to log on to this application")
   End If
Else
   Application.Run(New MDIForm)
End If

[C#]
VGAuthorizationState state = VGSecurityManager.LoadSecurity (System.Security.Principal.WindowsIdentity.GetCurrent());
if (state.IsFailed)
{
   if (state.IsUserNotFound)
   {
      MessageBox.Show("Your are not declared in the security repository.");
   }
   elseif (state.IsUserNotAuthorized)
   {
      MessageBox.Show("Your are not authorized to log on to this application.")
   }
}
else
{
   Application.Run(new MDIForm)
}

If you need to secure only form class in your application, you do not need to add more code. Visual Guard can detect automatically all form creations and sets the security automatically. But, if you want to secure other types of class, you must do the following:

• Add the Novalys.VisualGuard.Security.VGISecurable interface to your class.
• Add the call to the VGSecurityManager.SetSecurity method at the end of the constructor.