AuthManager Object [C++]
Use this object to perform user identification and authentication and to manage user security information. This object also contains methods for browsing with and without cookies.
| ProgID: | Commerce.AuthManager (Externally creatable) |
| COM Class Name: | MSCSAuthManager |
| Type Library Name: | Microsoft Commerce 2002 AuthManager 2.0 Type Library |
| DLL Name: | mscsauth.dll |
| Threading Model: | Both |
[C++]
| COM Interface Name: | IMSCSAuthManager2 |
| Interface ID Constant: | IID_IMSCSAuthManager |
| Header File: | MSCSAuth.h |
[C++]
The AuthManager object is primarily intended to be used through ASP script. However, the following methods are available in C++ through the IMSCSAuthManager interface when the MSCSAuthManager object is instantiated outside of an ASP script: GenerateEncryptionKey, GetUserIDFromCookie, GetUserIDFromCookieAndKey, Initialize, Refresh, and UnInitialize.
Once any AuthManager object instance has been successfully initialized withing an ASP or ASP.NET site, any further instances of the AuthManager object initiailized within that site use the cached resources as loaded by the first call to the Initialize method. Therefore, even if a different value for the SiteName parameter is used, the AuthManager object will still be configured to run using the site configuration specified in the first call to the Initialize method. In other words, within a single ASP or ASP.NET site you can run an AuthManager object against the resource configuration of a single site but never multiple sites.
[Visual Basic]
The AuthManager object is primarily intended to be used through ASP script. However, the following methods are available in Visual Basic when the MSCSAuthManager object is instantiated outside of an ASP script: GenerateEncryptionKey, GetUserIDFromCookie, GetUserIDFromCookieAndKey, Initialize, Refresh, and UnInitialize.
Once any AuthManager object instance has been successfully initialized withing an ASP or ASP.NET site, any further instances of the AuthManager object initiailized within that site use the cached resources as loaded by the first call to the Initialize method. Therefore even if a different value for the SiteName parameter is used, the AuthManager object will still be configured to run using the site configuration specified in the first call to the Initialize method. In other words, within a single ASP or ASP.NET site you can run an AuthManager object against the resource configuration of a single site but never multiple sites.
Methods
[C++]
| Method | Description |
|---|---|
| GenerateEncryptionKey | Generates an encryption key for the administration of cookie data. Use this method in administrative or setup components only. |
| GetProperty | Retrieves the specified custom property stored in a cookie or query string. |
| GetURL | Generates a URL containing optional name/value pairs. |
| GetUserID | Retrieves the unique ID for the current user. |
| GetUserIDFromCookie | Retrieves the user ID from a cookie. |
| GetUserIDFromCookieAndKey | Retrieves the user ID from a cookie and the encryption key. |
| Initialize | Initializes the AuthManager object by caching all the required site configuration resource properties. |
| IsAuthenticated | Indicates whether a user is currently authenticated. |
| Refresh | Updates the cached site configuration resource properties after any of the properties have been changed. |
| SetAuthTicket | Generates an encrypted MSCSAuth ticket for a registered user. |
| SetProfileTicket | Generates an encrypted MSCSProfile ticket for an anonymous user. |
| SetProperty | Adds a property/value pair to a cookie or query string containing a ticket. |
| SetUserID | Sets the user ID property on a ticket. |
| UnInitialize | Removes the site-specific configuration resource properties from the cache. |
| URLArgs | Generates a URL-encoded query string from arrays of parameter names and values. |
| URLShopperArgs | Generates an encoded Uniform Resource Locator (URL) query string of name/value pairs and append the ticket to the query string if a ticket is set. |
[Visual Basic]
| Method | Description |
|---|---|
| GenerateEncryptionKey | Generates an encryption key for the administration of cookie data. Use this method in administration or setup components only. |
| GetProperty | Retrieves the specified custom property stored in a cookie or query string. |
| GetURL | Generates a Uniform Resource Locator (URL) containing optional name/value pairs. |
| GetUserID | Retrieves the unique ID for the current user. |
| GetUserIDFromCookie | Retrieves the user ID from a cookie. |
| GetUserIDFromCookieAndKey | Retrieves the user ID from a cookie and the encryption key. |
| Initialize | Initializes the AuthManager object by caching all the required site configuration resource properties. |
| IsAuthenticated | Indicates whether a user is currently authenticated. |
| Refresh | Updates the cached site configuration resource properties after any of the properties have been changed. |
| SetAuthTicket | Generates an encrypted MSCSAuth ticket for a registered user. |
| SetProfileTicket | Generates an encrypted MSCSProfile ticket for an anonymous user. |
| SetProperty | Adds a property/value pair to a cookie or query string containing a ticket. |
| SetUserID | Sets the user ID property on a ticket. |
| UnInitialize | Removes the site-specific configuration resource properties from the cache. |
| URLArgs | Generates a URL-encoded query string from arrays of parameter names and values. |
| URLShopperArgs | Generates an encoded Uniform Resource Locator (URL) query string of name/value pairs and append the ticket to the query string if a ticket is set. |
Remarks
The AuthManager object identifies users and gathers information used for user authentication. The methods and properties of this object control and access the contents of cookies and encoded URL strings.
In the Commerce Server 2002 context, authentication uses tickets. A ticket is a string of property/value pairs that provide information about the user. Two types of tickets are supported. An authentication ticket, named MSCSAuth, is used for registered users while a profile ticket, named MSCSProfile, is used for anonymous users. In this context, "registered" means a user who has provided information to a site that can be used for identification.
A user may have both types of tickets. In this case, the MSCSAuth ticket takes precedence.
A ticket contains a unique user ID, and for authentication tickets, the time of last login and a time window. For an anonymous user who allows cookies, the MSCSProfile ticket is stored on the local computer of the user as a persistent cookie. For a registered user who allows cookies, the MSCSAuth ticket is stored in a session cookie and is valid for the duration of the session or a specified time window, and then is deleted.
If the user does not allow cookies, the ticket is placed in an encoded URL string. The URL string may be used to pass user information between pages and sites, provided all the URLs and query strings are generated by the AuthManager object.
The AuthManager object provides a transparent interface to the tickets, whether they are stored in cookies or in URL query strings, and handles encryption and decryption of the tickets to ensure security.
The AuthManager object is intended to be used only through Active Server Pages (ASP) since it depends on ASP intrinsic objects. Do not create the AuthManager object in application scope as it has dependencies on individual user ,sessions. The AuthManager object should be created and destroyed on each ASP page.
The methods GetUserIDFromCookie, GetUserIDFromCookieAndKey, and GenerateEncryptionKey facilitate rolling key encryption functionality. For more information about this feature, see Rolling Key Encryption for Authentication Tickets.
Any operation that requires decryption of the ticket will fail if you change the encryption key. One important instance of this behavior is with profile tickets, because they are persisted on the client computer. Hence when a user with a persisted profile ticket that was encrypted with the old key comes back to the site, AuthManager is not be able to decrypt this ticket. For more information about this issue, see Rolling Key Encryption for Authentication Tickets.
See Also
Copyright © 2005 Microsoft Corporation.
All rights reserved.