Thursday, November 29, 2007

Authenticating Users with ASP.NET AJAX

ASP.NET 2.0 provides built-in membership management capabilities that allow applications to log users into and out of a Web site with minimal coding. Simply run the aspnet_regsql.exe tool to add Microsoft's membership database into your chosen database server (otherwise, a SQL Server 2005 Express database will be used), add a few lines of configuration code in web.config to point to your database, drag on a few controls such as the Login and CreateUserWizard controls, and you're ready to go!

However, each time a user logs in to your application, a postback operation occurs which, in some situations, may not be desirable. In cases where you'd like to log users into a Web site without performing a complete postback of a page, you can use the ASP.NET AJAX authentication service instead.

The authentication service consists of a service that lives on the Web server that accesses membership information from the database, as well as a client-side class named AuthenticationService (located in the Sys.Services namespace) that is built into the ASP.NET AJAX script library. The AuthenticationService class knows how to call the membership service using the XmlHttpRequest object behind the scenes.
To use the AuthenticationService class to log users in or out of a Web site, you must first enable the authentication service on the server. This is done by adding code into web.config as shown below.

NOTE: instead of '<' symbol i have used '[' and for '>' I have used ']' symbol.

[authenticationService enabled="true" /]

This code enables calls to a file named _AppService.axd to be made behind the scenes and allows membership credentials to be passed and validated. _AppService.axd doesn't actually exist as a physical file; it's really an alias for an HttpHandler named ScriptResourceHandler that's responsible for handling log-in and log-out functionality within ASP.NET AJAX applications. ScriptResourceHandler is configured automatically when you create an ASP.NET AJAX-enabled Web site in Visual Studio .NET 2005, as shown in the following code:

[add verb="*" path="*_AppService.axd" validate="false"
type="System.Web.Script.Services.ScriptHandlerFactory, System.Web.Extensions,
Version=1.0.61025.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35"/]

Once you've enabled the ASP.NET AJAX authentication service in web.config you can use the client-side AuthenticationService class to log users into a Web site using an asynchronous postback operation. The AuthenticationService exposes login() and logout() methods, as well as several different properties.

1 defaultFailedCallback : Gets or sets the default failure callback method.
2 defaultLoginCompletedCallback: Gets or sets the default login callback method.
3 defaultLogoutCompletedCallback: Gets or sets the default logout callback method.
4 isLoggedIn : Used to determine if the user is currently logged into the application or not.
5 path : Gets or sets the authentication service path.
6 timeout : Gets or sets the authentication service time-out value.

The AuthenticationService's login() method performs an asynchronous postback operation that calls the ScriptHandlerFactory HttpHandler mentioned earlier to log a user into a Web site. The overall process still involves setting a cookie containing the ASP.NET membership authentication ticket in it as with standard ASP.NET applications, but the cookie is set without reloading the entire page. The login() method accepts several different parameters, as shown here:

1 userName The user name to authenticate.
2 password User password to use while authenticating.
3 isPersistent Determines if the issued authentication ticket should be persistent across
browser sessions. The default is false.
4 customInfo Reserved by Microsoft for future use. Defaults to null.
5 redirectUrl The URL to redirect the browser to on successful authentication. If null, no
redirect occurs. The default is null.
6 loginCompletedCallback The method to call when the login has finished successfully. The
default is null.
7 failedCallback The method to call if the login fails. The default is null.
8 userContext User context information that you are passing to the callback methods.

You can see that login() takes quite a few parameters, although several of them are optional. The key parameters are userName, password and loginCompletedCallback.

the AuthenticationService's login() method to attempt to log a user into a Web site. The code first calls the AuthenticationService class's login() method and passes in the user name, password, log-in completed callback handler and failure handler.

If the log-in attempt completes successfully, the method named OnLoginCompleted() is called. You know if the user successfully logged in or not by checking the isValid parameter. If the log-in attempt fails due to the service being unavailable or other circumstances, the OnLoginFailure() method is called, letting the user know that they're not able to log in at this time.

To log a user out of a Web site, you can call the AuthenticationService's logout() method. Be aware that this method will cause a full-page postback operation to occur to ensure that the authentication cookie is properly removed from the user's browser. This is standard behavior, so don't waste any time trying to figure out why an asynchronous postback isn't occurring. Parameters that the logout() method accepts are shown here:

1 redirectUrl The URL to redirect the browser to on successful logout. The default is null.
2 logoutCompletedCallback The method that is called when the logout has finished. The default
is null.
3 failedCallback The method that is called if the logout has failed. The default is null.
4 userContext User context information that you are passing to the callback methods.

Calling the logout() method to remove the authentication cookie from the users browser and log them out of a Web site. It defines a log-out completed callback method, as well as a failure callback method.

No comments: