Walkthroughs: Advanced

C# and VB.NET Code is available when installing the Samples package
Open this document in seperate window

In this walkthhrough, you will:

• Derive from the Kabel .NET base class to implement your specific authentication
• Survey further possibilities of customizing and overriding base functionality
• Take a look at the built-in helper functions
• Enable your new class for your ASP.NET Web Application
• Explore Kabel .NET's Authentication Event Model
• Test it all using a simple ASP.NET Web Service and Internet Explorer

The more advanced possibility to implement Kabel .NET is to derive from the base HTTP Module and override its authentication functionality. From a developer's perspective, this gives you more control over the internals of your HTTP pipeline processing and it also allows you to customize other, more advanced Kabel .NET features, such as ticket generation and validation.

As with the basic implementation method, your code must provide an implementation for the authentication mechanism, which will then be called by the base Kabel .NET module.
Specifically, the HTTP Module (Type: uthentic.Web.Security.HttpDigest.DigestAuthenticationModule)
exposes the protected virtual (Overrideable) AuthenticateUser method for this purpose.

When called, your implementation of this function will need to validate the given username (return true) and supply the stored password associated with it - or reject the username if it is unknown or otherwise invalid (for example, if the associated account is disabled). See How Kabel .NET works to better understand this concept.

Getting Started

Before anything, two basic things need to be taken care of:

Overriding IIS Security settings

Lastly, it is necessary to disable the Integrated Windows authentication of IIS, because otherwise IIS will attempt to authenticate your HTTP Digest clients, which will only fail. Follow these simple steps:

1. Open your IIS Virutal Directory settings and go to the Directory Security tab

2. Click Edit... and the upcoming dialog, uncheck Integrated Windows Authentication

Adding a Reference to the global Kabel .NET assembly

You will need to do add a reference to the Kabel .NET assembly, which contains the necessary classes that you will be using in just a moment. To do this in Visual Studio .NET, simply follow these steps:

• Select Add Reference... from the Project (context) menu

• Select the Kabel .NET HTTP Digest Authentication for ASP.NET (1.0) component from the list.

Implement Your Code!

Now we are ready to get coding. We will override the AuthenticateUser method, which the Kabel .NET base module calls whenever it needs to authenticate a client request. Let's first set-up our own HttpModule class that inherits from the base module:

• [1] Here, we declare that our custom class MyAuthenticationModule should inherit from the Kabel .NET Base Module.
• [2] This is the basic function signature of AuthenticateUser that needs to be overriden.

The most important part: The Parameters

Let's disect the parameters of this function signature. As seen above,

Two parameters are always passed into the function:

• username - The Username of the Client who needs to be authenticated
• app - An instance of HttpApplicationInstance (which gives access to the intrinsic ASP.NET objects like Context, Response, Request, Server) associated with the current request

and three parameters (including the boolean return value) should be returned

• the basic return value (true / false)
  • Return true if the given Username is generally valid (i.e. the account exists and is not disabled for some reason)
  • Return false if the given Username is completely invalid (it does not even exist in your database, for example)

  If you are returning true above,
  then the following parameters MUST be specified before the function exits.

  • password - You must set this out / ByRef parameter to the password, which you have associated for the Client with the given Username
• user - This is an otional parameter is of type IPrincipal and will be associated with the current request so that it may later be accessed through the Context.User property during your ASP.NET processing. The following examples will clarify the use of this. It may be left unassigned (null / Nothing), in which case Kabel .NET will create a simple GenericPrinicipal instance if the User is successfully authenticated.

If you are returning false above, then set

• password = null / Nothing
• user = null / Nothing

Bringing it together

This methodology will become clear when looking at the next code snippet. It implements the most simple Username validation, but it does not require much imagination to see a more sophisticated authentication being implemented instead (such as database lookups, or perhaps querying an XML configuration files, etc.)

Nothing easier than that.

NOTE: With HTTP Digest, passwords are case-sensitive. This is an important detail on the client side.

Overriding other Module Methods

Authentication is not the only functionality that can be overriden for the Kabel .NET base module. You can use these other functions for greatest flexibility in your security and development needs. The following virtual (Overrideable) proctected methods are called by the base module in the sequence shown here.

Once per activated module instance:

