IADsUser::SetPassword

The IADsUser::SetPassword method sets the user password to a specified value. For the LDAP provider, the user account must have been created and stored in the underlying directory using IADs::SetInfo before IADsUser::SetPassword is called.

The WinNT provider, however, allows you to set the password on a newly created user object prior to calling SetInfo. This ensures that you create passwords that comply with the system password policy before you create the user account.

HRESULT SetPassword( 
  BSTR bstrNewPassword
);

Parameters

bstrNewPassword

[in] The new password value.

Return Values

Remarks

The LDAP provider for Active Directory uses one of three processes to set the password; third-party LDAP directories such as iPlanet do not use this password authentication process. The method may vary according to the network configuration. Attempts to set the password occur in the following order:

• First, the LDAP provider attempts to use LDAP over a 128-bit SSL connection. For LDAP SSL to operate successfully, the LDAP server must have the appropriate server authentication certificate installed and the clients running the ADSI code must trust the authority that issued those certificates. Both the server and the client must support 128-bit encryption.
• Second, if the SSL connection is unsuccessful, the LDAP provider attempts to use Kerberos. On Windows 2000, Kerberos may not support cross-forest authentication. So on Windows 2000, for this to work properly, bind to the user object using either a serverless ADsPath, such as "LDAP://CN=Jeff Smith, CN=sales, DC=Fabrikam, DC=com" or a server-explicit ADsPath that contains the DNS server name, such as "LDAP://server1.Fabrikam.com/CN=jeff smith, CN=Sales, DC=Fabrikam, DC=com". Later enhancements to Kerberos support cross-forest authentication.
• Third, if Kerberos is unsuccessful, the LDAP provider attempts a NetUserSetInfo API call. In previous releases, ADSI called NetUserSetInfo in the security context in which the thread was running, and not the security context specified in the call to IADsOpenDSObject::OpenDSObject or ADsOpenObject. In later releases, this was changed so that the ADSI LDAP provider would impersonate the user specified in the OpenDSObject call when it calls NetUserSetInfo.

The NDS, NWCOMPAT, WinNT and LDAP system providers all support SetPassword. The NDS provider, however, only supports SetPassword on objects in containers where Bindery emulation is enabled.

Example Code [Visual Basic]

The following code example shows how to set the user password, if you have the permission to do so.

Dim usr As IADsUser
Dim szPassword As String
On Error GoTo Cleanup

' Add code to securely get the password.

Set usr = GetObject("LDAP://MyLdapSvr/CN=JeffSmith,DC=Fabrikam")
usr.SetPassword szPassword

Cleanup:
	If (Err.Number<>0) Then
		MsgBox("An error has occurred. " & Err.Number)
	End If
	Set usr = Nothing

Example Code [C++]

The following code example shows how to set the user password, if you have the permission to do so.

HRESULT SetPassword(IADsUser *pUser, BSTR password)
{
	HRESULT hr=S_OK;
	if(!pUser) { return E_FAIL;}
	hr = pUser->SetPassword(password);
	if (hr == S_OK) printf("User password has been set");
	pUser->Release();
	return hr;
}

Requirements

Client: Included in Windows XP and Windows 2000 Professional.
Server: Included in Windows Server 2003 and Windows 2000 Server.
Redistributable: Requires Active Directory Client Extension on Windows NT 4.0 SP6a and Windows 95/98/Me.
Header: Declared in Iads.h.

See Also

IADsMembers, IADsUser, IADsUser Property Methods, IADs::SetInfo, ADSI Error Codes, IADsServiceOperations