ImageGear .NET v25.2 - Updated
Developer Guide / How to Work with... / ART Mark Annotations / Annotation Security
In This Topic
    Annotation Security
    In This Topic

    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;
        }
    }
    
    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);
    }
    
    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