Visual Guard Class Library Documentation

How to integrate Visual Guard in WCF applications

To integrate Visual Guard in your WCF project you have to:

Referencing Visual Guard assemblies

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

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.

Add Visual Guard assemblies

If the assemblies does not appear in this list you can use the Browse tab and select them in the directory <Visual Guard installation directory>/bin/2.0.

Description of Visual Guard assemblies:

Modifying the "app.config" or "web.config" file of your application 

To enable Visual Guard in your application, you must declare and configure the section class <system.serviceModel> of your application hosting your WCF services. You can edit manually your application configuration file or use the Microsoft  Service Configuration Editor (Right-click on  your configuration file then select the option 'Edit WCF Configuration) .

Adding a new service behavior

The first step is to create a new service behavior. This behavior allows you to indicate how Visual Guard authenticates and authorizes a client to access to a service.

 

In Service Configuration Editor:

 

In text editor:

<configuration>
  <system.serviceModel>
    	...
        <behaviors>
            <serviceBehaviors>
                <behavior name="VGSecurityBehavior">
                    ...
     		</behavior>
            </serviceBehaviors>
    	...
      </behaviors> 
   </system.serviceModel>
</configuration>

 

Now, you have to add a serviceCredentials and serviceAuthorization elements to the service behavior

 

 

In Service Configuration Editor:

 

In text editor:

<configuration> 
    <system.serviceModel>
	<behaviors>
		 <serviceBehaviors>
        		<behavior name="VGSecurityBehavior">
				<serviceCredentials> 
				...
				</serviceCredentials>
				<serviceAuthorization>
            			... 
				</serviceAuthorization> 
			</behavior> 
		</serviceBehaviors> 
         </behaviors>
    </system.serviceModel> 
</configuration>


The serviceCredentials element specifies the credential to be used in authenticating the service and the client credential validation-related settings.

If you use Username/Password credentials to validate a Visual Guard account, you have to specify that the UserNamePasswordValidationMode is 'Custom' and the type of the CustomUserNamePasswordValidatorType is 'Novalys.VisualGuard.Security.WebService.VGUserNameValidator, Novalys.VisualGuard.Security.WebService'.


In Service Configuration Editor:

 

In text editor:

<configuration>
<system.serviceModel>
<behaviors>
<serviceBehaviors>
<behavior name="VGSecurityBehavior">
<serviceCredentials>
<usernameAuthentication
userNamePasswordValidationMode
="Custom" customUserNamePasswordValidatorType="Novalys.VisualGuard.Security.WebService.VGUserNameValidator, Novalys.VisualGuard.Security.WebService"
cacheLogonTokens
="true"
/
>
</serviceCredentials> <serviceAuthorization>
...
</serviceAuthorization>
</behavior>
</serviceBehaviors>
</behaviors>
</system.serviceModel>
</configuration>

You can use your own authentication mechanism or any authentication mechanisms compatible with WCF (Windows account...) . In this case, you can edit your own configuration for the serviceCredentials element. Visual Guard will use the identity provided by WCF to check the access to the service.

Now you have to specify that the authorization access checking is provided by the Visual Guard. To do that, you must specify in the serviceAuthorization element that the PrincipalPermissionMode is 'Custom' and the ServiceAuthorizationManagerType is 'Novalys.VisualGuard.Security.WebService.VGServiceAuthorizationManager, Novalys.VisualGuard.Security.WebService'.

 

In Service Configuration Editor:

 

In text editor:

<configuration>
<system.serviceModel>
<behaviors>
<serviceBehaviors>
<behavior name="VGSecurityBehavior">
<serviceCredentials>
<usernameAuthentication
userNamePasswordValidationMode
="Custom" customUserNamePasswordValidatorType="Novalys.VisualGuard.Security.WebService.VGUserNameValidator,Novalys.VisualGuard.Security.WebService"
cachedLogonTokens
="true"
/
> </serviceCredentials> <serviceAuthorization principalPermissionMode="Custom" serviceAuthorizationManagerType="Novalys.VisualGuard.Security.WebService.VGServiceAuthorizationManager, Novalys.VisualGuard.Security.WebService" />
</behavior> </
serviceBehaviors>
</behaviors>
</system.serviceModel>
</configuration>

The Visual Guard Service authorization manager will check the authorization access of the current identity. When the current identity is not allowed to access to the application (when the user account is not defined in the repository or is not a member of a role of the application), Visual Guard will reject the access to the service if anonymous session are not allowed. When anonymous session are allowed, the caller  is authorized to access to the service and becomes a member of the Anonymous role.

Configuring the service

You have to specify to all services requiring Visual Guard authentication and authorization mechanism the service behavior defined above.

In Service Configuration Editor:

In text editor:

<configuration>
<system.serviceModel>
<services>
<service
behaviorConfiguration="VGSecurityBehavior" name="CalculatorService"> <endpoint binding="wsHttpBinding" contract="ICalculatorService" /> </services> .... </system.serviceModel>
</configuration>

Integrating Visual Guard in your code

The main class in Visual Guard: Novalys.VisualGuard.Security.VGSecurityManager This class provides the main access point for interacting with Visual Guard. It allows to set the security of the object of your application.

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

Restricting the access to a service

Visual Guard is compatible with the standard PrincipalPermissionAttribute class. This attribute will check whether a user is authenticated or is a member of a role. Visual Guard also provides its own attribute: Novalys.VisualGuard.Security.VGPrincipalPermission. This attribute is similar as the standard PrincipalPermissionAttribute class and allows to check a Visual Guard role or aVisual Guard permission and does not requires

The following example demonstrates how to restrict access to the "Multiply" operation to caller with the permission "CanMultiply".

[C#]
[VGPrincipalPermission(SecurityAction.Demand, Name="CanMultiply", Type=VGPermissionType.Permission)]
public double Multiply(double n1, double n2)
{
  return  n1 * n2;
}


[Visual Basic]
<VGPrincipalPermission(SecurityAction.Demand, Name:="CanMultiply", Type=VGPermissionType.Permission)> _
Public Function Multiply(Double n1, Double n2) As Double
    Return n1 * n2
End Function

Securing objects of the application

If you need to apply Visual Guard security actions on object of your application, you will need to call Visual Guard to set the security of the object. To do that, you must:

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

The following code show how to secure the Calculator class that implement the ICalculator service contract:

[C#]
public class Calculator: ICalculator, VGISecurable
{
public Calculator()
{
// .... // Initialization of the object
// ....
// This call will indicates to Visual Guard that the class must be secured.
VGSecurityManager.SetSecurity(this);
}
public double Multiply(double n1, double n2)
{ return n1 * n2;
}
}
[Visual Basic]
Public Class Calculator
Implemenents ICalculator, VGISecurable Private Sub New() ' ... ' Initialization of the object ' ... ' This call will indicates to Visual Guard that the class must be secured. VGSecurityManager.SetSecurity(Me) End Sub Public Function Multiply(ByVal n1 as Double, ByVal n2 as Double) As Double Return n1 * n2; End Function End Class

How to filter granted roles

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

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

[Visual Basic]
Sub VGSecurityManager_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 VGSecurityManager_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; 
      }
    } 
}

How to change default Visual Guard configuration settings


By default, Visual Guard used the Visual Guard configuration files located in the same directory as the Novalys.VisualGuard.Security.dll assemblies. It is possible to change the path of the configuration file or configuration at runtime by handling the event VGServiceRuntimeProvider.RuntimeInitialized

Create a repository and declare the application


Once Visual Guard 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 directory containing the assemblies 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 to your application only when a role of the application is granted to this user.

Grants Read/Write permission to the Repository

Visual Guard needs to Read/Write permissions to access to 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 to the Visual Guard repository database must be a member of "vg_BasicAccess" role.

In most of case, 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:

 

See Also

Debugging Visual Guard Security Actions
How to apply security in your application
How Visual Guard secures an application
How to generate or edit the Visual Guard configuration files