Initializing Passport Manager | Observing the User Experience: A Practitioners Guide to User Research

You ll interact with Passport Manager using the IPassportManager2 interface. You can use this interface in your code by including the passport.h header file and linking with the passport.lib library. As its name suggests, this interface is the core interface for working with Passport Manager.

The code that you ll build in this chapter will be a request handler class that knows how to work with Passport. Once you ve built this request handler class, you ll use it to implement the scenario.

First declare your new request handler, as shown in Listing 21-1.

Listing 21.1: Declaration of a Passport-Enabled Request Handler

 #include <atlstencil.>  #include <passport.h>  template < class THandler,             class ThreadModel=CComSingleThreadModel,             class TagReplacerType=CHtmlTagReplacer< THandler > >  class CPassportHandlerT : public CRequestHandlerT< THandler,                                                     ThreadModel,                                                     TagReplacerType >  {  protected:          typedef CRequestHandlerT< THandler,                                    ThreadModel,                                    TagReplacerType> baseType;          IPassportManager2 *m_passportManager;  };

As you can see, you ll keep a pointer to the IPassportManager2 interface as a member in your new class because you ll need to use Passport Manager in a number of places in the new class.

Next, you ll initialize Passport Manager for each request that you process. This allows Passport Manager to read information it needs from the client HTTP request. You ll override the InitializeHandler method in your request handler to accomplish this initialization, as shown in Listing 21-2.

Because ATL Server applications are essentially ISAPI applications, you ll use the OnStartPageECB method to initialize Passport Manager. This method expects a pointer to the extension control block (ECB) associated with this request. The ECB is a structure that IIS initializes that contains all the information about the request the client is making. The ECB also contains pointers to functions that can be used to read/write data to/from the client. The ECB structure is really the link between IIS and an ISAPI application.

In most cases, you don t have to access the ECB directly when you re developing ATL Server applications. ATL Server provides a class, CServerContext , that exposes methods for accessing all of the information and methods in an ECB structure; the CRequestHandlerT class stores an instance of this class in a member, m_spServerContext , that you can use in your ATL Server applications. However, in cases where you do need access to the actual ECB structure, you can override the InitializeHandler method and get access to the ECB from the pRequestInfo parameter.

Don t worry if you see members being used in Listing 21-2 that weren t declared in Listing 21-1 ”we omit some of these declarations for now, but you ll see them in the full code listing at the end of this chapter.

Listing 21.2: Initializing Passport Manager

 1 HTTP_CODE InitializeHandler( AtlServerRequest *pRequestInfo,  2                              IServiceProvider *pProvider )  3 {  4     HTTP_CODE httpCode = baseType::InitializeHandler(pRequestInfo,pProvider);  5  6     if (httpCode == HTTP_SUCCESS)  7     {  8          if (!m_passportManager)  9          {  10              if (FAILED(CoCreateInstance(CLSID_Manager,  11                                          NULL,  12                                          CLSCTX_INPROC_SERVER,  13                                          IID_IPassportManager2,  14                                          (void**)&m_passportManager)))  15              {  16                   return HTTP_S_FALSE;  17              }  18         }  19  20         DWORD bufferSize(ATL_MAX_COOKIE_LEN);  21         CHAR  cookieHeader[ATL_MAX_COOKIE_LEN + 1];  22         cookieHeader[0] = 0;  23  24        if (FAILED(m_passportManager->OnStartPageECB((BYTE*)pRequestInfo->pECB,  25                                                      &bufferSize,  26                                                      cookieHeader)))  27         {  28              return HTTP_S_FALSE;  29         }  30  31         CString url;  32         bool    https(false);  33  34         if (!GetURL(url, https))  35         {  36              return HTTP_S_FALSE;  37         }  38  39         m_returnURL  = url;  40         m_usingHTTPS = https;  41  42         CCookie passportCookie;  43         if( passportCookie.Parse( cookieHeader ) )  44         {  45             m_HttpResponse.AppendCookie( passportCookie );  46         }  47  48         m_HttpResponse.SetCacheControl("no-cache");  49         m_HttpResponse.SetContentType("text/html");  50    }  51  52    return httpCode;  53 }

Let s have a look at this code line-by-line :

