LDAP: Status of User Accounts in a Directory Server Database

BIND response controls

Response controls might contain information about the status of a user account in a directory server database when included in a BIND response. The Password Expired Control and the Password Expiring Control are two examples of controls that might be included in a BIND response. Software that interacts with a directory server using LDAP should always check for controls in the response. Software that fails to check for response controls in LDAP responses risks losing important information.

Password Expired Control

The BIND response might include a Password Expired Control. The password expired control, when included in the BIND response, indicates that the users’ password must be reset before the user can authenticate. The OID of the Password Expired Control is "2.16.840.1.113730.3.4.4" and the value field of the response control should be "0" (zero). Some servers may include this control in a successful BIND response to indicate that the users’ password must be changed before that user is allowed to perform any other LDAP operations. If the password is expired, the server should set the LDAP result code to Unwilling To Perform (53).

Password Expiring Control

The BIND response might include the Password Expiring Control. This control indicates that the users’ password is expiring soon, and the value is set to the number of seconds before the users’ password will expire. The OID of the Password Expiring Control is "2.16.840.1.113730.3.4.5". When this control appears in the BIND response, authentication agents can notify a user that the password is about to expire.

Note: some UNIX LDAP authentication code (notably ldap_cachemgr on Solaris and OpenSolaris) incorrectly expects that the OID for the password expiring response control be published in the root DSE, and if it is not, the password expiring control and its associated values are not used by the authentication subsystem. The root DSE must publish request control OIDs that the server supports, not the response control OIDs. In any case, if your UNIX authentication does not provide a notice that your password is about to expire, the cause might be that your authentication LDAP code is broken and expects that a response control be published in the root DSE.

Account Usable Control

The UnboundID Directory Server also supports the Account Usable request and response controls. These request and response controls were designed by Sun Microsystems and are not based on any IETF draft or proposal. The account usable request control can be included in a search request and the response control is returned in the search response – the values in the response control are associated with the object of the search request. The OID of the request controls is "1.3.6.1.4.1.42.2.27.9.5.8" and the OID of the account usable response control is "1.3.6.1.4.1.42.2.27.9.5.8".

Certain values associated with the object of the search request are encoded into the response control as follows:

isUsable (integer value of seconds until password expiration)
isNotUsable – a “blob” that may contain:

accountIsInactive – the account is locked or deactivated (boolean)
mustChangePassword – the users’ password must be changed before any other operations can be conducted (boolean)
passwordIsExpired – the users’ password has expired (boolean)
remainingGraceLogins – the number of grace logins remaining (integer)
secondsUntilUnlock – the time in seconds before the account is automatically unlocked (integer)

The Account Usable Request Control API is available in the Commercial Edition of the UnboundID LDAP SDK.

Sample Code

The file AuthDemo.java binds to directory server and demonstrates the use of the Who Am I? extended request and the AuthorizationIdentityRequestControl, and demonstrates a methodology for handling response controls (such as the password expired and password expiring controls).

The file BindDemo.java binds to the directory server specified in the command line options, checks whether the AccountUsableRequestControl and the OperationPurposeRequestControl are supported by the server, and if they are, issues a bind request with the OperationPurposeRequestControl control attached, and a search request with the AccountUsableRequestControl attached, and prints the results of the bind and the search. The BindDemo is executed like this:

java -cp CLASSPATH samplecode.BindDemo \
 --hostname hostname                   \
 --port port                           \
 --baseObject dn                       \
 --bindDn bindDn                       \
 --bindPassword password