ASP+ authentication providers are the code modules that contain the code necessary to authenticate the requestor's credentials. To enable a given authentication provider for an ASP+ application, you only need to create an entry for the application configuration file as follows:
// config.web file <security> <authentication mode= "[Windows/Cookies/Passport]"> </authentication> </security>
The mode is set to one of the authentication methods: Windows, Cookies, or Passport. As is the case with other ASP+ modules, authentication modules are inherited by child directories in the URI space unless explicitly overridden. Each of the authentication providers is described in more detail in the sections that follow.
For more information on ASP+ configuration files, see ASP+ Configuration Concepts
The WindowsAuthenticationModule provider can use IIS authentication, or can be used to implement a custom Windows authentication scheme. In either case, the provider module constructs a WindowsIdentity object, and the default implementation constructs a WindowsPrincipal object and attaches it to the application context. The WindowsPrincipal object maps identities to Windows groups. For more information on these objects (classes), see the reference section of this documentation.
If it is desired to use IIS authentication, the provider module uses the authenticated identity passed in from IIS. The identity is authenticated by IIS using Basic, Digest, or Windows authentication, or some combination of them. Impersonation (in conjunction with NTFS ACL permissions) can be used to restrict or allow access to protected resources. This is the provider configuration you should use if you want to implement site security with a minimum of ASP+ coding.
You can also construct a custom authentication scheme using the WindowsAuthenticationModule, which is explained in the next topic.
An important reason to use the WindowsAuthenticationModule provider is to implement an impersonation scheme that can use any of the authentication methods that may have already been performed by IIS prior passing the request to the ASP+ application. To do this, set the authentication mode to "Windows", and confirm that the <impersonation enable> element is set to "true" (the default). For example:
<security> <authentication mode="Windows"> </authentication> <identity> <impersonation enable="true"/> </identity> </security>
Next you must set the NTFS ACLs to allow access only to the proper identities.
If you want to enable impersonation for only a short duration of time during request processing, you can do it by using an impersonation context and WindowsIdentity.Impersonate:
First, set the <impersonation enable> element to "false". Then, set up a context using the WindowsIdentity.Impersonate method:
ImpersonationContext context = WindowsIdentity.Impersonate(); // do whatever context.Undo();
Notice that identity reversion can be done using context.Undo.
As mentioned earlier, you can implement a custom Windows authentication scheme. You can use a WindowsAuthenticate_OnAuthenticate event handler to implement a WindowsIdentity object, from which you can create a custom IPrincipal class (perhaps derived from WindowsPrincipal) that implements your custom scheme. The default implementation constructs a WindowsPrincipal object and attaches it to the application context. The WindowsPrincipal object maps identities to Windows groups. For more information on the WindowsPrincipal object, see the Reference section of this documentation.
Passport authentication is a centralized authentication service provided by Microsoft that offers a single sign-in and core profile services for member sites. This benefits the end user because it is no longer necessary to log in every time the user needs to access new protected resources or sites. If you want your site to be compatible with Passport authentication and authorization, this is the provider you should use. This document provides some introductory material on Microsoft Passport and the ASP+ support for it, but it is not a substitute for the information contained in the Passport documentation, which can be found at http://www.passport.com/business. Once there, you will have to get a passport and register.
Conceptually, Passport is a cookie-based authentication service. A sample conversation using Passport authentication might look similar to the following:
Back on the originating server, the PassportAuthenticationModule detects the absence of the cookie and the presence of the ticket on the query string and issues the authentication cookie, which consists of the authentication ticket and a path of / . The request is then authenticated.
Subsequent requests for protected resources at the site are authenticated at the originating server using the supplied ticket. Passport also makes provisions for ticket expiration and reusing tickets across other member sites.
The encryption scheme Passport uses is Triple DES. When member sites register with Passport, they are granted a site-specific key. The Passport login server uses this to encrypt and decrypt the query strings passed between sites.
It is important to remember that using Passport authentication requires site registration with the Passport service and installation of the Passport SDK prior to use (a fee is charged).
The PassportAuthenticationModule provider provides a wrapper around the Passport SDK for ASP+ applications. It requires installation of the Passport SDK and provides Passport authentication services and profile information from an IIdentity-derived class called PassportIdentity.
As is the case with the WindowsIdentity, the primary purpose of handling the PassportAuthentication_OnAuthenticate event is to attach a custom IPrincipal object to the context.
A special IIdentity-derived class called IPassportIdentity provides an interface to the Passport profile information as well as methods to encrypt and decrypt Passport authentication tickets.
The general process for implementing Passport authentication in an ASP+ application is as follows:
<security> <authentication mode= "Passport"> </authentication> </security>
Cookie authentication is generally used to refer to a system where unauthenticated requests are redirected to an HTML form (using HTTP client-side redirection). If you need to collect your own user credentials at logon time through HTML forms, this would be a good choice of providers. The user provides credentials and submits the forms. If the application authenticates the request, the system issues a cookie that contains the credentials in some form or a key for reacquiring the identity. Subsequent requests are issued with the cookie in the request headers and they are authenticated and authorized by an ASP+ handler using whatever validation method the application specifies.
It should be noted that cookie authentication is often used for personalization, where content is customized for a known user. In some of these cases, identification is the issue rather than authentication, so it is enough to merely store the user name (in a durable cookie) and use that cookie to access the user personalization information.
The CookieAuthenticationModule provider exposes cookie-based authentication services to ASP+ applications. The module allows the developer to optionally handle a CookieAuthentication_OnAuthentication event during the authentication process.
You must provide a logon URL that collects and authenticates credentials. If the credentials are valid, you can rely upon helper utilities provided to redirect the request to the originally requested resource with an appropriate authentication ticket cookie. For more information on authentication ticket cookies, see Creating an Authentication Ticket Cookie later in this section.
In the simplest case, the developer can just configure a login URL to redirect unauthenticated requests to, supply a minimal implementation of that file (customized from an example page), and supply a file containing valid credential pairs. The framework will take care of the rest. The following example code shows how this might be handled in an ASP+ configuration file:
// config.web file <security> <authentication mode="cookie"> <cookie cookie="401kApp" loginurl="/login.aspx" decryptionkey="1!#$$*13^"> <credentials passwordformat=SHA1> <user name="Mary" password="GASDFSA9823423BSD"/> <user name="John" password="ZA#$34343443BSD44"/> <user name="John" password="ZA#$34343443BSD44"/> </credentials> </cookie> </authentication> </security>
The flow of control for a cookie authentication conversation is shown in the following example:
A user agent (browser) requests a protected resource from a server.
UA:
GET /default.aspx
In the absence of an authentication cookie, the server redirects the request to a login page to collect credentials. Information about the originating page is placed in the query string using RETURNURL as the key.
S:
302 Found Location: https://samples.microsoft.com/login.aspx?RETURNURL=/default.aspx
The user agent follows the redirection to the login page.
UA:
GET /login.aspx?RETURNURL=/default.aspx
The server returns the login page. It is recommended that at least the POST back to the login page use SSL to protect the user’s credentials from being sent in cleartext.
S:
200 OK
The user enters their credentials into the login form.
UA:
POST /login.aspx?RETURNURL=/default.aspx
The server validates the credentials and, if the credentials are authenticated, redirects the UA to the original URL retrieved from the login ticket. The authentication ticket is encrypted in the query string.
S:
302 Found Location: /default.aspx?ASPXTICKET=ABCDEFG12345
The user agent follows the redirection and requests the original resource again.
UA:
GET /default.aspx?ASPXTICKET=ABCDEFG12345
Access is granted (assuming the user is authorized) and the authentication cookie, which contains an authentication ticket, is granted. Future requests by the same browser session will be authenticated when the module inspects the cookie. It is possible to create a durable cookie that can be used for future sessions, but only until the cookie expiration date.
S:
200 OK Set-Cookie: ASPXTICKET=ABCDEFG12345;Path=/
Notice that the cookie Path is set to /. Because cookies are case-sensitive, this is a safeguard against inconsistent case in URLs on the site. For example, if the path were set to /401K and a link contained /401k, the user would be forced to reauthenticate because the browser would not send the cookie.
The authentication ticket is a linear representation of the AuthenticationTicket class suitable for encoding as an HTTP cookie or query string. The creation of an authentication ticket cookie from an AuthenticationTicket class is straightforward and detailed in the following steps:
When the cookie is validated, the CookieAuthenticationModule will take the cookie data, append the site encryption key, and produce a hash. The resulting hash will be compared to the hash in the cookie itself. If they match, the cookie is considered valid.
You can allow the CookieAuthenticationModule to handle the authentication process from an application configuration file, as described in the following paragraphs.
As illustrated earlier, valid user/password pairs can be placed in the <credentials> section of a configuration file. The credentials collected from the user requesting logon privileges can be compared to the list of user/password pairs in the <credentials> section to determine if access should be granted. In the following example, users Mary and John could log in if they provide the correct password.
<credentials passwordformat=”SHA1” > <user name=”Mary” password=”GASDFSA9823598ASDBAD”/> <user name=”John” password=”ZASDFADSFASD23483142”/> </credentials>
The credential pairs must be contained within a <credentials> section. The passwordformat
attribute is required, and can be one of the following values:
Value | Description |
---|---|
MD5 | Passwords are stored using an MD5 hash digest. When credentials are validated, the user password will be hashed using the MD5 algorithm and compared for equality with this value. The cleartext password is never stored or compared when using this value. Use this algorithm for best speed as compared to SHA1. |
SHA1 | Passwords are stored using the SHA1 hash digest. When credentials are validated, the user password will be hashed using the SHA1 algorithm and compared for equality with this value. The cleartext password is never stored or compared when using this value. Use this algorithm for best security. |
clear | Passwords are stored in cleartext. The user password is compared directly against this value without further transformation. |
The CookieAuthenticationModule is configured by the <cookie> element in a configuration file. The cookie, loginurl, and decryptionkey attributes of the <cookie> element can be set. See the example cookie configuration file shown earlier.
The cookie attributes can be set as follows:
Attribute | Description |
---|---|
Cookie= |
Name of the HTTP cookie to use for the authentication ticket. By default, this value is .ASPXAUTH. |
Loginurl= |
The URL to which the request is redirected if it does not contain a valid authentication ticket. It is strongly suggested that this be a SSL URL (https://) to prevent credentials from being posted in cleartext. This need not be SSL-protected if the login form itself posts back to an SSL-protected resource. |
Decryptionkey= |
A key used to decrypt authentication tickets. Note that the default is "autogenerate", so a machine-specific key is used, and the cookies cannot be shared across server machines. This key is stored in cleartext. |
For more information on ASP+ configuration, see ASP+ Configuration Concepts
A helper class called CookieAuthentication provides some static helper methods for managing cookie authentication tickets. These methods are as follows:
System.ASP.Security { public class CookieAuthentication { // encrypt and decrypt tickets public static CookieAuthenticationTicket Decrypt ( String cookie); public static String Encrypt ( CookieAuthenticationTicket ticket); public static bool Authenticate(String user, String password); public static void Redirect(HttpContext context, CookieAuthenticationTicket ticket, String originalURL); public static void Redirect(HttpContext context, CookieAuthenticationTicket ticket); } }
You can use the helpers to customize the way the module works. They can also be used in the login page handler to avoid the work of generating the redirection. A login page using these facilities can be as simple as the following example:
<html> <head> <script runat=server> Sub SubmitBtn_Click(ByVal Source as Object, ByVal E as EventArgs) ’pull credentials from form fields and try to authenticate If CookieAuthentication.Authenticate(UserName.Value, UserPassword.Value) Then Set ticket = New CookieAuthenticationTicket( UserName.Value, false) CookieAuthentication.Redirect context, ticket End If EndSub </script> </head> <body> <form method=post runat=server> <table> <tr> <td>Name:</td> <td><input type=”text” id=”UserName” runat=server/> </tr> <tr> <td>Password:</td> <td><input type=”password” id=”UserPassword” runat=server/> </td> </table> <input type=”submit” OnServerClick=”SubmitBtn_Click”/ runat=server> </form> </body> </html>
Applications that need granular control over the HTTP cookie properties can use the encryption helpers to encrypt the authentication ticket, but can construct the ticket and perform the redirection themselves.
You can choose to handle the CookieAuthenticate_OnAuthenticate event in order to do all cookie management in whatever way you want. Although in many applications you will want to take advantage of the framework support to manage this for you, some applications might have specific needs (for example, storing credentials in the cookie). These applications should handle the CookieAuthenticate_OnAuthenticate event to perform cookie management in whatever way desired.