Editing Lightweight Directory Access Protocol (section)

==Operations==

===Add===
The ADD operation inserts a new entry into the directory-server database.<ref>[http://tools.ietf.org/html/rfc4511#section-4.7 Add section of RFC4511]</ref> If the distinguished name in the add request already exists in the directory, then the server will not add a duplicate entry but will set the result code in the add result to decimal 68, "entryAlreadyExists".<ref>[http://tools.ietf.org/html/rfc4511#appendix-A LDAP result codes]</ref>
* LDAP-compliant servers will never dereference the distinguished name transmitted in the add request when attempting to locate the entry, that is, distinguished names are never de-aliased.
* LDAP-compliant servers will ensure that the distinguished name and all attributes conform to naming standards.
* The entry to be added must not exist, and the immediate superior must exist.
<syntaxhighlight lang="ldif">
dn: uid=user,ou=people,dc=example,dc=com
changetype: add
objectClass:top
objectClass:person
uid: user
sn: last-name
cn: common-name
userPassword: password
</syntaxhighlight>

In the above example, <code>uid=user,ou=people,dc=example,dc=com</code> must not exist, and <code>ou=people,dc=example,dc=com</code> must exist.

===Bind (authenticate)===
When an LDAP session is created, that is, when an LDAP client connects to the server, the '''authentication state''' of the session
is set to anonymous. The BIND operation establishes the authentication state for a session.

Simple BIND and SASL PLAIN can send the user's DN and password in [[plaintext]], so the connections utilizing either Simple or SASL PLAIN
should be encrypted using [[Transport Layer Security]] (TLS). The server typically checks the password against the <code>userPassword</code>
attribute in the named entry.  Anonymous BIND (with empty DN and password) resets the connection to anonymous state.

[[Simple Authentication and Security Layer|SASL]] (Simple Authentication and Security Layer) BIND provides authentication services through a
wide range of mechanisms, e.g. [[Kerberos (protocol)|Kerberos]] or the [[client certificate]] sent with TLS.<ref>[https://www.iana.org/assignments/sasl-mechanisms/sasl-mechanisms.xml SASL Mechanisms at IANA]</ref>

BIND also sets the LDAP protocol version by sending a version number in the form of an integer. If the client requests a version that the server does not support, the server must set the result code in the BIND response to the code for a protocol error. Normally clients should use LDAPv3, which is the
default in the protocol but not always in LDAP libraries.

BIND had to be the first operation in a session in LDAPv2, but is not required as of LDAPv3. In LDAPv3, each
successful BIND request changes the authentication state of the session and each unsuccessful BIND request resets the authentication state
of the session.

===Delete===
To delete an entry, an LDAP client transmits a properly formed delete request to the server.<ref>[http://tools.ietf.org/html/rfc4511#section-4.8 RFC4511: delete request]</ref>
* A delete request must contain the distinguished name of the entry to be deleted
* Request controls may also be attached to the delete request
* Servers do not dereference aliases when processing a delete request
* Only leaf entries (entries with no subordinates) may be deleted by a delete request. Some servers support an operational attribute <code>hasSubordinates</code> whose value indicates whether an entry has any subordinate entries, and some servers support an operational attribute <code>numSubordinates</code><ref>[http://tools.ietf.org/html/draft-boreham-numsubordinates-01 Boreham Draft (numSubordinates)]</ref> indicating the number of entries subordinate to the entry containing the <code>numSubordinates</code> attribute.
* Some servers support the subtree delete request control permitting deletion of the DN and all objects subordinate to the DN, subject to access controls. Delete requests are subject to access controls, that is, whether a connection with a given authentication state will be permitted to delete a given entry is governed by server-specific access control mechanisms.

===Search and compare===
The Search operation is used to both search for and read entries.  Its parameters are:
; baseObject : The name of the base object entry (or possibly the root) relative to which the search is to be performed.
; scope : What elements below the baseObject to search. This can be <code>BaseObject</code> (search just the named entry, typically used to read one entry), <code>singleLevel</code> (entries immediately below the base DN), or <code>wholeSubtree</code> (the entire subtree starting at the base DN).
; filter : Criteria to use in selecting elements within scope. For example, the filter <code>(&(objectClass=person)(|(givenName=John)(mail=john*)))</code> will select "persons" (elements of objectClass <code>person</code>) where the matching rules for <code>givenName</code> and <code>mail</code> determine whether the values for those attributes match the filter assertion. Note that a common misconception is that LDAP data is case-sensitive, whereas in fact matching rules and ordering rules determine matching, comparisons, and relative value relationships. If the example filters were required to match the case of the attribute value, an ''extensible match filter'' must be used, for example, <code>(&(objectClass=person)(|(givenName:caseExactMatch:=John)(mail:caseExactSubstringsMatch:=john*)))</code>
; derefAliases : Whether and how to follow alias entries (entries that refer to other entries),
; attributes : Which attributes to return in result entries.
; sizeLimit, timeLimit : Maximum number of entries to return, and maximum time to allow search to run. These values, however, cannot override any restrictions the server places on size limit and time limit.
; typesOnly : Return attribute types only, not attribute values.

The server returns the matching entries and potentially continuation references. These may be returned in any order.  The final result will include the result code.

The Compare operation takes a DN, an attribute name and an attribute value, and checks if the named entry contains that attribute with that value.

===Modify===
The MODIFY operation is used by LDAP clients to request that the LDAP server make changes to existing entries.<ref>[http://tools.ietf.org/html/rfc4511#section-4.6 Modify Section of RFC4511]</ref> Attempts to modify entries that do not exist will fail. MODIFY requests are subject  to access controls as implemented by the server.

The MODIFY operation requires that the distinguished name (DN) of the entry be specified, and a sequence of changes. Each change in the sequence must be one of:
* add (add a new value, which must not already exist in the attribute)
* delete (delete an existing value)
* replace (replace an existing value with a new value)

[[LDIF]] example of adding a value to an attribute:

<syntaxhighlight lang="ldif">
dn: dc=example,dc=com
changetype: modify
add: cn
cn: the-new-cn-value-to-be-added
-
</syntaxhighlight>

To replace the value of an existing attribute, use the <code>replace</code> keyword. If the attribute is multi-valued, the client must specify the value of the attribute to update.

To delete an attribute from an entry, use the keyword <code>delete</code> and the changetype designator <code>modify</code>. If the attribute is multi-valued, the client must specify the value of the attribute to delete.

There is also a Modify-Increment extension<ref>{{cite IETF|title=LDAP Modify-Increment Extension|rfc=4525|first=K.|last=Zeilenga}}</ref> which allows an incrementable attribute value to be incremented by a specified amount. The following example using LDIF increments <code>employeeNumber</code> by <code>5</code>:

<syntaxhighlight lang="ldif">
dn: uid=user.0,ou=people,dc=example,dc=com
changetype: modify
increment: employeeNumber
employeeNumber: 5
-
</syntaxhighlight>

When LDAP servers are in a replicated topology, LDAP clients should consider using the post-read control to verify updates instead of a search after an update.<ref>{{Cite IETF|title = Lightweight Directory Access Protocol (LDAP) Read Entry Controls|rfc = 4527|publisher = [[IETF]]|last = Zeilenga|first = K.}}</ref> The post-read control is designed so that applications need not issue a search request after an update – it is bad form to retrieve an entry for the sole purpose of checking that an update worked because of the replication [[eventual consistency]] model. An LDAP client should not assume that it connects to the same directory server for each request because architects may have placed load-balancers or LDAP proxies or both between LDAP clients and servers.

===Modify DN===
Modify DN (move/rename entry) takes the new RDN (Relative Distinguished Name), optionally the new parent's DN, and a flag that indicates whether to delete the value(s) in the entry that match the old RDN.  The server may support renaming of entire directory subtrees.

An update operation is atomic: Other operations will see either the new entry or the old one.  On the other hand, LDAP does not define transactions of multiple operations: If you read an entry and then modify it, another client may have updated the entry in the meantime.  Servers may implement extensions<ref>[http://tools.ietf.org/html/draft-zeilenga-ldap-txn-15 INTERNET-DRAFT LDAP Transactions draft-zeilenga-ldap-txn-15.txt]</ref> that support this, though.

===Extended operations===
The Extended Operation is a generic LDAP operation that can define new operations that were not part of the original protocol specification. StartTLS is one of the most significant extensions.  Other examples include Cancel and Password Modify.{{cn|date=January 2024}}

====StartTLS====
The [[StartTLS]] operation establishes [[Transport Layer Security]] (the descendant of [[Transport Layer Security|SSL]]) on the connection.  It can provide data confidentiality (to protect data from being observed by third parties) and/or data integrity protection (which protects the data from tampering).  During TLS negotiation the server sends its [[X.509]] certificate to prove its identity.  The client may also send a certificate to prove its identity.  After doing so, the client may then use [[Simple Authentication and Security Layer|SASL]]/EXTERNAL.  By using the SASL/EXTERNAL, the client requests the server derive its identity from credentials provided at a lower level (such as TLS).  Though technically the server may use any identity information established at any lower level, typically the server will use the identity information established by TLS.

Servers also often support the non-standard "LDAPS" ("Secure LDAP", commonly known as "LDAP over SSL") protocol on a separate port, by default 636.  LDAPS differs from LDAP in two ways:
1) upon connect, the client and server establish TLS before any LDAP messages are transferred (without a StartTLS operation) and
2) the LDAPS connection must be closed upon TLS closure.

Some "LDAPS" client libraries only encrypt communication; they do not check the host name against the name in the supplied certificate.<ref>[http://shibboleth.net/community/advisories/secadv_20120227.txt Shibboleth Security alert 20120227]</ref>

===Abandon===
The Abandon operation requests that the server abort an operation named by a message ID.  The server need not honor the request.  Neither Abandon nor a successfully abandoned operation send a response.  A similar Cancel extended operation does send responses, but not all implementations support this.

===Unbind===
The Unbind operation abandons any outstanding operations and closes the connection.  It has no response.  The name is of historical origin, and is ''not'' the opposite of the Bind operation.<ref>[http://tools.ietf.org/html/rfc4511#section-4.3 Tools.ietf.org]</ref>

Clients can abort a session by simply closing the connection, but they should use Unbind.<ref>[http://tools.ietf.org/html/rfc4511#section-5.3 Tools.ietf.org]</ref> Unbind allows the server to gracefully close the connection and free resources that it would otherwise keep for some time until discovering the client had abandoned the connection. It also instructs the server to cancel operations that can be canceled, and to not send responses for operations that cannot be canceled.<ref>[http://tools.ietf.org/html/rfc4511#section-3.1 Tools.ietf.org]</ref>