Overview

The HTTP protocol is simple, effective, and ubiquitous, but it is not stateful. So two consecutive and logically related calls to the same URL (that is, a postback) are treated as independent calls, and for each of them a new and especially clean environment is created. To add some state and global data containment to Web applications, virtually all server-side runtime environments build an abstraction layer and provide additional services to applications. Common services for ASP.NET applications include session state, authentication, role management, caching, profiling and, in general, any operation that can manipulate an intrinsic ASP.NET object.

These application services are available only to server-side code and are not directly exposed to JavaScript; as such, they can’t be invoked directly from the client page. Despite their rich and advanced user-interface capabilities, ASP.NET AJAX applications are primarily ASP.NET applications. So they still need a way to use traditional ASP.NET application services, such as Forms authentication, session state management, server-side caching, user profiling, and role and membership information verification. In the native server environment of ASP.NET, developers find a number of facilities such as the HttpContext object (including its child objects Session, Cache, Profile, and User) and static service-specific classes to accomplish common tasks such as managing a profile or authenticating a user. But on the client?

ASP.NET AJAX Extensions wraps some of these base application services into JavaScript classes defined in the Microsoft AJAX library. (See Chapter 2, “The Microsoft Client Library for AJAX.”) Such wrapper classes expose server-side services through a number of built-in Web services, making services callable directly from the client.

In ASP.NET AJAX, you find client-side wrappers for two key and related server-side services: Forms authentication and user profiles.

Forms Authentication Services

To protect Web pages from unauthorized users, you place some boilerplate code on top of each page and redirect the user to a login page. On the login page, the user is prompted for credentials. Next, if successfully authenticated, the user is redirected to the originally requested page. Forms authentication is the ASP.NET built-in infrastructure that implements the aforementioned pattern for login.

Server-side Forms authentication requires an additional login page and two HTTP redirect commands. Can you authenticate directly from the client without any page redirection? You bet.

The System Infrastructure for Authentication

The infrastructure of AJAX-accessible ASP.NET services is made of two key components: a client-side JavaScript class and a server-side Web service. Authentication and user profile services are both implemented according to this model.

A JavaScript class provides you with methods to send credentials to a built-in Web service. You receive a Boolean answer that indicates whether or not the user has been authenticated. The Web service uses the server-side ASP.NET authentication and membership API to validate the user information.

By using a client JavaScript class to command a remote Web service, you authenticate users more quickly because you incorporate login forms into the home page of the site (or any pages a user would visit regularly) rather than force a redirect to a specialized login page.

The Client-Side Authentication Service Class

To verify the credentials that a user typed in a client-side login box, you invoke the methods of a class defined in the Microsoft AJAX Library. The class is named Sys.Services._AuthenticationService and, as the leading underscore in the name suggests, it should be considered private to the library. More importantly, the class is a singleton, meaning that it has only one instance with a global point of access. You don’t have to instantiate the _AuthenticationService class; you just use the global instance of it that is always available to your application and returned by the object named Sys.Services.AuthenticationService.

The global entry point is set in the Microsoft AJAX Library following the definition of the class. Here’s an excerpt from the source code:

Sys.Services.AuthenticationService = new Sys.Services._AuthenticationService();

The authentication service class features the methods listed in Table 6-1.

Table 6-2 details the properties defined on the object.

The Sys.Services._AuthenticationService class acts as a client-side proxy for the remote Web service. It inherits from a class named Sys.Net.WebServiceProxy that is the base class for any JavaScript proxy of a remote Web service. As we’ll see in Chapter 7, a class derived from Sys.Net.WebServiceProxy is generated on the fly for each ASP.NET Web service registered with the script manager. For the authentication Web service, this class is simply hard-coded in the Microsoft AJAX Library.

The Server-Side Authentication Web Service

The back end of the authentication service is implemented in the AuthenticationWebService class. The class is contained in the AJAX assembly within the System.Web.Security.AuthenticationService namespace. The AuthenticationWebService class is mapped to the following URL:

Authentication_JSON_AppService.axd

The URL points to an HTTP handler registered in the web.config file. The handler simply captures incoming requests, deserializes input parameters and method names, executes the call, and sends values back to the client in a JavaScript Object Notation (JSON) stream.

After the AJAX authentication service is enabled in the site configuration, any page served from the site includes the following script:

