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 |
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 |
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 |
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.
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 |