What Does the Security Application Block Do?

The Security Application Block allows you to perform two separate but related tasks. You can authorize users against a range of authorization providers, and/or cache a user's identity and security context for use throughout your application. The code required to use these features is simple, and the actual mechanics of accessing authorization systems and caching identities and security contexts are abstracted within the block. Often, you only need to write one line of code to perform common tasks. The following schematic shows the basic elements of the Security Application Block.

The Security Application Block exposes two interfaces that you can access in your code:

• An Authorization Provider interface, which exposes the single method named Authorize that takes an instance of an IPrincipal object containing details of the user's identity and roles. Depending on the way that you configure the block, the authorization can take place either through Windows® Authorization Manager (AzMan) against Active Directory, an XML file, or a database; or by using custom rules that you define and are stored as XML in the application configuration file.
• A Security Cache Provider interface, which exposes methods that allow you to save and retrieve a user's identity or security context as an IIdentity instance, IPrincipal instance, or ASP.NET Profile instance. Each cached identity or security context is identified by a token (by default a GUID, though you can create and use your own implementation of the IToken interface). The block stores this information in either a database or in Isolated Storage using the Caching Application Block. You can alternatively create a custom provider for the Caching Application Block and use it to cache the information in the location and using the techniques you implement in your provider.

Your application can use these interfaces to quickly and easily cache user identities and security contexts, obtain tokens that represent users, expire these users, and check if users are authorized to perform specific tasks or operations. However, to get the most from the block, you must understand the differences between the Windows IIdentity and IPrincipal interfaces and commonly used concrete implementations of these types.

An identity is represented by a concrete implementation of the IIdentity interface, usually a WindowsIdentity, GenericIdentity, PassportIdentity, or FormsIdentity depending on the authentication technique used. The IPrincipal interface provides the link between an identity and the roles for that identity. In ASP.NET, the current IPrincipal instance for a user is available from the HttpContext.User property. The methods that cache and retrieve user identity and security context accept an instance of a class that implements either the IIdentity or IPrincipal interface, or an ASP.NET Profile instance. For more information about Windows identities and security contexts, see Principal and Identity Objects and Role-Based Security on MSDN®.

Typical Usage of the Security Application Block

Some typical tasks that you may perform when using the Security Application Block in your applications are as follows:

• Collect user credentials information and authenticate the user. If you are not using a mechanism that automatically authenticates users and provides access to an IIdentity or IPrincipal instance, such as ASP.NET Membership, Windows Authentication, IIS certificate authentication, or a third party authentication mechanism, you may need to authenticate the user yourself. You can collect the user's credentials when the application starts, when a process starts, or when a user logs in. The credentials may be a user name and password, or some other type of credentials such as a certificate. After authenticating the user, you can generate an IIdentity instance such as a GenericIdentity for that user.
• Access the existing identity and security context. If your operating system or software does authenticate the user, you can obtain instances of the IIdentity and IPrincipal from the current User context. It is likely to be as a WindowsIdentity, GenericIdentity, PassportIdentity, or FormsIdentity instance. In ASP.NET, you can use the User property of the current HttpContext.
• Cache the authenticated IIdentity, IPrincipal, or ASP.NET Profile. The SaveIdentity, SavePrincipal, and SaveProfile methods return a token that represents the user's identity, which you can store and use throughout the lifetime of your application or the user's session. The default type of token is a GUID, and so you can store this in a range of ways such as in a variable in the application, in a string value in an encrypted browser cookie, or in the user's ASP.NET Session or ViewState objects. Alternatively, you can implement your own version of the IToken interface that exposes a token as a string value and pass an instance of this into the SaveIdentity, SavePrincipal, and SaveProfile methods. You can also use the token to combine identities, principals, and profiles stored in the cache.
• Retrieve the authenticated IIdentity, IPrincipal, or ASP.NET Profile. Use the GetIdentity, GetPrincipal, or GetProfile method to retrieve the identity, security context, or ASP.NET Profile for a user by passing in the appropriate token.
• Authorize the user or process when a resource is requested. Either access the current user context to get an existing IPrincipal instance, use the token you are holding for a user or process to retrieve the security context from the cache, or generate a new GenericPrincipal; then use it in a call the Authorize method to see if this user is authorized for a specific resource.
• Use the ExpireIdentity method when the user logs off to remove the identity and security context from the cache.

For more details of the ways you can use the Security Application Block, see Key Scenarios.

Example Application Code

The following code shows how to determine if a user is authorized to perform a task. It assumes that you resolve the class through the Enterprise Library container to populate the dependency on the default configured AuthorizationProvider instance.

public void ExampleScenario(IAuthorizationProvider ruleProvider)
{
  IPrincipal principal = new GenericPrincipal(new GenericIdentity("Username"),
                                              new string[]{"Manager"});

  // Determine whether user is authorized for the rule defined as "Print Document".
  bool authorized = ruleProvider.Authorize(principal, "Print Document");
}

'Usage
Public Sub ExampleScenario(ByVal ruleProvider As IAuthorizationProvider)
  Dim principal As IPrincipal = New GenericPrincipal(New GenericIdentity("Username"), _
                                                     New String() {"Manager"})

  ' Determine whether user is authorized for the rule defined as "Print Document".
  Dim authorized As Boolean = ruleProvider.Authorize(principal, "Print Document")
End Sub 

For information about resolving Enterprise Library objects in your applications, see Creating and Referencing Enterprise Library Objects.