As you can see, a private member of the JavaScript _AuthenticationService class is set to the default path of the server Web service. However, by setting the path property via JavaScript, you can make the client invoke an authentication Web service elsewhere. The Web service, though, must support JSON and expose a contract identical to that of the _AuthenticationService class.

The Programming Interface of the Service

As you would expect, the AuthenticationWebService class features the same two methods-login and logout-that we have in the proxy client and with the same signatures. The login method, for example, has the following signature:

[WebMethod] public bool login( string userName, string password, bool createPersistentCookie)

The first two arguments (userName and password) set the credentials; the final Boolean argument indicates whether a persistent cookie is required. When you authenticate a user through Forms authentication, a cookie is created and attached to the response. This cookie is referred to as the authentication ticket, and its name defaults to .ASPXAUTH.

If you set the createPersistentCookie argument to false, the issued authentication ticket expires after 30 minutes. If you opt for a persistent cookie, the authentication ticket lasts as long as 50 years. What if you need a ticket timeout that falls in between 30 minutes and 50 years? You can simply set the timeout attribute in the section of the application’s web.config file to the desired number of minutes.

The login method of the Web service uses the following code to do its work:

if (Membership.Provider.ValidateUser(userName, password)) { FormsAuthentication.SetAuthCookie(userName, createPersistentCookie); return true; } return false;

As you can see, it validates using the current membership provider and sets the cookie using the SetAuthCookie method on the FormsAuthentication class. This means that most settings defined in the section of the configuration file are taken into proper account while creating the authentication ticket.

The logout method takes no arguments and simply removes the cookie from the response. Internally, the method ends up calling the SignOut method of the FormsAuthentication class.

Configuration of the Authentication Service

The ASP.NET AJAX authentication service requires you to set a few attributes in the application’s web.config file. In particular, you need to enable the service as follows:

Note that the service is disabled by default. A second attribute can be specified for the ticationService> node-the requireSSL Boolean attribute. Set to false by default, the attribute indicates whether a Secure Sockets Layer (SSL) connection is required to transmit the authentication cookie.

When SSL is not required, credentials are sent out as clear text. This is a known limitation of Forms authentication. If this is a concern to you, use SSL or Transport Layer Security (TLS) to secure your login page.

The section is located under a new AJAX-specific section:

<authenticationService enabled="true" /> ...

As you can see, the login method of the JavaScript class includes a few arguments beyond the user name and password. Let’s review the signature in detail. Table 6-3 lists the accepted parameters.

Only the user name and password are mandatory parameters and can’t be omitted. Note that for the the password field a value of null is acceptable. You can indicate two callbacks: one for a successful completion of the login process and one to use in case of failure. Here’s a possible implementation of a login-completed callback:

