The Authorization Handler

The Authorization Handler provides the capability to check that the current user (the security principal for the current thread) has the requisite permission to access the selected object method or property. This handler uses the Security Application Block and takes advantage of the features that it exposes.

The Authorization Handler applies the security check before invocation of the selected method or setting of the selected property of the target object. If the current user does not have permission to access the method or property accessor, the Authorization Handler aborts execution of the pre-processing handler pipeline and does not invoke the method or set the property. It also generates a UnauthorizedAccessExceptionand packages it into the message passed back to the previous handler in the chain.

Behavior of the Authorization Handler

In more detail, the Authorization Handler does the following:

• It reads the type of Authorization Provider to use from the Policy Injection Application Block configuration, which maps to a configured Authorization Provider instance.
• It reads the OperationName property as a string, which may contain tokens for contextual items such as the type or method name (see the following section for a full list) from the Policy Injection Application Block configuration.
• It calls the specified Authorization Provider using the current thread principal when the handler is invoked.
• If the authorization succeeds, it allows the next handler to execute.
• If the authorization fails, it returns an UnauthorizedAccessException to the caller and does not allow the next handler to execute.

Configuration Settings of the Authorization Handler

The following configuration settings are available for the Authorization Handler:

• AuthorizationProvider (String). This is the name of the Authorization Provider instance the Authorization Handler will use, as configured in the Security Application Block.
• OperationName (String). This is the name of the authorization operation (rule) the Authorization Handler will use, and which may include the following tokens:
  • {method}
  • {type}
  • {namespace}
  • {assembly}
  • {appdomain}

The next procedure describes how to configure the Authorization Handler using the Configuration Console or the Visual Studio 2005 Configuration Editor.

To configure the Authorization Handler

1. If you have not already added the Security Application Block to the configuration of your application, do this first. You must add at least one rule provider to the Authorization section of the Security Application Block to use the Authorization Handler with the Policy Injection Application Block. For details about configuring rule providers, see Entering Configuration Information in the documentation for the Security Application Block.
2. Right-click the Handlers node in the Enterprise Library Configuration Console or Visual Studio Configuration Editor, point to New, and then click Authorization Call Handler.
3. In the right pane of the Enterprise Library Configuration Console, or in the Visual Studio Properties window, select the Name property, and then change the default name to the name you want to use for the new handler.
4. Select the AuthorizationProvider property, and then select the authorization provider you want to use from the list. The list shows the rule providers you previously configured for the Security Application Block.
5. Select the OperationName property and enter the name of the rule to use for authorizing users. The operation name defines the rule already configured for the Security Application Block (in the Rule Providers section). You can use the tokens {method}, {type}, {namespace}, {assembly}, and {appdomain} to pass dynamic values from the current call that select the appropriate rule.

Attribute-based Targeting with the Authorization Handler

The following code shows the use of the [AuthorizationCallHandler] attribute on a simple method. This attribute can also decorate the class declaration, in which case it applies to all members of that class. The operation name is a mandatory parameter.

[AuthorizationCallHandler("operation-name")]
public void Deposit(decimal depositAmount)
{
  balance += depositAmount;
}

<AuthorizationCallHandler("operation-name")> _
Public Sub Deposit(Decimal depositAmount)
  balance += depositAmount
End Sub

Table 1 describes the properties of the AuthorizationCallHandlerAttributeclass.

Table 1: Properties of the AuthorizationCallHandlerAttribute Class

To set these properties using an attribute, add them as parameters to the attribute declaration, as shown in the following code.

[AuthorizationCallHandler(OperationName="operation-name", 
                           ProviderName="provider-name")]

<AuthorizationCallHandler(OperationName:="operation-name", _
                           ProviderName:=" provider-name ")>