Visual Guard Class Library Documentation

How to integrate Visual Guard in MVC Application

To integrate Visual Guard in your MVC Application project you have to:

Integration Demo

This demo shows how to integrate Visual Guard in MVC application

How to integrate Visual Guard 

Referencing Visual Guard assemblies

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

Add Visual Guard assemblies

Note: Once the Visual Guard assemblies are referenced into project, you need to mark "Copy Local" property to "true" for each assembly.

Description of Visual Guard assemblies:

 

Modifying the "web.config" file of your application 

To enable Visual Guard in your application, you must declare the class Novalys.VisualGuard.Security.WebForm.VGHttpModule in the list of HttpModules in the "web.config" of your application. To do that, you must:

<add type="Novalys.VisualGuard.Security.WebForm.VGHttpModule,Novalys.VisualGuard.Security.WebForm" name="VGModule"/>

For example:

<configuration> 
<system.web>
 ... 
<httpModules>
      <add type= "Novalys.VisualGuard.Security.WebForm.VGHttpModule,Novalys.VisualGuard.Security.WebForm" name="VGModule" />
</httpModules>
 ... 
</system.web>
<system.webserver>
... <!--  Integrated Mode -->
<modules runAllManagedModulesForAllRequests="true" > 
     <add type= "Novalys.VisualGuard.Security.WebForm.VGHttpModule,Novalys.VisualGuard.Security.WebForm" name="VGModule"/> 
</modules
...

            

 </system.webserver>
        </configuration> 


        

            This module will enable Visual Guard in your application.
                It will automatically detect the type of authentication used in your application.
                Visual Guard supports Forms  and Windows authentication mode.

        

            If you use Form authentication mode, you can use the Visual Guard authentication
            mechanism. In this case you must call the method VGSecurityManager.Authenticate
            in your login form. You can find an example of the authentication integrated in
            a login form in the chapter "Integrate Visual Guard
                in your code".

        

            If you use Windows authentication mode, Visual Guard will automatically detect the
            authenticated user and load the security permissions granted to this user.

        

            If the user does not have any role in the application or if the user is
            not declared in the repository or if the user is anonymous, Visual Guard will deny
            the user access to all pages in your application.

        

            If you want to allow anonymous sessions in your application, you must declare
            an anonymous role to your application in the Visual Guard console.

        

            To enable anonymous sessions, you must:

        
        

            You can use Visual Guard in conjunction with the URL Authorization module to deny
            access to specific users (anonymous or not) or roles. Visual Guard users and
            roles are fully compatible with the URL Authorization module.

            

            Allow Anonymous Access

            If you have not allowed anonymous session in your web application and you want to
            allow certain files to have anonymous access, you must configure your web.config
            with following section. By default Visual Guard secures all pages except login page, so if you want to allow certain pages to have anonymous access(actions without [Authorize] attribute) without redirecting to login page, mark AutoLoginPage="False" :

        
 <configuration>
 <configSections>
      <section name="VGWebConfiguration" type="Novalys.VisualGuard.Security.WebForm.VGWebConfiguration" />
 </configSections>


        
...

        
<VGWebConfiguration excludeExtension=".css,.png,.js,.gif,.jpg,.Gif">
<ExcludePages>
 <add Url="^~/$" />
 <add Url="~/Account/Login" />
</ExcludePages>
 <VGCookieConfig Domain=".vg.local" DomainScope="WebSSO" AutoRedirect="true" AuthenticationUrl="http://vg.local/webApp/Account/Login" />
</VGWebConfiguration>
</configuration>    

        

            Web SSO
        

        

            Web SSO allows users authenticated across sub-domains(Ex. sales.novalys.local, marketing.novalys.local, etc) when the authentication takes places at any application under parent domain(Ex. novalys.local). To enable web sso, you must enable VGCookieConfig as mentioned above. Please go through points below which explains possible scenarios with it.
        

        
		 

            Mixed Mode Authentication
        

        

            Mixed Mode Authentication allows users to be able to authenticate against a web application using either Windows authentication or Forms authentication. If a user executes an application internally from an organization, he can log in with Windows authenticatiom wherein other users who connects to the same application externally can use Form authentication. Visual Guard handles this feature in same application by configuring web.config with essential tags and passing an argument with URI. To enable this feature, please refer to the points below:
        

        
        

            Configuring Membership

        

            Alike Membership API, Visual Guard has its own library of Membership. To use VG
            Membership features, you must declare 
                VGMembershipProvider and 
                    VGRoleProvider in your web.config file.

        

        