1. Initialize (HttpApplication application) - Called once during the initial initialization of the HTTP Module and before the first request is processed; use it to initialize any data/objects specific to each instance of your custom module (Note: ASP.NET may create several instances of your module to process concurrent requests). You also have full read/write access to the configuration settings which will be used to initialize the Kabel .NET base module instance (via the HttpDigestConfiguration instance member; you could thus load a custom ticket validation key, for example, without specifying it in the web.config file...).

And then for each authentication request (in sequence as shown):

1. bool AuthenticateUser (...) - see above
2. If true is returned, processing continues:
   1. bool ValidateTicket (string ticket, HttpApplication app) - Overwrite this method and the GenerateNewTicket method to implement your own ticket validation;
   2. string GenerateNewTicket (HttpApplication application) - return your custom ticket string here.
   3. string GenerateOpaqueValue (HttpApplication application) - return your custom opaque value here;
      Only called if useOpaque is enabled in the configuration; see Configuring Kabel .NET for more details on Opaque values.

Using Built-In Helper Functions

All classes deriving from the Kabel .NET base Module have access to a number of protected member methods, which can be used to simplify advanced development tasks. Refer to the API Documentation for details.

Use the DigestHelper class

The additional DigestHelper class exposes several static helper methods to simplify common Authentication processing and also Hashing functions. Please see the Basic Walkthrough for an example of how to use it; to learn more about its feature set, refer to the API Documentation.

Access the current DigestHeader

DigestHelper exposes one particular method, called GetCurrentDigestHeader, which returns a DigestHeader info structure when given a valid HttpContext instance for the current request. The DigestHeader contains all the HTTP Digest-specific information and parameters pertaining to the current request; it is provided for advanced development purposes and can be called from anywhere within your code (except from within Initialize [see above], which is called before processing the first request). Refer to the API Documentation for details.

Final Steps: Enabling the new custom Module for the ASP.NET application

After you have implemented your custom module to handle Kabel .NET authentication, we need to specify a few minimum configuration settings in the web.config file of your ASP.NET application to enable the newly derived module.

• [3] <httpModule> This adds the module to ASP.NET request processing pipeline.
  • [3.1] name="HttpDigestModule"
    This "friendly" name given the Module here will be used when capturing module evetns in the global.asax file
  • [3.2] type="KabelAdvSample.MyDigestAuthentication, KabelAdvSample"
    Same as [1] above! This type attribute must point to your class (and its assembly) which inherited from the Kabel .NET base module.
• [4] <authentication> The ASP.NET authentication mode must be set to None to signal that a custom mechanism is employed.
• [5] <uthentic.HttpDigest> This section specifies any configuration options for the Kabel .NET module. As a minimum, the realm attribute is required; it uniquely identifies your web application to clients when they authenticate.

Additional Module Event Processing

Before jumping to the end, there is one more aspect about the Kabel .NET module that could be of interest to advanced developers and implementors: Like the built-in Authentication Modules of ASP.NET, Kabel .NET exposes two public events that are raised to indicate the outcome of a user's authetnication. Note that these events are available independently of your choice of implementation (Basic [via global.asax] or Advanced [via derived class, ie. this example]).

Module events are always captured in an application's global.asax file and in order to be hooked-up properly by the ASP.NET runtime, they must follow a certain naming pattern; see below for each event's specification.

AuthenticationSucceeded

The Kabel .NET base module will raise this event every time a user successfully authenticated to your application. For this to happen, these criteria must have been satisfied:

• Your Code returned that the Username was valid
• The Password you specified for this Username was the Password the Client used when making the HTTP Digest request (this is enforced by Kabel .NET's internal processing of the Digest Headers)

The following snippets illustrate the basic event handler signature:

When implementing the event handler, make sure that it is named as follows:
FriendlyName_AuthenticationSucceeded where FriendlyName is the name assigned to the Module in the <httpModule> section of your web.config file (here: MyHttpDigestModule), as specified in [3.1] above.

AuthenticationSucceededEventArgs (parameter e, above) exposes the following properties:

• e.Username - the Username (as passed by the Client and validated by you) of the successfully authenticated Client
• e.UsedCachedPassword (true/false) - Indicates whether the Kabel .NET used the Accepted Password Cache to authenticate the User
  (see How Kabel .NET Works, Authentication Cache)
• e.User - a reference to the IPrincipal User object to be associated with the current request.
  This is the value returned via the user parameter of your AuthenticateUser function (above);
  You may (re-)specify/override the object at this point.
• e.Context - An instance of HttpContext (which gives access to the intrinsic ASP.NET objects like Response, Request, Server) associated with the current request

If the User has been successfully authenticated (according to the above criteria) but the e.User property is still unassigned after the execution of the AuthenticateUser method and after this event completed, Kabel .NET will create a simple System.Security.Principal.GenericPrincipal user object for you, using the e.Username property as the identity's name.

AuthenticationFailed

The Kabel .NET base module will raise this event every time authentication for a request fails. Any one of the following criteria causes this to happen:

• Your Code returned that the Username was NOT valid
• The Password you specified for this Username was NOT the Password the Client used when making the HTTP Digest request

Use this event to customize the handling of bad requests and for advanced security auditing features.

NOTE: This event is not called when a Client ticket was stale / expired, as this does not indicate that the Client passed invalid credentials; rather, it means that the Client simply needs to re-authenticate using a new ticket. See About HTTP Digest, Tickets for more info.

The following snippets illustrate the basic event handler signature for AuthenticationFailed:

When implementing the event handler, make sure that it is named as follows:
FriendlyName_AuthenticationFailed where FriendlyName is the name assigned to the Module in the <httpModule> section of your web.config file (here: MyHttpDigestModule), as specified in [3.1] above.

AuthenticationFailedEventArgs (parameter e, above) exposes the following members:

• e.Username - the Username, which did not authenticate properly
• e.BadClientPassword (true/false) - false indicates that authentication failed because the Username was rejected by your code; true indicates that the username was valild, but the client used a wrong password.
• e.EndResponseWith401() - Allows you to short-cut the ASP.NET processing pipeline and deny the request immediately; no further processing will be done. The client will receive an HTTP 401 Access Denied message.
• e.Context - An instance of HttpContext (which gives access to the intrinsic ASP.NET objects like Response, Request, Server) associated with the current request

At last: Kabel .NET + Your Code in Action

So far, we have successfully

• Enabled Kabel .NET in an ASP.NET Web Application,
• Implemented a basic, custom authentication mechanism using an event handler in the global.asax,
• and taken a quick a look at the DigestHelper class!

This means, we are ready to see Kabel .NET in action. Let's create a simple Web Service, which will only be accessible to successfully authenticated users and return the name of the current user (i.e. "Administrator" or "MickeyMouse", as seen above). The following snippet defines our public WebMethod:

Let's call this serivce RestrictedWs.asmx, and since it is restricted, let's configure the application so that only authenticated will be able to call it.

ASP.NET supports a powerful configuration mechanism, which allows you to authorize users according to their verified identity, roles, etc. on a ressource-specific basis. (Authorization happens after successful Authentication; at this stage, an application determines whether the authenticated user actually has the permission to access a given ressource.)

You can restrict all of your Web Application to authenticated users, by using the web.config <authorization> tag. Alternatively, you can use the <location> tag to specify different access criteria for individual pages and services.

The following web.config snippet configures the application so that all pages are restricted to authenticated users using the <authorization> tag:

• [6] <deny users="?"> This means that all unknown (un-authenticated) users should be denied from the Web Application.

The next possible web.config code configures the application so that only RestrictedWs.asmx will be restricted; we are using the <location> tag:

• [7] <deny users="?"> This means that all unknown (un-authenticated) users should be denied when accessing the path RestrictedWs.asmx.

Let's Launch

Let's test our simple but secure application: Open up Internet Explorer and point it to the location of RestrictedWs.asmx on your web server. The following screenshots illustrate a simple access scenario:

1. When accessing the protected resource, Internet Explorer prompts for credentials.
   Notice the IBuySecurely identifier, as specified for the Web Application's Realm in [3] of the web.config file.

2. First, when entering bad credentials (Username: i-am-a-hacker), we are denied access:

3. Next, we try the accepted Username mickey with the password mouse-password. See there...

we're in!

4. The HelloCurrentUser method of the Service then returns the following user-dependent string:

5. Notice also that no additional re-authentication was required during the session; any possibly expired or stale tickets will be automatically renewed through the communication between Internet Explorer and Kabel .NET
6. See the HTTP Digest Client Side Walkthrough for an example of how to automate authentication in your client applications.

Feedback on Help
Copyright © 2002, uthentic.net
All Rights Reserved