Constable Authorization Engine 2.0 BETA

AuthorizationPolicy.ResolveRoleMembership Event

[This is preliminary documentation and subject to change.]

The event is raised as part of the role resolution process.

[Visual Basic]
Public Event ResolveRoleMembership As ResolveRoleMembershipEventHandler
[C#]
public event ResolveRoleMembershipEventHandler ResolveRoleMembership;

Event Data

The event handler receives an argument of type ResolveRoleMembershipEventArgs containing data related to this event. The following ResolveRoleMembershipEventArgs properties provide information specific to this event.

Property Description
IsResolved Sets or returns a value specifying whether the event handler resolved the role membership.
IsRoleMember Sets or returns a flag specifying whether the IPrincipal associated with the event is member of the Role associated with the event.
Principal Returns the IPrincipal reference whose membership in the role specified by the Role property should be determined.
Role Returns a reference to the Role for which the membership of the principal specified by the Principal property should be determined.

Remarks

CAUTION If there are multiple handlers of this event, the last one that explicitly sets the IsResolved property to true will ultimately provide the outcome of the role resolution process.
The ResolveRoleMembership event handlers are not serialized along with the policy. This means that if you're transferring policies across AppDomain or machine boundaries, the event handlers won't be marshaled and used in the remote domain.

Example

The following example illustrates how to use the ResolveRoleMembership the event to 'override' normal role resolution process and to allow any principal to be handled as member of any role (regardless of the actual role membership):

[Visual Basic]
Imports System
Imports System.Diagnostics
Imports System.Security.Principal

Imports LaMarvin.Constable
Imports LaMarvin.Constable.Model
Imports LaMarvin.Constable.Principal

''' 
''' The class illustrates usage of the ResolveRoleMembership
''' event that is raised by the AuthorizationPolicy class while
''' evaluating the policy.
''' 
Public Class ResolveRoleMembershipEvent

  ''' 
  ''' Represents the entry point of the application.
  ''' 
  Public Shared Sub Main()
    ' Populate a very simple policy with one state, role, action
    ' and action rule.
    Dim policy As New AuthorizationPolicy
    policy.States.AddNew("Default")
    policy.Roles.AddNew("User")
    policy.Actions.AddNew("Logon")

    ' The following statement grants the User role persmission to
    ' execute the Logon action (in the Default state, which is implicit in this case).
    policy.ActionRules.AddNew("Logon", "User")

    ' Now we'll set up the authorization context: the current state is already
    ' set to the sole Default state and we'll associate the policy with an 
    ' generic principal without roles.
    policy.CurrentPrincipal = New GenericPrincipal(New GenericIdentity("Joe"), Nothing)

    ' Because the principal has no roles, the Logon action should be disabled.
    Debug.Assert(Not policy.IsActionExecutable("Logon"))

    ' Now we'll handle the ResolveRoleMembership event and always mark the passed-in
    ' role as belonging to the current principal.
    AddHandler policy.ResolveRoleMembership, AddressOf policy_ResolveRoleMembership

    ' Our ResolveRoleMembership handler ensures that any principal is member of any
    ' defined role, so the Logon action is now permitted.
    Debug.Assert(policy.IsActionExecutable("Logon"))
    policy.ExecuteAction("Logon")
  End Sub

  ''' 
  ''' Handles the ResolveRoleMembership event. Always indicates that the passed-in role
  ''' belongs to the current principal.
  ''' 
  Private Shared Sub policy_ResolveRoleMembership(ByVal sender As Object, ByVal e As ResolveRoleMembershipEventArgs)
    e.IsResolved = True ' disable further role membership checks by the owning AuthorizationPolicy
    e.IsRoleMember = True  ' mark the current principal as member of the role.
  End Sub

End Class

[C#]
using System;
using System.Diagnostics;
using System.Security.Principal;

using LaMarvin.Constable;
using LaMarvin.Constable.Model;
using LaMarvin.Constable.Principal;

/// The class illustrates usage of the ResolveRoleMembership
/// event that is raised by the AuthorizationPolicy class while
/// evaluating the policy.
public class ResolveRoleMembershipEvent
{

  /// Represents the entry point of the application.
  public static void Main()
  {
    // Populate a very simple policy with one state, role, action
    // and action rule.
    AuthorizationPolicy policy = new AuthorizationPolicy();
    policy.States.AddNew("Default");
    policy.Roles.AddNew("User");
    policy.Actions.AddNew("Logon");

    // The following statement grants the User role persmission to
    // execute the Logon action (in the Default state, which is implicit).
    policy.ActionRules.AddNew("Logon", "User");
    
    // Now we'll set up the authorization context: the current state is already
    // set to the sole Default state and we'll associate the policy with an 
    // generic principal without roles.
    policy.CurrentPrincipal = new GenericPrincipal(new GenericIdentity("Joe"), null);

    // Because the principal has no roles, the Logon action should be disabled.
    Debug.Assert(!policy.IsActionExecutable("Logon"));

    // Now we'll handle the ResolveRoleMembership event and always mark the passed-in
    // role as belonging to the current principal.
    policy.ResolveRoleMembership += new ResolveRoleMembershipEventHandler(policy_ResolveRoleMembership);

    // Our ResolveRoleMembership handler ensures that any principal is member of any
    // defined role, so the Logon action is now permitted.
    Debug.Assert(policy.IsActionExecutable("Logon"));
    policy.ExecuteAction("Logon");
  }

  /// Handles the ResolveRoleMembership event. Always indicates that the passed-in role
  /// belongs to the current principal.
  private static void policy_ResolveRoleMembership(object sender, ResolveRoleMembershipEventArgs e)
  {
    e.IsResolved = true; // disable further role membership checks by the owning AuthorizationPolicy
    e.IsRoleMember = true;  // mark the current principal as member of the role.
  }

}

See Also

AuthorizationPolicy Class | LaMarvin.Constable Namespace