Implementing Sign-Out and Deleting Cookies
.jpg)
Implementing Sign-Out and Deleting Cookies
The Passport Manager uses cookies written into a participating site's domain to track users' authentication status for that site. Every participating site must provide a script that deletes all authentication cookies from a user's computer. This topic discusses the implementation requirements of a participating site's cookie-delete script.
Sign-Out Process
When users click the Sign Out button on any participating site, they are redirected to a central sign-out script hosted by Microsoft® .NET Passport. This script uses a Visited Sites cookie that is maintained on the user's computer in the *.passport.com domain to determine which sites the user is currently signed in to. Then, the sign-out script deletes all cookies from the *.passport.com domain. Next, the sign-out script calls the cookie-delete scripts for each of the participating sites that the user is signed in to. The cookie-delete script for each site deletes all of the .NET Passport-related cookies in the site's domain. Finally, based on the return value of each site's script, the centrally hosted sign-out script displays a page listing each site that the user was signed in to and indicating whether the user was successfully signed out.
When the centrally hosted sign-out script calls the cookie-delete script of a participating site, it does so by embedding an image into its HTTP response. The source of the image is set to the address of the participating site's cookie-delete script. After the participating site performs the required cookie deletion, it should return an actual image to the calling script, using the SignOut method of the PassportIdentity object. The return of this image, including an HTTP 200 status code, is used by the central sign-out script to determine if the participating site's sign-out script was successful. The image returned by the site is not actually displayed. Instead, the standardized green check-mark image is displayed beside the sites from which the user was successfully signed out. A red "X" indicates that the sign-out script for that site was not successful.
Providing a cookie-delete script is a requirement for becoming a .NET Passport participating site. You specify the URL of your cookie-delete script in the Expire Cookie URL field of the .NET Services Manager when you register your site.
To implement sign-out
Verify that all pages that use .NET Passport authentication contain a call to the LogoTag2 method of the PassportIdentity object. If they do, and if the user is signed in, the user should be able to sign out by clicking the .NET Passport sign-out link on each page.
Verify that the cookie-delete script is served from the location you supplied when you registered this site. If your site does not have a Site ID, it cannot delete cookies and is considered to be in test mode. For more information, see Test Mode.
Write the code that will be served from the cookie-delete script location. It is a .NET Passport policy requirement that participating sites delete the .NET Passport Ticket and Profile cookies whenever the cookie-delete script is loaded by a user's browser. You are advised to also delete any other related cookies of your own that could cause an invalid determination of state after the .NET Passport cookies are deleted. Cookies are deleted by setting their value to NULL and their expiration to a date in the past.
To delete the Ticket cookie, delete the cookie named MSPAuth as written into the site's domain. To delete the Profile cookie, delete the cookie named MSPProf as written into the site's domain. To delete the Consent cookie, delete the cookie named MSPConsent (Microsoft® Kids Passport sites only). If your site is using SSL sign-in, delete the cookie named MSPSecAuth.
Verify that Passport Manager installations on the site set the Ticket and Profile cookie paths correctly. Any paths set by using the Passport Manager Administration utility (in the Cookie Path field) should be the same paths from which the cookie-delete script attempts to delete cookies.
Test the cookie-delete mechanism.
Sign-Out Example Code
The following is an ASP.NET sample cookie-delete script.
<%@ Page Language="C#"%>
<%@ Import Namespace="System.Web.Security"%>
<%
Response.ContentType="image/gif"
Response.Expires = -1;
Response.AddHeader("P3P", "CP=""TST""");
Response.Cookies("MSPProf").Value = "";
Response.Cookies("MSPProf").Expires = DateTime.MinValue;
Response.Cookies("MSPAuth").Value = "";
Response.Cookies("MSPAuth").Expires = DateTime.MinValue;
Response.Cookies("MSPConsent").Value = "";
Response.Cookies("MSPConsent").Expires = DateTime.MinValue;
Response.Cookies("MSPSecAuth").Value = "";
Response.Cookies("MSPSecAuth").Expires = DateTime.MinValue;
Response.Cookies("YourSiteCookie").Value = "";
Response.Cookies("YourSiteCookie").Expires = DateTime.MinValue;
//If you have configured your Web site to use a domain other than the default, then
//uncomment and modify the following lines:
//Response.Cookies("MSPProf").Domain = your cookie domain ;
//Response.Cookies("MSPProf").Path = your cookie path ;
//Response.Cookies("MSPAuth").Domain = your cookie domain ;
//Response.Cookies("MSPAuth").Path = your cookie path ;
//also remember to delete any site-specific cookies
//that are based on .NET Passport profiles!
//For example, delete the shopping cart cookie.
Response.Cookies("ShoppingCartCookie").Value = "";
System.Web.Security.PassportIdentity.SignOut("images/signoutcheckmark.gif");
%>
The following comments pertain to the preceding example.
Always Set Content Type
Note the line of code emphasized in red in this example. Microsoft® Internet Explorer's security code now requires that ASP.NET-generated content declare its content type in certain circumstances. If you use ASP.NET for the cookie-delete file, check all of your cookie-deleting code to make sure that it sets content type, either through ASP.NET or directly in the header. If content type is not set, the requested Graphics Interchange Format (GIF) or Joint Photographic Experts Group (JPEG) sign-out image is not loaded into Internet Explorer and does not return the correct status code to the .NET Passport network sign-out code.
Setting P3P Mini-Headers
Note the Response.AddHeader call in the preceding example:
Response.AddHeader("P3P", "CP=\"TST\"")The page that deletes .NET Passport cookies does so as a third-party transaction, because your site's cookie-delete page is included in the .NET Passport-served global sign-out page. This requires that your site's cookie-delete page include a P3P "mini-header" in the response sent to any Internet Explorer version 6 browser user. If the mini-header is not included, the browser does not allow cookies set by your site to be deleted in this scenario. For more information about P3P mini-headers, Internet Explorer 6, and .NET Passport, see .NET Passport and P3P.
Verifying Same Domain and Path Are Used Both to Set and Delete Cookies
If the Cookie Domain or Secure Domain fields in the Passport Manager Administration utility are set to anything other than the full domain name for the site, or to NULL, verify that the cookie-delete code is clearing cookies for all domains specified. Typically, these domain fields are left blank in the Passport Manager Administration utility, which defaults to the domain in which the object is created. The cookie-delete code for your site should be clearing cookies for any possible cookie-writing domains used by Passport Manager installations on your site, because your configuration information provides one URL for cookie-delete code that must serve your whole site (a site being one that shares a single .NET Passport Site ID).
It is recommended that the cookie-delete code be served from your Web site root so that it has domain-level permissions to delete cookies set by any particular subdomain.
Similarly, if the Cookie Path field in the Passport Manager Administration utility is set to anything other than the blank default, your cookie-delete code must be able to delete the cookies written into that path. For more information, see Passport Manager Administration Utility.
Kids Passport: Handling the MSPConsent Cookie
The Passport Manager Administration utility includes the Consent Cookie Domain field, which you can use to set the Consent (MSPConsent) cookie to a different domain if you wish. A different path can also be specified with the Consent Cookie Path field. Make sure the cookie-delete page deletes the MSPConsent cookie and also that it has access to both the .path and .domain with which this cookie was set.
Return an Image
Note the call to the SignOut method in this example file. The successful (HTTP 200 status) return of a legitimate image on the request to your site's cookie-delete page enables the .NET Passport network cookie-delete page to correctly show the green check mark to the user. Although not returning an image may not necessarily break the sign-out process, it will present a confusing user interface (UI) and should be avoided.
The image itself is actually replaced by a network default by the centrally hosted sign-out page. Therefore, as long as the image call to your site's cookie-delete code returns an HTTP 200 status code, your image will be replaced by a network-served green check-mark image. If the image call to your site's Expire Cookie URL returns any other (error) code, the image is replaced by a network-served red "X" image. The actual image specified by your site's cookie-delete code is never seen by the user, but should still always return HTTP 200 status code when requested. For this reason, do not use 302 or other redirects on your site because the 302 code will be treated as a missing image by the .NET Passport network code.
See Also