Line 4: You want to preserve the behavior of your base class, so you call back to the base implementation first. If that s successful, then you ll continue on and do your Passport-specific initialization.
Lines 8 through 14: Passport Manager is exposed to you as a COM interface, so you can use CoCreateInstance to a get a pointer to IPassportManager2 .
Lines 20 through 29: Passport Manager needs to know where to read information about the client s request. There are methods on the IPassportManager2 interface to read client requests from ASP and ISAPI. Passport may require some cookies to be set on the client; these cookies are returned in the cookieHeader variable.
Lines 31 through 37: To authenticate with Passport, your users will click a Sign In button. This button is a link to a URL on a Passport server. After it tries to authenticate the user, the Passport server needs to know where the user should go. To do this, you need to give Passport a return URL. In the case of the code you ll build in this chapter, and in most cases in general, this return URL will be the URL that the client used to request your ATL Server application in the first place.
Lines 42 through 46: Set any cookies that Passport Manager requested .
Lines 48 and 49: The last steps in your initialization are to turn off caching and set your content type to indicate that you re returning textual HTML. Turning off caching is helpful especially during the development phase so that the browser won t display cached information about whether you re authenticated with Passport or not.

The code in Listing 21-2 called a GetURL function. Let s look at how that method is implemented. Because you re building a request handler that could be used for a number of different applications, you want to get the URL the client requested in a generic way. You ll put this code in the GetURL method more for neatness than for anything else. The code for this method is as shown in Listing 21-3.

Listing 21.3: GetURL Implementation

 1 bool GetURL(CString& url, bool& bHttps)  2 {  3     CHAR szURL[ATL_URL_MAX_URL_LENGTH];  4     DWORD dwUrlSize = sizeof(szURL) * sizeof(CHAR);  5  6     CHAR szServer[ATL_URL_MAX_HOST_NAME_LENGTH];  7     DWORD dwServerSize = sizeof(szServer) * sizeof(CHAR);  8  9     CHAR szHttps[10];  10    DWORD dwHttpsLen = sizeof(szHttps) * sizeof(CHAR);  11  12    if (m_spServerContext->GetServerVariable("URL",  13                                             szURL,  14                                             &dwUrlSize) != FALSE)  15    {  16         if (m_spServerContext->GetServerVariable("SERVER_NAME",  17                                                  szServer,  18                                                  &dwServerSize) != FALSE)  19         {  20              bHttps = false;  21              if ((m_spServerContext->GetServerVariable(  22                      "HTTPS",  23                      szHttps,  24                      &dwHttpsLen) != FALSE) &&  25                     (!_stricmp(szHttps, "ON")))  26              {  27                   bHttps = true;  28              }  29              _ATLTRY  30              {  31                   url.Format("http%s://%s%s", bHttps ? "s" : "",  32                              szServer,  33                              szURL);  34  35                   return true;  36              }  37              _ATLCATCHALL()  38              {  39                   return false;  40              }  41         }  42    }  43  44    return false;  45 }

All of the code in GetURL is basically for accessing server variables . Server variables are a set of data that IIS stores that provides information about the HTTP connection the client made as well as information about the IIS server itself. You can access the server variables using the m_spServerContext member that s part of your CRequestHandlerT base class. As we mentioned before, m_spServerContext is an instance of the CServerContext class, which is essentially an abstraction of the ECB structure.

Let s take a look at this code line-by-line. You should also consult the IIS SDK documentation for a full listing of all the server variables and their definitions.

Line 12: The server variable URL will give you the base portion of the URL that the client requested. This doesn t contain the protocol or parameters that were part of that request.
Lines 16 through 18: The SERVER_NAME server variable gives you the name of the IIS server you re running. Getting the name in this manner lets you not have to rely on reading the registry or anything on the local machine to determine the name of your IIS installation. The HTTPS server variable contains a value of ON or OFF to indicate whether the request came through a secure channel or an insecure channel, respectively. You ll want to preserve this information for Passport Manager, because if your client came through a secure channel, you don t want Passport Manager to send the client back to your application using an insecure channel.
Line 31: Finally, you build your return URL with a protocol of http or https , depending on whether or not the user who called your application used a secure channel. A more advanced method that we leave as an exercise for the interested reader is to use the SERVER_PROTOCOL server variable to determine this information.

We hope you ve seen that working with Passport Manager in ATL Server isn t that difficult. In fact, the code in this section is probably the most complicated code in this chapter. Now that you ve initialized Passport Manager, you ll take a look at how you can use it to implement the scenario described earlier in this chapter.