Annotation Security

ImageGear.ART can be used in a variety of architectural solutions and sometimes it is necessary to provide access to the same ART page for different users with different access levels. ImageGear does not provide a complete solution for access control; instead, it provides a basic set of tools required to implement access control.

By default, access control functionality is disabled. In order to enable it, you have to implement your own class inherited from ImGearARTAccessController and initialize the ImGearARTPage.AccessController property.

Access control can be applied to the following ART classes: ImGearARTPage, ImGearARTGroup, and annotation classes derived from the ImGearARTMark class. All these classes have a public property AccessController, but only the ART page allows you to set a value of the AccessController. For ART Groups and Annotations, this property is initialized internally when a corresponding object is added to the page and cannot be changed directly.

The ImGearARTAccessController class defines a few abstract overloaded methods (bool OnIsAccessAllowed), that you have to implement in your own class. These methods will be called each time the page / group / annotations are accessed. If access is not available, the OnIsAccessAllowed method has to return false. If the method returns true, it means that access is allowed and the corresponding operation will be performed in a regular way, but if the method returns false, an ImGearARTAccessDenied exception will be thrown.

If the exception throwing is undesirable, then before accessing the methods/properties of the ART object, you can explicitly call the IsAccessAllowed method of the access controller and ensure that the current user has the necessary rights:

