The Authorization Handler

Retired Content
This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
The latest Enterprise Library information can be found at the Enterprise Library site.

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 UnauthorizedAccessException and 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}
• Order (Integer). This value specifies the position of the handler within the policy handler chain. The default value is zero, which means that there is no explicit order specified for the handler in relation to other handlers in the same handler chain. To specify an explicit order, set the Order property for each handler starting from 1. If you specify the same value for the Order property of two handlers in the same policy, the application block will add them to the policy handler chain in the order defined in the configuration.

The next procedure describes how to configure the Authorization Handler using the Configuration Console or the Visual Studio 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.
6. (Optional) Enter a numeric value for the Order property if you want to specify the position of the handler within the policy handler chain. Set the Order property for each handler starting from 1.

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 be applied to 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;
}

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

The following table describes the properties of the AuthorizationCallHandlerAttribute class.

Property	Description
OperationName	String. The name of the authorization operation, which may include the tokens {method}, {type}, {namespace}, {assembly}, and {appdomain}.
ProviderName	String. The name of the authorization provider instance to use, as configured in the Security Application Block.
Order	Integer. The position of the handler within the policy handler chain, starting from 1. The default value is zero, which means that there is no explicit order specified for the handler in relation to other handlers in the same handler chain.

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")]

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