summaryrefslogtreecommitdiffstats
path: root/README.md
diff options
context:
space:
mode:
authorned <ned@appliedtrust.com>2014-11-12 22:52:16 +0100
committerned <ned@appliedtrust.com>2014-11-12 22:52:16 +0100
commitf4e67fa4cd924fbe6f271611514caf5589e6a6e5 (patch)
treee696dd77956b8e1ce1aa342a35036db3a9494575 /README.md
parentPing / Abandon request should not expect response (diff)
downloadldap-f4e67fa4cd924fbe6f271611514caf5589e6a6e5.tar
ldap-f4e67fa4cd924fbe6f271611514caf5589e6a6e5.tar.gz
ldap-f4e67fa4cd924fbe6f271611514caf5589e6a6e5.tar.bz2
ldap-f4e67fa4cd924fbe6f271611514caf5589e6a6e5.tar.lz
ldap-f4e67fa4cd924fbe6f271611514caf5589e6a6e5.tar.xz
ldap-f4e67fa4cd924fbe6f271611514caf5589e6a6e5.tar.zst
ldap-f4e67fa4cd924fbe6f271611514caf5589e6a6e5.zip
Diffstat (limited to 'README.md')
-rw-r--r--README.md113
1 files changed, 113 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..c72fca8
--- /dev/null
+++ b/README.md
@@ -0,0 +1,113 @@
+# LDAP for Golang
+
+This library provides basic LDAP v3 functionality for the GO programming language.
+
+The **client** portion is limited, but sufficient to perform LDAP authentication and directory lookups (binds and searches) against any modern LDAP server (tested with OpenLDAP and AD).
+
+The **server** portion implements Bind and Search from [RFC4510](http://tools.ietf.org/html/rfc4510), has good testing coverage, and is compatible with any LDAPv3 client. It provides the building blocks for a custom LDAP server, but you must implement the backend datastore of your choice.
+
+
+## LDAP client notes:
+
+### A simple LDAP bind operation:
+```go
+l, err := ldap.Dial("tcp", fmt.Sprintf("%s:%d", ldapServer, ldapPort))
+// be sure to add error checking!
+defer l.Close()
+err = l.Bind(user, passwd)
+if err==nil {
+ // authenticated
+} else {
+ // invalid authentication
+}
+```
+
+### A simple LDAP search operation:
+```go
+search := &SearchRequest{
+ BaseDN: "dc=example,dc=com",
+ Filter: "(objectclass=*)",
+}
+searchResults, err := l.Search(search)
+// be sure to add error checking!
+```
+
+### Implemented:
+* Connecting, binding to LDAP server
+* Searching for entries with filtering and paging controls
+* Compiling string filters to LDAP filters
+* Modify Requests / Responses
+
+### Not implemented:
+* Add, Delete, Modify DN, Compare operations
+* Most tests / benchmarks
+
+### LDAP client examples:
+* examples/search.go: **Basic client bind and search**
+* examples/searchSSL.go: **Client bind and search over SSL**
+* examples/searchTLS.go: **Client bind and search over TLS**
+* examples/modify.go: **Client modify operation**
+
+*Client library by: [mmitton](https://github.com/mmitton), with contributions from: [uavila](https://github.com/uavila), [vanackere](https://github.com/vanackere), [juju2013](https://github.com/juju2013), [johnweldon](https://github.com/johnweldon), [marcsauter](https://github.com/marcsauter), and [nmcclain](https://github.com/nmcclain)*
+
+## LDAP server notes:
+The server library is modeled after net/http - you designate handlers for the LDAP operations you want to support (Bind/Search/etc.), then start the server with ListenAndServe(). You can specify different handlers for different baseDNs - they must implement the interfaces of the operations you want to support:
+```go
+type Binder interface {
+ Bind(bindDN, bindSimplePw string, conn net.Conn) (uint64, error)
+}
+type Searcher interface {
+ Search(boundDN string, searchReq SearchRequest, conn net.Conn) (ServerSearchResult, error)
+}
+type Closer interface {
+ Close(conn net.Conn) error
+}
+```
+
+### A basic bind-only LDAP server
+```go
+func main() {
+ s := ldap.NewServer()
+ handler := ldapHandler{}
+ s.BindFunc("", handler)
+ if err := s.ListenAndServe("localhost:389"); err != nil {
+ log.Fatal("LDAP Server Failed: %s", err.Error())
+ }
+}
+type ldapHandler struct {
+}
+func (h ldapHandler) Bind(bindDN, bindSimplePw string, conn net.Conn) (uint64, error) {
+ if bindDN == "" && bindSimplePw == "" {
+ return ldap.LDAPResultSuccess, nil
+ }
+ return ldap.LDAPResultInvalidCredentials, nil
+}
+```
+
+* Server.EnforceLDAP: Normally, the LDAP server will return whatever results your handler provides. Set the **Server.EnforceLDAP** flag to **true** and the server will apply the LDAP **search filter**, **attributes limits**, **size/time limits**, **search scope**, and **base DN matching** to your handler's dataset. This makes it a lot simpler to write a custom LDAP server without worrying about LDAP internals.
+
+### LDAP server examples:
+* examples/server.go: **Basic LDAP authentication (bind and search only)**
+* examples/proxy.go: **Simple LDAP proxy server.**
+* server_test: **The tests have examples of all server functions.**
+
+*Warning: Do not use the example SSL certificates in production!*
+
+### Known limitations:
+
+* Golang's TLS implementation does not support SSLv2. Some old OSs require SSLv2, and are not able to connect to an LDAP server created with this library's ListenAndServeTLS() function. If you *must* support legacy (read: *insecure*) SSLv2 clients, run your LDAP server behind HAProxy.
+
+### Not implemented:
+All of [RFC4510](http://tools.ietf.org/html/rfc4510) is implemented **except**:
+* 4.1.11. Controls
+* 4.5.1.3. SearchRequest.derefAliases
+* 4.5.1.5. SearchRequest.timeLimit
+* 4.5.1.6. SearchRequest.typesOnly
+* 4.6. Modify Operation
+* 4.7. Add Operation
+* 4.8. Delete Operation
+* 4.9. Modify DN Operation
+* 4.10. Compare Operation
+* 4.14. StartTLS Operation
+
+*Server library by: [nmcclain](https://github.com/nmcclain)*