IADsUser::SetPassword method

Applies to: desktop apps only

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, enables 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.

Syntax

HRESULT SetPassword(
  [in]  BSTR bstrNewPassword
);

Parameters

bstrNewPassword [in]

A BSTR that contains the new password.

Return value

This method supports the standard return values, including S_OK. For other return values, see ADSI Error Codes.

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.

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.

In Active Directory, the caller must have the Reset Password extended control access right to set the password with this method.

Examples

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

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

See also

IADsMembers

IADsUser

IADsUser Property Methods

IADs::SetInfo

NetUserSetInfo

ADSI Error Codes

IADsServiceOperations

Send comments about this topic to Microsoft

Build date: 2/3/2012