<configuration> 
<system.web> ... 
     <roleManager defaultProvider="VGRoleProvider" enabled="true"> 
          <providers> 
                <add name="VGRoleProvider" type="Novalys.VisualGuard.Security.WebForm.VGRoleProvider, Novalys.VisualGuard.Security.WebForm" /> 
         </providers> 
     </roleManager> 
     <membership defaultProvider="VGMemberShipProvider"> 
        <providers> 
              <add name="VGMemberShipProvider" type="Novalys.VisualGuard.Security.WebForm.VGMemberShipProvider, Novalys.VisualGuard.Security.WebForm" /> 
       </providers> 
    </membership> 
   ... 
</system.web> 
</configuration> 

        

        

            Integrating Visual Guard in your code

        

        

        

            The main class in Visual Guard is 
                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
            objects.

        

            You have 3 types of code to integrate Visual Guard in your code:

        
        

            To create a Login page

        

            If you use form authentication mode, you must configure your web.config file as
            described in the previous chapter. You can also use your own controls or develop
            a custom form page.

        

            The following example demonstrates how to authenticate a user. This code can be
            inserted in the LogOn[HttpPost] method of your Login Controller class:

        
[C#]

[HttpPost]
public ActionResult LogOn(LogOnModel model, string returnUrl)
{ 
     if (ModelState.IsValid) 
     {
          if (!VGSecurityManager.Authenticate(model.UserName, model.Password, VGAuthenticationMode.VisualGuard).IsFailed) 
          { 
               VGFormsAuthentication.SignIn(); 
               if (Url.IsLocalUrl(returnUrl) && returnUrl.Length > 1 && returnUrl.StartsWith("/") && !returnUrl.StartsWith("//") && !returnUrl.StartsWith("/\\")) 
               { 
                    return Redirect(returnUrl); 
               } 
               else 
               { 
                    return RedirectToAction("Index", "Home"); 
               } 
          } 
          else 
          { 
               ModelState.AddModelError("", "The user name or password provided is incorrect."); 
          } 
     } 
     return View(model); 
} 

public ActionResult LogOff() 
{ 
     VGFormsAuthentication.SignOut(); 
     return RedirectToAction("Index", "Home"); 
}

        

        
[Visual Basic]

<HttpPost>_ 
Public Function LogOn(ByVal model As LogOnModel, ByVal returnUrl As String) As ActionResult 
     If ModelState.IsValid Then 
          If Not VGSecurityManager.Authenticate(model.UserName, model.Password, VGAuthenticationMode.VisualGuard).IsFailed Then 
               VGFormsAuthentication.SignIn() 
               If Url.IsLocalUrl(returnUrl) AndAlso returnUrl.Length > 1 AndAlso returnUrl.StartsWith("/") _ 
                    AndAlso Not returnUrl.StartsWith("//") AndAlso Not returnUrl.StartsWith("/\\") Then 
                    Return Redirect(returnUrl) 
               Else 
                    Return RedirectToAction("Index", "Home") 
               End If 
          Else 
               ModelState.AddModelError("", "The user name or password provided is incorrect.") 
          End If 
     End If 
     Return View(model) 
End Function 

Public Function LogOff() As ActionResult 
     FormsAuthentication.SignOut() 
     Return RedirectToAction("Index", "Home") 
End Function

        

        

            To secure your application objects

        

            If you want to understand how Visual Guard sets the security of your application
            objects, see How Visual Guard secures an application.

        

            How to filter granted roles

        If a user has more than one role, by default Visual Guard creates a permission set
        that will be a union of all permission sets. If you want to select only one role
        or filter roles granted to the user, you can handle the event 
            VGHttpModule.PermissionLoading. This event allows you to select roles granted
        to the user.

        To handle this event you must declare <VGHTTPModuleName>_ PermissionLoading
        in the global.asax script (where <VGHTTPModuleName> is the name of the Visual
        Guard module declared in the web.config files, by default "VGModule").

        

        The following example demonstrates how to select the role Administrator if this
        role is granted:

        
[Visual Basic]
Sub VGModule_PermissionLoading(ByVal sender As  Object, ByVal e As VGPermissionsLoadingEventArgs) 
If e.Roles.Length > 1 Then
     Dim selectedRoles(1)  As Novalys.VisualGuard.Security.VGGrantedRole 
     For Each role As Novalys.VisualGuard.Security.VGGrantedRole In e.Roles
        If role.Name = "Administrator"  Then 
          selectedRoles(0) = role 
          Exit 
        For Else If role.Name = "Member"  Then 
          selectedRoles(0)  = role 
        Exit For
       End 
If End 
        If Next If
                selectedRoles(0)
                Is
Nothing Then e.Status = Novalys.VisualGuard.Security.VGAuthorizationStatus.ProcessCanceled
        Else e.Roles
        = selectedRoles
        End 
If End 
        If End Sub


        
[C#]
void VGModule_PermissionLoading(object sender, VGPermissionsLoadingEventArgs args) 
{
     if(e.Roles.Length > 1) 
     { 
       Novalys.VisualGuard.Security.VGGrantedRole[] selectedRoles = new Novalys.VisualGuard.Security.VGGrantedRole[1]; 
       foreach (Novalys.VisualGuard.Security.VGGrantedRole role in e.Roles)
       { 
         if (role.Name ==  "Administrator") 
         { 
             selectedRoles[0] = role;
             break; 
         } 
         else if (role.Name == "Member") 
         {
             selectedRoles[0] = role; 
             break; 
         }
       }
       if (selectedRoles[0] == null) 
       {
           e.Status = Novalys.VisualGuard.Security.VGAuthorizationStatus.ProcessCanceled;
       }
       else 
       {
            e.Roles = selectedRoles;
       }
    }
} 


       
        

        

        

            Creating a repository and declaring the application

        Once Visual Guard is integrated in your application, you can create the repository
        containing the information about the security of your application (users, roles,
        permissions ...). You must launch the Visual Guard console, right-click the root
        node in the treeview then select the option "Add repository".

        

        After creating the repository, you must declare your application in the repository.
        Right-click the node corresponding to your repository then select the option 
            "Connect...". After the connection, right-click on
        the repository node then select the option "Add application". At
        the end of the wizard, the console will generate 2 configuration files in the 
            "bin" directory of your application.

        

        Note: If you want to test the connection to this repository from
        your application, you will need to create a role for your application in the Visual
        Guard console and grant this role to a user. A user defined in the repository can
        access your application only when a role of the application is granted to this user.

        

            Securing MVC application

        Once all the above configurations are integrated in your application, you can now
        create permissions.
        

        There are multiple ways possible with Visual Guard to create permission on your
        application. At first, you need to create permission under Permission Node of an
        application. Please find steps below on how to create a permission:

        
        

        You can secure your MVC application in following manner:
        

        
        

             

        
        

        

            Granting Read/Write permission to the Repository

        

            Visual Guard needs to have Read/Write permissions to access the repository. For
            example, for a file based repository you must grant "Modify" permission to
            the directory containing the repository for ASP.NET user accounts. For a repository
            stored in a database, the user used to access the Visual Guard repository database
            must be a member of "vg_BasicAccess" role.

        

            In most cases, you must grant this permission to "MACHINE\ASPNET" user account.
            If you use IIS 6.0 on Windows Server 2003 the user account is "NT Authority\Network
            Service". If you use impersonation, you must grant permission to "MACHINE\IUSR_<MACHINE>"
            for Form authentication mode and "Domain\UserName" for Windows integrated authentication
            mode.

        

            To change permission to a directory, you must: