Programmatic Identifier
Membership.VerifUsr.1
CLSID
C4F9C9CC-C33E-11D0-B8A0-00C04FB616C7
COM Class Name
verifusr
Type Library Name
verifusr 1.0 Type Library
Type Library Location
c:\Microsoft Site Server\Bin\P&M\verifusr.dll
Threading Model
"Both"
The VerifUsr COM class is used in an ASP environment to issue appropriate Membership server related cookies to a user. Objects of this class should be used in the following situations:
Objects of this class will only work correctly if in an ASP scripting environment.
The verifusr COM class exposes the single dual custom COM interface Iverifusr. Thus, the methods and properties are accessible through the COM interface, or through the dispinterface Iverifusr. (IDispatch)
It should be noted here that instance of the Verifusr class require the ASP scripting context interfaces and thus the ASP environment. Because of this, script languages used within ASP pages will be the primary clients for objects of this class.
The OnStartPage method is an implementation of the standard server-side method invoked by the ASP scripting context on any COM objects created using the built-in ASP Server object method CreateObject. The method gathers the necessary interfaces internally to prepare for additional method invocations exposed on the verifusr COM class. This method should never be invoked explicitly by the scripter, as the COM class verifusr should always be created in an ASP page using the Server object method CreateObject.
Example
VBScript in an ASP page
Set IVerifUsr = Server.CreateObject("Membership.Verifusr.1")
The OnEndPage method is an implementation of the standard server-side method invoked by the ASP scripting context on any COM objects created using the built-in ASP Server object method CreateObject. The OnEndPage method is not used by the script writer and is listed here strictly for completeness.
This method verifies that the passed arguments bszUsername and bszPassword are correct by contacting the appropriate Membership Authentication server instance. If they are correct, an appropriate cookie is issued to the user, and the passed URL argument is returned. If the username and password are not valid, no cookie is issued, and the URL returned points to a predefined registration page.
IDL Definition
HRESULT VerifyCredentials(
BSTR bszUserName,
BSTR bszPassword,
BSTR bszURL,
[out, retval] BSTR * pbstrUrlToRedirect
);Parameters
bszUserName
The username to check along with a password
bszPassword
The password to check along with a username
bszURL
The URL to send the user if the presented credentials are valid.
pbstrUrlToRedirect
On return, the URL to redirect the client. This value is dependent on whether the client's presented credentials were valid or not. If the credentials are valid, the bszURL value is returned. Otherwise, a predefined error/registration URL is returned.
Return Values
A standard HRESULT value
Remarks
This method should be used in ASP pages for IIS server instances mapped to Membership Authentication server instances that have "Membership" authentication set, and is most useful when "Forms Authentication" is being used. In this case, one uses this method to perform the verification of credentials. Once the user has successfully provided valid credentials to the VerifyCredentials method, the necessary cookies are sent in the HTTP response that then allow the user to go on and access content.
In any case, a user must have the necessary cookies issued to proceed to content without being sent back to the login page.
Example
VBScript in an ASP page
Assume ”forms authentication" is being used for this IIS server. Further assume the items Username and Password are collected through an HTML form that has it's ACTION attribute set to an ASP script with the following code included. A "success" target URL is set up in the form if login is successful, usually as a "hidden" variable in the form.
<%
Name = Request("UserName")
Password = Request("Password")
URL = Request("SuccessURL")
Set IVerifUsr = Server.CreateObject("Membership.VerifUsr.1")
If IVerifUser.
returnedURL = oVerifUsr.VerifyCredentials(Name,Password,URL)
Response.Redirect returnedURL
%>This method issues the necessary cookies to a new registered user account that has been migrated from a previous anonymous cookie account. The GUID value for the new registered account will be the same as for the old cookies account.
IDL Definition
HRESULT IssueCookieToOldUser(BSTR bszUserName);
Parameters
bszUserName
The new username to issue the old cookie to
Return Values
a standard HRESULT value
Remarks
Make sure to actually move the account information to its new location before invoking IssueCookieToOldUser. The GUID value will be fetched for the user using the new account information.
Example
This example moves an anonymous cookie user to the "ou=members" container using the new username.
VBscript in an ASP Page
<% Set oUserObject = Server.CreateObject("membership.userobjects.1")
UserName = "JohnS"
if Request.Cookies("SITESERVER")("GUID") <> "" Then
'
' Get the parent object
Set ParentUserObject = oUserObject.GetObjectAsUser(oUserObject.Parent)
'
' Get the grandparent object
Set TargetContainer = oUserObject.GetObjectAsUser(ParentUserObject.Parent)
'
'Move the object to the target container
TargetContainer.MoveHere oUserObject.ADsPath, "cn=" & UserName
'
' create cookie object
Set NewCookie = Server.CreateObject("Membership.verifusr")
'
' Issue cookie to the old user
NewCookie.IssueCookieToOldUser(cstr(UserName))
End if
%>This method is used to issue the necessary cookies to a new registered user account that did not previously have a corresponding anonymous cookie account.
IDL Definition
HRESULT IssueCookiesToNewUser(
BSTR bszUserName,
[out, retval] BSTR* pbstrNewGUIDValue
);Parameters
bszUserName
The name of the new user.
pbstrNewGUIDValue
On return, the BSTR variable contains the user's new GUID value.
Return Values
A standard HRESULT value
Remarks
This method is used to set a new user's Membership cookies during the construction of a new user account as well as generate a GUID value for the account. If the user already has a GUID value associated, use the IssueOldCookiesToNewUser method.
The schema definition for a user requires that each have a GUID value. One must explicitly update the new account's properties with the required GUID.
Example
<%
NewUserName = "FredJ"
ID = "o=company/ou=members/cn=administrator"
Password = "password"
Set IUserObjects = Server.CreateObject("Membership.UserObjects.1")
' assume this AUO is going to be used to create a new user
' with username "FredJ"
' set the new username in the AUO
IUserObjects.SetUserName(cstr(NewUserName))
' use these binding credentials to access the DS
IUserObjects.BinsAs "", ID,Password
' Now work with cookies
Set IVerifUsr = Server.CreateObject("Membership.VerifUsr.1")
' Check to see if the user already has a GUID
If Request("MEMUSER") <> "" Then
' No username and likely no GUID; Issue Cookies and Get a new GUID
GUIDValue = IVerifUsr.IssueCookiesToNewUser(Username)
' ADSI object loaded and the value put
' the required GUID value in the object
IUserObjects.Put "GUID", cstr(GUIDValue)
Else
GUIDValue = IUserObjects.Get("GUID")
IVerifUsr.IssueOldCookiesToNewUser Username, GUIDValue
End If
' the info in the ADSI object committed to DS
IUserObjects.SetInfo
%>This method generates and returns the Secure Hashing Algorithm (SHA) hash of the subject name and issuer name for a user's certificate.
IDL Definition
HRESULT HashCert(
BSTR bszSubjectName,
BSTR bszIssuerName,
[out, retval] BSTR* pbstrCertHash
);Parameters
bszSubjectName
The subject in the certificate
bszIssuerName
The certificate issuer name
pbstrCertHash
On return, the hash of the certificate.
Return Values
A standard HRESULT value
Example
<%
Set gMemUserObject = Server.CreateObject("Membership.UserObjects")
If Request("REMOTE_USER") = "" Then
ScriptError("Not Authenticated")
End if
set x = Server.CreateObject("Membership.verifusr.1")
y = x.HashCert(Request.ClientCertificate("SUBJECT"),Request.ClientCertificate("ISSUER"))
gMemUserObject.Put "userCertificateHash", y
gMemUserObject.setinfo
%>This method issues an updated timestamp cookie to the user that will notify the Membership Authentication server instance on the next request that the user's directory data should be refreshed from the directory service.
IDL Definition
HRESULT IssueRecentChangesCookie(BSTR bszUserName);Parameters
bszUserName
The username of the user. This name should be the name of the user as it appears in the REMOTE_USER server variable. For example, if the relative DN of a user is "cn=JohnS", the username passed to this method should be "JohnS".
Return Values
a standard HRESULT value
Remarks
This method should be invoked whenever a user's properties have been updated in the Membership directory service. It issues or updates the "MemRightsChanged" timestamp cookie using the ASP Response object. This cookie is therefore sent to the client along with the rest of the response. When the user makes their next request, the timestamp notifies the Membership Authentication server instance that the user's properties should be refreshed from the directory store.
This method is invoked by the UserObjects object automatically when a Put/PutEx method is invoked on its IADs interface. In this case, no explicit call is necessary.
Example
<%
Set IUserObjects = Server.CreateObject("Membership.UserObjects")
call IUserObjects.GetObject("","").Put "something","somevalue"
' note that here we got the dispinterface on the ADSI object
' directly using the GetObject method. We must invoke
' IssueRecentChangesCookie explicitly.
Set IVerif = Server.CreateObject("Membership.VerifUsr.1")
' change a property in the directory (code ommited)
IVerif.IssueRecentChangesCookie(Request("Remote_User"))
%>This method checks the username and password against the directory information and returns TRUE if they are valid. It returns FALSE if they are incorrect.
IDL Definition
HRESULT VerifyPassword(
BSTR bszUserName,
BSTR bszPassword,
[out, retval] LONG* plPasswordVerified
);Parameters
bszUserName
The username
bszPassword
The password
plPasswordVerified
On return, the LONG variable holds the result of the verification. The value returned will be either TRUE (1) or FALSE (0). TRUE means that the password was correct.
Return Values
a standard HRESULT value
Example
ASP and VBScript
<% Set IVerifUsr = Server.CreateObject("Membership.VerifUsr")
' assume Username and Password are defined and need to be checked
If IVerifUsr.VerifyPassword(Username,Password) Then
Response.Write "password is correct"
Else
Response.Write "password incorrect"
End If
%>
This method issues the Membership cookies to a specified new user. It is used when creating a new user that had a previously set anonymous GUID value.
IDL Definition
HRESULT IssueOldCookiesToNewUser(
BSTR bszUserName,
BSTR bstrUserGUID
);
Parameters
bszUserName
The new username to issue the cookies under
bszUserGUID
The previous GUID value for the user
Return Values
a standard HRESULT value
Remarks
This method should only be used when creating a new user account for a user that already has a GUID value stored with the Membership directory service.
Example
NewUserName = "FredJ"
ID = "o=company/ou=members/cn=administrator"
Password = "password"
Set IUserObjects = Server.CreateObject("Membership.UserObjects.1")
' assume this AUO is going to be used to create a new user
' with username "FredJ"
' set the new username in the AUO
IUserObjects.SetUserName(cstr(NewUserName))
' use these binding credentials to access the DS
IUserObjects.BinsAs "", ID,Password
' Now work with cookies
Set IVerifUsr = Server.CreateObject("Membership.VerifUsr.1")
' Check to see if the user already has a GUID
If Request("MEMUSER") <> "" Then
' No GUID; Issue Cookies and Get a new GUID
GUIDValue = IVerifUsr.IssueCookiesToNewUser(Username)
' ADSI object loaded and the value put to the object
IUserObjects.Put "GUID", cstr(GUIDValue)
Else
GUIDValue = IUserObjects.Get("GUID")
IVerifUsr.IssueOldCookiesToNewUser Username, GUIDValue
End If
' Now the new user with DN cn=FredJ exists in the default
' AUO provider and the necessary cookies will be sent with
' the response from this page
IUserObjects.SetInfo
%>This method issues a cookie to the page response, inserting the correct Domain portion that the Site Server Membership system requires.
IDL Definition
HRESULT IssueCookie(BSTR bszCookieName, BSTR bszCookieValue);
Parameters
bszCookieName
The name of the cookie
bszCookieValue
The associated value of the cookie
Return Values
A standard HRESULT value
Remarks
This method can be used to simply "reset" a user's cookies that somehow have been lost or are not present.
Example
<%
' The response.buffer line MUST be the first code
' and/or HTML line on the page
Response.Buffer = TRUE
Set UserObjects = Server.CreateObject("Membership.UserObjects")
Set vusr = Server.CreateObject("Membership.verifusr")
vusr.IssueCookie "SITESERVER", "GUID=" & UserObjects.Get("GUID")
vusr.IssueCookie "MEMUSER", UserObjects.Get("cn")
%>The method will cancel a previously assigned cookie from the server's response.
IDL Defintion
HRESULT CancelCookie(BSTR bszCookieName);
Parameters
bszCookieName
The name the cookie was set under
Return Values
A standard HRESULT value
Example
<% Set IVerifUsr = Server.CreateObject("Membership.Verifusr.1")
IVerifUsr.IssueCookie "mycookie", "myvalue"
… ' for some reason, we need to revoke it
IVerifUsr.CancelCookie "mycookie"
%>