Walkthroughs: Basic

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

In this walkthhrough, you will:

• Enable Kabel .NET for your web application
• Implement your own authentication code using the global.asax file
• Use the DigestHelper class
• Test it using a simple ASP.NET Web Service and Internet Explorer

With the Basic implementation method, your code will capture the HTTP Module’s Authenticate event using the global.asax file of your web application. You will need to validate the given username and respond with either the stored password or a notice that the username is invalid by itself (for example, if it does not exist or the associated account is disabled). See How Kabel .NET works to better understand this concept.

Getting Started: Enabling Kabel .NET

To jumpstart, let’s first specify the minimum configuration settings in the web.config file of your ASP.NET application to enable the Kabel .NET module.

• [1] <httpModule> This adds the Kabel .NET module to ASP.NET request processing pipeline.
  • [1.1] name="HttpDigestModule"
    This "friendly" name given the Module here will later be of importance when we code in the global.asax file
• [2] <authentication> The ASP.NET authentication mode must be set to None to signal that a custom mechanism is employed.
• [3] <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.

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 capture the Authenticate event, which the Kabel .NET module sends whenever it needs to authenticate a client request. This is done at the application level of in the global.asax file. The basic method body looks as follows:

When implementing the event handler, make sure that it is named as follows:
FriendlyName_Authentication where FriendlyName is the name assigned to the Module in [1.1] above.

The most important part: AuthenticationEventArgs

The AuthenticationEventArgs parameter (named e in the above snippet) passed into this method is your way of communicating with the underlying Kabel .NET module. This parameter exposes the following properties:

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

It also exposes two important methods, namely:

• e.UsernameAccepted ( storedPassword, [optional: IPrincipal user] ) - You must call this method to indicate that e.Username was valid and you must also specify which password the Client should have passed (storedPassword).
  The optional parameter user 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.
• e.UsernameRejected() - Alternatively, you must call this method if the Username was invalid. The requesting client will be denied.

Bringing it together

Now that the AuthenticationEventArgs is explained, let's look at how to use it. The following example 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.

Use the DigestHelper class

The uthentic.Web.Security.HttpDigest contains a class called DigestHelper, which exposes many useful functions related to Authentication and HTTP Digest processing. We will use it here to construct a simple User object that we will pass back into the e.UsernameAccepted method.

All methods of DigestHelper class are static / Shared; think of them as utility functions to simplify your development tasks. See the API Documentation for more information.

The User, which we thus assigned above, can later be used to identify the Client's identity within the code of ASP.NET WebForms and Web Services; it accessed via Context.User. To learn more about the Context.User object (Type: IPrincipal), check out the MSDN .NET Framework documentation. It can add significantly to your application logic by simplifying the identification, role assignments, and permissions of the current user within your code. Click here for a Google search that should always get you a working link to the official documentation.

To learn more about the functions available in the DigestHelper, please refer to the API Documentation.

At last: Kabel .NET 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 Restricted.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:

• [4] <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 Restricted.asmx will be restricted; we are using the <location> tag:

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

Let's Launch

Let's test our simple but secure application: Open up Internet Explorer and point it to the location of Restricted.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