Kabel .NET : Documentation : How Kabel .NET works

Walkthroughs: How Kabel .NET works
Open this document in seperate window

In this document:
Kabel .NET: An HTTP Module for ASP.NET
Implementing Your Authentication Code
The Authentication Cache
A Common Event Model
Configuration Options

Kabel .NET: An HTTP Module for ASP.NET

As an extension to ASP.NET, Kabel .NET is designed as a modular component to allow for the easy implementation of your own custom authentication code and mechanism. It is implemented as an HTTP Module that intercepts client requests and performs the necessary security checks before they reach the core of your web application for actual further processing.

Implementing Your Authentication Code

Kabel .NET offers two ways for implementing your custom authentication code:

Basic: You capture and process the Module's Authenticate event in the global.asax of your web application and return the needed authentication information (see code requirements below)
Advanced: You inherit a class from the base Module and override the AuthenticateUser method;
Other functionality may be overriden as well - see below for details.

Click below to see sample code:

Basic

Advanced

... or browse the implementation walkthroughs:

Basic

Advanced

Code Requirements

When a request comes in, Kabel .NET will call your custom code according to the following procedure:

Kabel .NET calls your Code, passing in a plain-text Username
Your Code must verify that the Username is valid by itself
(Does it exist in your database at all? Or is it completely unknown?)
If Step 2 passes, your code must return the clear-text passwordassociated with that username.
Kabel .NET will now perform the necessary hashing of password and additional request data, as described in the HTTP Digest specification.
Additionally, you may also return a custom IPrincipal User object to be directly associated with the authenticated request.
Note: Even your code confirms the username (in Step 2) and even returns a valid IPrincipal (in 5), authentication can still fail in Step 4, if Kabel .NET determines that the Client used a different (bad) password than you have specified in Step 3.

This basic design aspect is crucial due to the basic nature of HTTP Digest communication. Because the Server cannot decrypt the credentials passed by the Client but can only verify them by applying the same irreversible algorithm to the credentials it has stored for the known username, your implementation must return a clear-text password for a given username. Whether or not the password passed by the Client was in fact valid can only be determined by Kabel .NET’s internal processing, as it involves the strict adherence to the HTTP Digest specification in combination with cryptographic hash calculations.

Overriding Base Functionality

As explained above, you can freely derive from the Kabel .NET HTTP Module to extend and customize its functionality while relying on its core logic for standardized HTTP Digest processing. For example, you could easily overwrite its ticket generation and validation functions to implement your own scheme of security checking.

The Helper Classes

The Kabel .NET implementation also contains a special Helper Class (DigestHelper), which you can use from your code for common tasks related to Digest User authentication – such as the encoding/decoding and signing/verifying of custom tickets, the calculation of MD5 and server-keyed SHA1 hashes, and many other such support functions. As a developer, you also have access to an info structure DigestHeader that contains all the specific HTTP Digest parameters for each client request.

The Authentication Cache

Because your code needs to return the valid password for each client request (even if the Client has been authenticated in previous requests), the processing burden for the necessary lookups (database for example) may be quite high.
Here, Kabel .NET offers a simple but effective solution by implementing a password cache. Kabel .NET can thus be easily configured to cache a verified password together with the associated username after the first time it has been successfully authenticated. When the Client makes subsequent requests, Kabel .NET can short-cut the processing pipeline and retrieve the password from the cache without calling your code again until the cache expires (the expiration time is freely configurable). This saves repeated lookups and can provide significant performance and scalability gains.

Rejected Username Cache

Additionally, the Module can be set to maintain a cache of rejected usernames that your code has explicitly returned as invalid (possibly because the usernames do not exist in your database or because the accounts are disabled). If a request comes in with a matching username in the cache, Kabel .NET can immediately reject the request and prevent resources from being spent on unnecessary processing.

Both of these Caches internally rely on the underlying ASP.NET caching architecture and are thus light-weight and scalable.

A Common Event Model

Besides calling your code for authentication, the Module exposes two additional global events AuthenticationSuceeded and AuthenticationFailed. They can be captured in the global.asax file your application and you can use them to further customize security processing.

Configuration Options

Kabel .NET offers several advanced configuration options which you can specify according to your security needs.
See About HTTP Digest, Tickets in Kabel .NET for more information on 'tickets.'

Ticket Timeouts
One-Time Tickets and limited Re-Use Counts
Resource-Dependent Tickets
Specify a common machineKey for ticket validation to be used in Web Farm/multi-server environments