3.1.1.3.1.5.2 userPassword

Active Directory supports modifying passwords on objects via the userPassword attribute, provided that (1) either the DC is running as AD LDS, or the DC is running as AD DS and the domain functional level is DS_BEHAVIOR_WIN2003 or greater, and (2) the fUserPwdSupport heuristic is TRUE in the dSHeuristics attribute (section 6.1.1.2.4.1.2). If fUserPwdSupport is FALSE, the userPassword attribute is treated as an ordinary attribute and has no special semantics associated with it. If fUserPwdSupport is TRUE but the DC is running as AD DS and the domain functional level is less than DS_BEHAVIOR_WIN2003, the DC fails the operation with the error constraintViolation / ERROR_NOT_SUPPORTED.

As with the unicodePwd attribute, changing a password via the userPassword attribute is modeled as an LDAP Modify operation containing a Delete operation followed by an Add operation, and resetting a password is modeled as an LDAP Modify operation containing a single Replace operation. The control access rights required are the same as for the unicodePwd attribute, as is the requirement that when changing a password, Vdel MUST match the object's current password.

The special encoding required for updating the unicodePwd attribute is not used with the userPassword attribute; that is, Vpassword = V. The same restrictions on SSL/TLS- or SASL-protected connections are enforced. The password values are sent to the server as UTF-8 strings, and surrounding quotation marks are not used. For example, the following LDAP Data Interchange Format (LDIF) sample changes a password from oldPassword to newPassword.

 dn: CN=John Smith, OU=Users,DC=Fabrikam,DC=com
 changetype: modify
 delete: userPassword
 userPassword: oldPassword
 -
 add: userPassword
 userPassword: newPassword
 -

The following example uses LDIF to reset the password to newPassword.

 dn: CN=John Smith, OU=Users,DC=Fabrikam,DC=com
 changetype: modify
 replace: userPassword
 userPassword: newPassword
 -

Optionally, when performing a password change operation, the add operation portion of the LDAP modify can be omitted. The server treats this as a request to change the user or inetOrgPerson object's password to the empty string.