How to use .Net API ?

Estimated reading: 5 minutes

Introduction

Visual-Guard is a comprehensive Identity and Access Management (IAM) solution that provides robust security for business applications. It offers a unified approach to application security, integrating several major access control features such as authentication, identity management, authorization, audit & reporting, supervision, permission matrix, and a workflow system.

One of the powerful tools offered by Visual-Guard is its .NET API, which allows developers to interact with the Visual-Guard system programmatically within a .NET environment. The API provides a set of methods and classes for managing users, roles, permissions, and other security-related aspects of your applications.

Two key classes in the Visual-Guard .NET API are VGSecurityManager and VGSecurityRuntime. These classes provide a common format to perform any Visual-Guard operation on any entity.

The VGSecurityManager class is the main entry point for managing security in your application. It provides methods for managing groups, roles, permission sets, permissions, memberships, and repositories.

The VGSecurityRuntime class is used to perform runtime operations. It provides access to instances of various entities such as groups, roles, permission sets, permissions, memberships, and repositories.

The common format to perform any operation is as follows:

VGSecurityManager.Runtime.<Entity>.<Action>

Here, <Entity> can be one of the following:

VGGroupsInstance
VGRolesInstance
VGPermissionSetsInstance
VGPermissionInstance
VGMembershipInstance
VGRepositoryInstance
Etc…

And, <Action> can be any operation for the above entities, such as CreateGroup, UpdateGroup, CreateRole, UpdateRole, CreateUser, etc.

For example, if you want to create a new role, you would use the following code:

VGSecurityManager.Runtime.Roles.CreateNewRole("NewRole");

This line of code creates a new role named “NewRole” in the Visual-Guard system.

The Visual-Guard .NET API provides a powerful set of tools for managing security within your applications. A key component of this API is the VGSecurityRuntime class, which is used to perform runtime operations.

To obtain an instance of VGSecurityRuntime, you need to call VGSecurityManager.Runtime. The VGSecurityManager class is the main entry point for managing security in your application, and its Runtime property returns an instance of VGSecurityRuntime.

Fast Authentication with Visual-Guard API

One of the key features of this API is the ability to authenticate users. This is done using the VGSecurityManager.Authenticate method, which takes a username and password as input and returns an instance of VGAuthenticationState.

The VGAuthenticationState class represents the result of an authentication attempt. It provides several properties that indicate whether the authentication was successful and, if not, what the reason for the failure was.

Here’s a breakdown of the code snippet you provided:

using Novalys.VisualGuard.Security;

// Attempt to authenticate the user
VGAuthenticationState state = VGSecurityManager.Authenticate(txtUserName.Text, txtPassword.Password);

// Check the result of the authentication attempt
if (state.IsFailed)
{
    // Handle failed authentication
    DialogResult = false;

    if (state.IsCanceled) return;

    if (state.IsCredentialInvalid)
    {
        // Handle invalid credentials
        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)
    {
        // Handle unauthorized user
        MessageBox.Show("User not authorized to log on the application");
    }
    else if (state.IsUserAccountExpired)
    {
        // Handle expired user account
        MessageBox.Show("Your account is no more valid. Contact your administrator");
    }
    else if (state.IsUserAccountNotYetAvailable)
    {
        // Handle not yet available user account
        MessageBox.Show("Your account is not yet available.");
    }
    else if (state.IsUserAccountLockedOut)
    {
        // Handle locked out user account
        MessageBox.Show("Your account is locked. Contact your administrator.");
    }
    else if (state.MustChangePasswordAtNextLogon)
    {
        // Handle insecure password
        MessageBox.Show("Your password is not secure enough. You must change it.");
    }
}
else
{
    // Handle successful authentication
    DialogResult = true;

    if (!state.IsPasswordSecure)
    {
        // Handle insecure password
        MessageBox.Show("Your password is not secure enough. You must change it.");
    }
}

In this code snippet, we first attempt to authenticate the user using the VGSecurityManager.Authenticate method. We then check the IsFailed property of the returned VGAuthenticationState instance to determine whether the authentication attempt was successful. If the authentication failed, we use the other properties of VGAuthenticationState to determine the reason for the failure and display an appropriate message to the user.

Some articles

If you want to store your Visual Guard repository in database (Oracle, SQLServer)
make sure you have read Storing a repository in a database.
If you want to integrate Visual Guard in a WinForm application, see
How to integrate Visual Guard to your WinForm application.
If you want to integrate Visual Guard in an ASP.Net 2.0 application, see
How to integrate Visual Guard to your WebForm 2.0 application.
If you want to integrate Visual Guard in a WCF application, see
How to integrate Visual Guard to your WCF application.
If you want to understand how Visual Guard secures the object of your applications,
see How Visual Guard secures an application
If you want to understand how to apply security in your application, see
How to apply security in your application.
If you want to understand how to deploy a repository, see
How to deploy a repository.
You can also examine the sample project sources installed with Visual Guard.