C# Example	Copy Code
if (artPage.AccessController.IsAccessAllowed(ImGearARTAccessRights.View)) { string author = artPage.Author; //… }

VB.NET Example	Copy Code
If artPage.AccessController.IsAccessAllowed(ImGearARTAccessRights.View) Then Dim author As String = artPage.Author '… End If

Access Rights

ImageGear defines the following access rights:


Right	Description
View	Controls if an object can be viewed
Create	Controls if an object can be created
Delete	Controls if an object can be deleted
Edit	Controls if an object properties can be changed
Resize	Controls if a mark object can be resized
Move	Controls if a mark object can be moved
Export	Controls if a mark object can be exported

Access Token

An access token is an object that describes the current security context of the ART Page. The information that token contains varies on implementation, as a rule it includes identity and privileges of the current user.

ImageGear does not provide implementation of an access token, instead there is a defined, empty abstract class ImGearARTAccessToken. The implementation of an access token should inherit the ImGearARTAccessToken class in order to be able to use it with the ImGearARTAccessController.

The ImGearARTAccessController class contains the abstract property AccessToken which should be used to switch the current user of the ART Page:

C# Example	Copy Code
ImGearARTAccessToken accessToken = _userDataBase.GetAccessToken("User name #1"); if (accessToken != null) { _artPage.AccessController.AccessToken = accessToken; // ... }

VB.NET Example	Copy Code
Dim accessToken As ImGearARTAccessToken = _userDataBase.GetAccessToken("User name #1") If accessToken IsNot Nothing Then _artPage.AccessController.AccessToken = accessToken ' ... End If

There are no specific requirements for the access token implementation. This abstraction was introduced to simplify switching between users and is not used internally by ImageGear.

Secure Object Data

We use the term “secure object” to refer to any object in ImageGear ART in which the access must be limited: ImGearARTPage class, ImGearARTGroup class, and any annotation class derived from ImGearARTMark.

Sometimes it may be necessary to associate some data with a secure object which can be used by the AccessController. For this purpose, ImGearARTPage / ImGearARTGroup / ImGearARTMark classes have the SecureObjectData property of ImGearARTSecureObjectData type.

Examples

Access Controller Implementation Example:

C# Example	Copy Code
class UserAccessToken : ImGearARTAccessToken { private ImGearARTAccessRights _accessRights; public UserAccessToken(ImGearARTAccessRights accessRights) { _accessRights = accessRights; } public ImGearARTAccessRights UserRights { get { return _accessRights; } } } class SimpleAccessController : ImGearARTAccessController { public override ImGearARTAccessToken AccessToken { get; set; } protected override bool OnIsAccessAllowed(ImGearARTAccessRights accessRights) { UserAccessToken userAccessToken = this.AccessToken as UserAccessToken; if (userAccessToken != null) { // compare current User Access Rights and required rights return (userAccessToken.UserRights & accessRights) == accessRights; } return false; } protected override bool OnIsAccessAllowed( ImGearARTAccessRights accessRights, ImGearARTGroup group) { // allow access for any user to default Group, and disable access to other groups if (group.Name == "[Untitled]") return true; return false; } protected override bool OnIsAccessAllowed( ImGearARTAccessRights accessRights, ImGearARTMark mark) { UserAccessToken userAccessToken = this.AccessToken as UserAccessToken; if (userAccessToken != null) { // compare current User Access Rights and required rights return (userAccessToken.UserRights & accessRights) == accessRights; } return false; } }

C# Example

Copy Code

class UserAccessToken : ImGearARTAccessToken
{
    private ImGearARTAccessRights _accessRights;
    public UserAccessToken(ImGearARTAccessRights accessRights)
    {
        _accessRights = accessRights;
    }
    public ImGearARTAccessRights UserRights
    {
        get
        {
            return _accessRights;
        }
    }
}
class SimpleAccessController : ImGearARTAccessController
{
    public override ImGearARTAccessToken AccessToken
    {
        get;
        set;
    }
    protected override bool OnIsAccessAllowed(ImGearARTAccessRights accessRights)
    {
        UserAccessToken userAccessToken = this.AccessToken as UserAccessToken;
        if (userAccessToken != null)
        {
            // compare current User Access Rights and required rights
            return (userAccessToken.UserRights & accessRights) == accessRights;
        }
        return false;
    }
    protected override bool OnIsAccessAllowed(
        ImGearARTAccessRights accessRights, ImGearARTGroup group)
    {
        // allow access for any user to default Group, and disable access to other groups
        if (group.Name == "[Untitled]")
            return true;
        return false;
    }
    protected override bool OnIsAccessAllowed(
        ImGearARTAccessRights accessRights, ImGearARTMark mark)
    {
        UserAccessToken userAccessToken = this.AccessToken as UserAccessToken;
        if (userAccessToken != null)
        {
            // compare current User Access Rights and required rights
            return (userAccessToken.UserRights & accessRights) == accessRights;
        }
        return false;
    }
}

VB.NET Example	Copy Code
Class UserAccessToken Inherits ImGearARTAccessToken Private _accessRights As ImGearARTAccessRights Public Sub New(accessRights As ImGearARTAccessRights) _accessRights = accessRights End Sub Public ReadOnly Property UserRights() As ImGearARTAccessRights Get Return _accessRights End Get End Property End Class Class SimpleAccessController Inherits ImGearARTAccessController Public Overrides Property AccessToken() As ImGearARTAccessToken Get Return _accessToken End Get Set(value As ImGearARTAccessToken) _accessToken = value End Set End Property Private _accessToken As ImGearARTAccessToken Protected Overrides Function OnIsAccessAllowed(accessRights As ImGearARTAccessRights) As Boolean Dim userAccessToken As UserAccessToken = TryCast(Me.AccessToken, UserAccessToken) If userAccessToken IsNot Nothing Then ' compare current User Access Rights and required rights Return (userAccessToken.UserRights And accessRights) = accessRights End If Return False End Function Protected Overrides Function OnIsAccessAllowed(accessRights As ImGearARTAccessRights, group As ImGearARTGroup) As Boolean ' allow access for any user to default Group, and disable access to other groups If group.Name = "[Untitled]" Then Return True End If Return False End Function Protected Overrides Function OnIsAccessAllowed(accessRights As ImGearARTAccessRights, mark As ImGearARTMark) As Boolean Dim userAccessToken As UserAccessToken = TryCast(Me.AccessToken, UserAccessToken) If userAccessToken IsNot Nothing Then ' compare current User Access Rights and required rights Return (userAccessToken.UserRights And accessRights) = accessRights End If Return False End Function End Class

VB.NET Example

Copy Code

Class UserAccessToken
    Inherits ImGearARTAccessToken
    Private _accessRights As ImGearARTAccessRights
    Public Sub New(accessRights As ImGearARTAccessRights)
        _accessRights = accessRights
    End Sub
    Public ReadOnly Property UserRights() As ImGearARTAccessRights
        Get
            Return _accessRights
        End Get
    End Property
End Class
Class SimpleAccessController
    Inherits ImGearARTAccessController
    Public Overrides Property AccessToken() As ImGearARTAccessToken
        Get
            Return _accessToken
        End Get
        Set(value As ImGearARTAccessToken)
            _accessToken = value
        End Set
    End Property
    Private _accessToken As ImGearARTAccessToken
    Protected Overrides Function OnIsAccessAllowed(accessRights As ImGearARTAccessRights) As Boolean
        Dim userAccessToken As UserAccessToken = TryCast(Me.AccessToken, UserAccessToken)
        If userAccessToken IsNot Nothing Then
            ' compare current User Access Rights and required rights
            Return (userAccessToken.UserRights And accessRights) = accessRights
        End If
        Return False
    End Function
    Protected Overrides Function OnIsAccessAllowed(accessRights As ImGearARTAccessRights, group As ImGearARTGroup) As Boolean
        ' allow access for any user to default Group, and disable access to other groups
        If group.Name = "[Untitled]" Then
            Return True
        End If
        Return False
    End Function
    Protected Overrides Function OnIsAccessAllowed(accessRights As ImGearARTAccessRights, mark As ImGearARTMark) As Boolean
        Dim userAccessToken As UserAccessToken = TryCast(Me.AccessToken, UserAccessToken)
        If userAccessToken IsNot Nothing Then
            ' compare current User Access Rights and required rights
            Return (userAccessToken.UserRights And accessRights) = accessRights
        End If
        Return False
    End Function
End Class

Access Controller usage Example:

C# Example	Copy Code
void Example() { // View (read-only) access rights UserAccessToken user1 = new UserAccessToken(ImGearARTAccessRights.View); // View & Edit & Create (Edit right does not include Move & Resize) rights UserAccessToken user2 = new UserAccessToken( ImGearARTAccessRights.View & ImGearARTAccessRights.Edit & ImGearARTAccessRights.Create); // create art page and access controller ImGearARTPage artPage = new ImGearARTPage(); artPage.AccessController = new SimpleAccessController(); // switch access controller to user1 artPage.AccessController.AccessToken = user1; try { // try to add mark ImGearARTLine line = new ImGearARTLine( new ImGearPoint(), new ImGearPoint(), new ImGearRGBQuad()); // Access Denied exception is thrown, because 'user1' // does not have 'Create' right artPage.AddMark(line, ImGearARTCoordinatesType.DEVICE_COORD); } catch (ImGearARTAccessDeniedException) { } // switch access controller to user2 artPage.AccessController.AccessToken = user2; ImGearARTLine line2 = new ImGearARTLine( new ImGearPoint(), new ImGearPoint(), new ImGearRGBQuad()); // OK, 'user2' has Create right artPage.AddMark(line2, ImGearARTCoordinatesType.DEVICE_COORD); }

C# Example

Copy Code

void Example()
{
    // View (read-only) access rights
    UserAccessToken user1 = new UserAccessToken(ImGearARTAccessRights.View);
            
    // View & Edit & Create (Edit right does not include Move & Resize) rights
    UserAccessToken user2 = new UserAccessToken(
        ImGearARTAccessRights.View & 
        ImGearARTAccessRights.Edit & 
        ImGearARTAccessRights.Create);
    // create art page and access controller
    ImGearARTPage artPage = new ImGearARTPage();
    artPage.AccessController = new SimpleAccessController();
    // switch access controller to user1
    artPage.AccessController.AccessToken = user1;

    try
    {
        // try to add mark
        ImGearARTLine line = new ImGearARTLine(
            new ImGearPoint(),
            new ImGearPoint(),
            new ImGearRGBQuad());
        // Access Denied exception is thrown, because 'user1' 
        // does not have 'Create' right
        artPage.AddMark(line, ImGearARTCoordinatesType.DEVICE_COORD);
    }
    catch (ImGearARTAccessDeniedException)
    {
    }
    // switch access controller to user2
    artPage.AccessController.AccessToken = user2;
    ImGearARTLine line2 = new ImGearARTLine(
        new ImGearPoint(), new ImGearPoint(), new ImGearRGBQuad());
    // OK, 'user2' has Create right
    artPage.AddMark(line2, ImGearARTCoordinatesType.DEVICE_COORD);
}

VB.NET Example	Copy Code
Private Sub Example() ' View (read-only) access rights Dim user1 As New UserAccessToken(ImGearARTAccessRights.View) ' View & Edit & Create (Edit right does not include Move & Resize) rights Dim user2 As New UserAccessToken(ImGearARTAccessRights.View And ImGearARTAccessRights.Edit And ImGearARTAccessRights.Create) ' create art page and access controller Dim artPage As New ImGearARTPage() artPage.AccessController = New SimpleAccessController() ' switch access controller to user1 artPage.AccessController.AccessToken = user1 Try ' try to add mark Dim line As New ImGearARTLine(New ImGearPoint(), New ImGearPoint(), New ImGearRGBQuad()) ' Access Denied exception is thrown, because 'user1' ' does not have 'Create' right artPage.AddMark(line, ImGearARTCoordinatesType.DEVICE_COORD) Catch generatedExceptionName As ImGearARTAccessDeniedException End Try ' switch access controller to user2 artPage.AccessController.AccessToken = user2 Dim line2 As New ImGearARTLine(New ImGearPoint(), New ImGearPoint(), New ImGearRGBQuad()) ' OK, 'user2' has Create right artPage.AddMark(line2, ImGearARTCoordinatesType.DEVICE_COORD) End Sub

VB.NET Example

Copy Code

Private Sub Example()
    ' View (read-only) access rights                                                                                            
    Dim user1 As New UserAccessToken(ImGearARTAccessRights.View)
    ' View & Edit & Create (Edit right does not include Move & Resize) rights                                                   
    Dim user2 As New UserAccessToken(ImGearARTAccessRights.View And ImGearARTAccessRights.Edit And ImGearARTAccessRights.Create)
    ' create art page and access controller                                                                                     
    Dim artPage As New ImGearARTPage()
    artPage.AccessController = New SimpleAccessController()
    ' switch access controller to user1                                                                                         
    artPage.AccessController.AccessToken = user1

    Try
        ' try to add mark                                                                                                       
        Dim line As New ImGearARTLine(New ImGearPoint(), New ImGearPoint(), New ImGearRGBQuad())
        ' Access Denied exception is thrown, because 'user1'                                                                    
        ' does not have 'Create' right                                                                                          
        artPage.AddMark(line, ImGearARTCoordinatesType.DEVICE_COORD)
    Catch generatedExceptionName As ImGearARTAccessDeniedException
    End Try
    ' switch access controller to user2                                                                                         
    artPage.AccessController.AccessToken = user2
    Dim line2 As New ImGearARTLine(New ImGearPoint(), New ImGearPoint(), New ImGearRGBQuad())
    ' OK, 'user2' has Create right                                                                                              
    artPage.AddMark(line2, ImGearARTCoordinatesType.DEVICE_COORD)
End Sub