Using Passport to Authenticate | Observing the User Experience: A Practitioners Guide to User Research

As we discussed earlier in this chapter, one of the benefits of Passport is the ability to give your users a consistent and familiar user interface to use. You ll notice that all Passport-enabled sites use the following Sign In button (note that at the time of this writing, this is the current image):

If the user clicks this button, the Passport Login user interface displays. If the user has authenticated successfully, this button becomes a Sign Out button:

The CPassportRequestHandlerT class that you re building in this chapter will expose this functionality as a stencil tag. Remember from earlier in this book that stencil tags are used in SRF files to insert dynamic content into the stream of data that will be sent to the client.

You ll create a stencil tag {{Passport_LogoTag}} to insert the Sign In or Sign Out button that Passport provides. By implementing a stencil tag in CPassportHandlerT , any ATL Server application that you build using this request handler class will be able to insert a Passport Sign In or Sign Out button by simply including the following stencil tag:

 {{Passport_LogoTag}}

Let s take a look at the code necessary to implement this stencil tag. The first step is to add a replacement map to your CPassportHandlerT request handler class:

 BEGIN_REPLACEMENT_METHOD_MAP(THandler)       REPLACEMENT_METHOD_ENTRY("Passport_LogoTag", OnLogoTag)  END_REPLACEMENT_METHOD_MAP()

As you ve probably seen in previous chapters, this replacement map simply associates the {{Passport_LogoTag}} stencil tag with the OnLogoTag method. The code for the OnLogoTag method is shown in Listing 21-4.

Listing 21.4: The OnLogoTag Method

 1 HTTP_CODE OnLogoTag()  2 {  3     BSTR logoTag(NULL);  4  5     if (FAILED(m_passportManager->LogoTag(m_returnURL,  6                                      m_timeWindow,  7                                      m_forceLogin,  8                                      m_coBrandArgs,  9                                      m_langId,  10                                     m_usingHTTPS,  11                                     m_namespace,  12                                     m_kpp,  13                                     m_useSecureAuth,  14                                     &logoTag)))  15    {  16         m_HttpResponse << "ERROR - could not get LogoTag";  17         return HTTP_S_FALSE;  18    }  19  20    m_HttpResponse << logoTag;  21    ::SysFreeString(logoTag);  22  23    return HTTP_SUCCESS;  24 }

The IPassportManager2::LogoTag method takes several parameters that you should look at individually. All of the input parameters are optional; if they aren t specified, they will be taken from the Passport Manager registry settings. These registry settings are set using the Passport Manager Administrative tool included with the SDK.

Let s have a look at the code for OnLogoTag line-by-line :

Line 5: You ll use the return URL that you built up during your initialization. This will give Passport Manager a URL to redirect the client to after the client has tried to authenticate him- or herself.
Line 6: The time window is used to specify how long the security token is valid after the user successfully authenticates him- or herself.
Line 7: This parameter should be VARIANT_TRUE if a return URL was specified and VARIANT_FALSE otherwise . If this parameter is VARIANT_TRUE , the time window is compared against the last time the user signed in; otherwise, it s compared against the last time the ticket was refreshed.
Line 8: This parameter specifies the query parameters that are added to the logo tag URL for cobranding purposes. Basically, cobranding allows you to integrate the look and feel of your application with the look and feel that Passport uses. Please see the latest Passport SDK documentation for details about cobranding.
Line 9: This parameter determines the language that Passport should use in its Login user interface. The value should be the integer value of the standard locale identifier (LCID) of the language you wish to use.
Line 10: This parameter determines whether or not the return URL is using a secure channel. You obtain this value during your initialization, so you just have to pass it in.
Line 11: This parameter allows you to specify an optional namespace, which helps you avoid name collisions in your HTML.
Line 12: You should use this parameter only if you re implementing Kids Passport. That service is offered by Passport to restrict authentication based on consent levels. See the latest Passport SDK documentation for details on this aspect of Passport.
Line 13: This parameter determines the security level for the Passport Login user interface. The following are valid values:
- 0: This is the default. The Login user interface is served using HTTP (though the cookie containing the security token is written using HTTPS).
- 1: The Login user interface is served using HTTPS. This requires that the return URL specified is using HTTPS as well.
- 2: The Login user interface is a service using HTTPS. This requires that a security key be passed as well as a password.

Line 14: This output parameter contains the URL that specifies the Sign In or Sign Out button. As mentioned earlier, clicking this button will display the Passport Login user interface.

As you can see, there are numerous parameters to the LogoTag method; the CPassportHandlerT class that you re building will leave these parameters unspecified. That means that their values will be taken from the Passport Manager registry settings. You can configure these settings using the Passport Manager Administrative tool included with the Passport SDK.

With the {{Passport_LogoTag}} stencil tag, an ATL Server application can easily add a Passport Sign In button. You should consult the latest Passport SDK documentation for guidelines as to where this button should appear in your application.

The next step in this scenario, covered in the next section, is to determine whether or not a user is authenticated. You need to know this to decide if you should show content specific to that user.

IsAuthenticated

ATL Server stencils implement basic logic constructs. You can take advantage of this to create a stencil tag that you can branch on, depending on whether or not the user is authenticated. You ll need to do this in order to display user-specific content.

Let s add a stencil tag to CPassportHandlerT called {{Passport_IsAuthenticated}} . This stencil tag will return a boolean value, so it can be used in a stencil as follows :

 {{if Passport_IsAuthenticated}}      Thanks for signing in!  {{else}}      Please sign in!  {{endif}}

This stencil tag lets you conveniently divide the generic content from the user-specific content in your pages.

Adding this stencil tag is very similar to what you had to do for {{Passport_LogoTag}} . You need to expand your replacement map as follows:

 BEGIN_REPLACEMENT_METHOD_MAP(THandler)       REPLACEMENT_METHOD_ENTRY("Passport_LogoTag", OnLogoTag)       REPLACEMENT_METHOD_ENTRY("Passport_IsAuthenticated", OnIsAuthenticated)  END_REPLACEMENT_METHOD_MAP()

This will associate the {{Passport_IsAuthenticated}} tag with the OnIsAuthenticated method. Listing 21-5 shows how to implement this method.

Listing 21.5: Authenticating a Passport Login Request

 1 HTTP_CODE OnIsAuthenticated()  2 {  3     VARIANT_BOOL isAuthenticated(VARIANT_FALSE);  4     if (FAILED(m_passportManager->IsAuthenticated(m_timeWindow,  5                                                   m_forceLogin,  6                                                   m_useSecureAuth,  7                                                   &isAuthenticated)))  8     {  9          return HTTP_S_FALSE;  10    }  11  12    return isAuthenticated == VARIANT_TRUE ? HTTP_SUCCESS : HTTP_S_FALSE;  13 }

This code is simple enough that we don t look at it line-by-line. The first three parameters are optional and serve the same purpose as in the IPassportManager2::LogoTag method. The last parameter is an output parameter that indicates whether or not the user has been authenticated. You ll return a mapping of this boolean value to the boolean values ( HTTP_S_FALSE , HTTP_SUCCESS ) that ATL Server uses in its stencil files.

Now you ve seen how to provide a login user interface for your users to authenticate themselves as well as a way to determine if they ve successfully done so. The only step remaining in this scenario is to display user-specific content.