function onLoginCompleted(results) { // On success, there will be a Forms authentication cookie in the browser // Adjust the user interface to reflect the logged-in status of the user HandleLoginLogoutState(results); // Clean up the login form if (results) { username.value = ""; password.value = ""; } else { alert("Sorry, your credentials appear to be invalid. Try again."); } }

In ASP.NET AJAX, any JavaScript callback used to process the results of a remote Web service call has the following prototype:

function methodCompleted(results, context, methodName)

The results argument contains the return value of the Web service method, whereas context mirrors the contents of the userContext parameter of the login method. Finally, methodName indicates the name of the client-side method that triggered the callback. Of course, context and methodName arguments can be null.

The return value of the authentication Web service method is passed to the callback. In this case, it is a Boolean value indicating the result of the authentication.

You can handle the possible failure of a login operation by using a made-to-measure callback, as shown here:

function onLoginFailed(results, context, methodName) { alert("Login failed. <" + results.get_message() + ">"); }

In this case, the results parameter is the JavaScript transposition of the exception that was raised on the server. It is a JavaScript Error object with as many properties as the server-side exception object.

It should be noted, though, that the login-failed callback is triggered only if an exception occurs on the server while the credentials are being verified. If the credentials are simply invalid, no exception is thrown, a value of false is returned to the client, and the login-failed callback isn’t invoked.

The Logout Process

Figure 6-2 shows the HTTP request and response for a login attempt. (The tool in the figure is Web Development Helper, which we briefly discussed in Chapter 4, “Partial Page Rendering.”) As you can see, the HTTP response contains an additional cookie, named .ASPXAUTH. That is exactly the authentication ticket issued on the server and delivered to the client. From now on, the user can access any secured pages in the application until the ticket expires.

Figure 6-2: The HTTP response for a call to the login method on the authentication service

To give users a chance to log out directly from the client, you add another button to your client user interface and bind it to the following JavaScript code:

function Logout() { Sys.Services.AuthenticationService.logout(onLogoutCompleted); return false; }

When this function returns, the HTTP response looks like the one shown in Figure 6-3.

Figure 6-3: The HTTP response for a call to the logout method on the authentication service

The .ASPXAUTH cookie now has an empty body and can no longer be used to enable access to the secured pages of the application.

Typical User Interface Enhancements

Any applications based on authentication services should provide optional user interface (UI) elements to welcome the logged-in user and give her a chance to log out. In addition, some pages might also include conditional controls that show up only if the current request is authenticated. How would you know whether the current request is authenticated?

In classic ASP.NET, you simply check the Request.IsAuthenticated property in Page_Load or wherever else you need to know it. In ASP.NET AJAX, things will be slightly different.

When the JavaScript login method returns, you know whether or not the current user is authenticated. Suppose that the user navigates to another page in the application and then clicks the Back button or any link that returns the user to the original page. Once back to the original page, the user’s browser will have lost any information about the authentication status-in the end, the authentication status was simply the value of a JavaScript global variable. If not properly designed, the user interface might show that the user is not logged in, while the authentication module correctly handles her further requests for secured pages. Let’s consider a block of user interface code that displays the name of the logged-in user:

Hey,   

Not logged in

The first

will be used when any user is logged in; the second block comes in handy when no user is connected. You toggle them based on the result of the login method and the authentication status of the request. To facilitate this, add the following code to the Page_Load event of the code file:

protected void Page_Load(object sender, EventArgs e) { if (Request.IsAuthenticated) { LoggedIn.Style["display"] = String.Empty; NotLoggedIn.Style["display"] = "none"; LoggedUser.Text = User.Identity.Name; // Show any UI element specific to registered users ... } else { LoggedIn.Style["display"] = "none"; NotLoggedIn.Style["display"] = ""; LoggedUser.Text = ""; // Hide any UI element specific to registered users ... } }

The code ensures that UI elements are correctly initialized when the page first loads and every time the page is refreshed, loaded through a link, or loaded via the Back/Forward buttons. In addition, you will need to extend the client-side onLoginCompleted and onLogoutCompleted callback functions to update the user interface dynamically as the user connects or disconnects directly from the page. For example, you can use the following function:

You can call the HandleLoginLogoutState function from both onLoginCompleted and onLogoutCompleted by passing true and false, respectively.

If the user has been successfully authenticated, you clear the user interface of the login form and enable the secured portions of the page. (See Figure 6-4.)

Figure 6-4: A typical user interface when the current user is logged in

Design Guidelines for Protected Resources

In ASP.NET, to guarantee that protected resources (for example, Web pages) are exclusively accessed by authorized users, you place them in a site folder controlled by a modified version of the web.config file. The configuration file requires that a valid authentication ticket is presented by requests aimed at any of the resources. From a UI perspective, you might or might not apply special measures to let users know about the requirements of a protected page. You can leave any links to such pages visible and active; if the user clicks, the system infrastructure blocks any unauthorized access.

More precisely, if the user follows the link to a protected page, ASP.NET first attempts to locate the authentication ticket. If no valid ticket is found, the user is automatically redirected to the configured login page. This behavior is good enough for classic ASP.NET pages; it’s not a solution for AJAX-enabled sites. The redirect, in fact, will break the continuity between users and applications that is a characteristic of AJAX applications.

Although there’s no way to prevent users from typing the URL of a protected page on the address bar-in that case, a full page reload is inevitable-there are two possible approaches to prevent users from blindly navigating to protected URLs from within the current page. You can hide links to protected pages, or you can add some script code to buttons to enable the operation only if the user is currently logged in. To hide protected resources to unauthenticated users, you set cascading style sheet (CSS) style attributes as shown in the preceding code snippet. To dynamically verify the status of the current user, you attach some script to the user interface element as shown here:

<a href="securedlistinvoices.aspx" onclick="return checkFirst()"> View invoices (Must be logged in) </a>

Next, you write a JavaScript function that checks the logged-in status and prevents the default action if the user is not authenticated:

function checkFirst() { var loggedIn = Sys.Services.AuthenticationService.get_isLoggedIn(); if (!loggedIn) { alert("You must be logged in to follow this link"); return false; } return true; }

To check the status of the user, you use the isLoggedIn property of the Sys.Services.AuthenticationService object.

User Profiling Services

To make your ASP.NET pages friendlier, more functional, and more appealing to use, you can build a personalization layer into your Web application that gives users a chance to set and retrieve their preferences. The personalization capabilities of ASP.NET 2.0 are built around the concept of the user profile.

The user profile is a collection of properties that the ASP.NET 2.0 runtime groups into a dynamically generated class. The application defines its own data model in the configuration file, and the ASP.NET runtime does the rest by parsing and compiling that model into a class. Each member of the class corresponds to a piece of information specific to the currently logged-in user. Any profile data is persisted on a per-user basis and is permanently stored on the server until someone with administrative privileges deletes it.

When the application runs and a page is displayed, ASP.NET dynamically creates a profile object that contains, properly typed, the properties you defined in the data model. The object is then added to the current HttpContext object and is available to pages through the Profile property. The ASP.NET profile service is implemented through an HTTP module. The module kicks in when the request has been authenticated and retrieves data for the specific user. (If the user is anonymous, a unique ID is generated for that user and stored in the .ASPXANONYMOUS cookie.) At the end of the request, the profile object is saved back to the data store ready for the next time.

From within a server page, you can read and write profile properties using the HttpContext.Profile object. Can you do the same from within an ASP.NET AJAX page in an out-of-band postback? In fact, you can.

The System Infrastructure for Profiling

Just as with the authentication service, the user profile service relies on a client-server infrastructure. A JavaScript class provides methods to load and save user-specific information to the server. You receive a collection of properties representing the profile of the current user and save it back to the server’s data store with any changes made on the client. The underlying Web service uses the ASP.NET profile provider to persist information.

The user profile can be used to update properties used by server-side controls and page components. However, it also opens up a whole new world of possibilities. In fact, you can have client controls to persist a portion of their state to the server on a per-user basis.

The Client-Side Profiling Service Class

The Microsoft AJAX Library that wraps the user profiling service is named Sys.Services._ProfileService and is a private class that is available to programmers through a single point of access-the Sys.Services._ProfileService object. The global entry point is set in the Microsoft AJAX Library following the definition of the class, as the following code snippet shows:

Sys.Services.ProfileService = new Sys.Services._ProfileService();

The profile service class features the methods listed in Table 6-4.

Table 6-5 details the properties defined on the object.

Inherited from the Sys.Net.WebServiceProxy base class, the class Sys.Services._ProfileService acts as a client-side proxy for the remote Web service and is the bridge between the client page and the server-side HttpContext.Profile object.

The Server-Side Profiling Web Service

The ASP.NET AJAX profile service is a Web service coded through the class ProfileWebService located in the System.Web.Profile namespace. The class is mapped to the following URL:

Profile_JSON_AppService.axd

The URL points to an HTTP handler registered in the web.config file. The handler captures incoming requests and input parameters, executes the call, and then sends values back to the client in a JSON stream.

Once the AJAX authentication service is enabled in the site configuration, any page served from the site includes the following script:

You can replace the default Web service with another of choice as long as the new Web service supports JSON and is an ASP.NET Web service in the same Internet Information Services (IIS) application as the caller.

The Programming Interface of the Service

Table 6-6 lists the methods of the server-side profile Web service.

The exact signatures of the get methods are shown in the following code segment:

[WebMethod] public IDictionary GetAllPropertiesForCurrentUser(); [WebMethod] public IDictionary GetPropertiesForCurrentUser( string[] properties)

The properties argument lists the profile properties that you want to load in the JavaScript Sys.Profile object.

The SetPropertiesForCurrentUser method has the following signature:

[WebMethod] public int SetPropertiesForCurrentUser(IDictionary values)

It takes a dictionary of name/value property pairs as the input argument and updates the data store.

Because the ASP.NET AJAX service works on top of the ASP.NET profile subsystem, you can choose to bring in only a portion of the application data model coded in the web.config file. This tactic is normally a good move because it lets you move only the profile data you need to access from the client.

Configuration of the Profiling Service

The profile service requires a bit of configuration work. In particular, you need to explicitly enable the service through the section in the new section under :

...