About

go-ad-auth is a simple wrapper around the great ldap library to help with Active Directory authentication.

Installing

Using Go Modules:

go get github.com/korylprince/go-ad-auth/v3

Using gopkg.in:

go get gopkg.in/korylprince/go-ad-auth.v3

Dependencies:

If you have any issues or questions create an issue.

API Versions

You should update to the v3 API when possible. The new API is cleaner, more idiomatic, exposes a lot more functionality, and is fully testable.

v3 was created to support Go Modules, so it is backwards compatible with v2. However, updates made to v3 are not backported to v2.

The v3 API is almost a complete rewrite of the older gopkg.in/korylprince/go-ad-auth.v1 API. There are similarities, but v3 is not backwards-compatible.

One notable difference to be careful of is that while v1's Login will return false if the user is not in the specified group, v3's AuthenticateExtended will return true if the user authenticated successfully, regardless if they were in any of the specified groups or not.

Usage

Example:

config := &auth.Config{
    Server:   "ldap.example.com",
    Port:     389,
    BaseDN:   "OU=Users,DC=example,DC=com",
    Security: auth.SecurityStartTLS,
}

username := "user"
password := "pass"

status, err := auth.Authenticate(config, username, password)

if err != nil {
    //handle err
    return
}

if !status {
    //handle failed authentication
    return
}

See more advanced examples on go.dev.

Testing

go test -v

Most tests will be skipped unless you supply the following environment variables to connect to an Active Directory server:

Name	Description
ADTEST_SERVER	Hostname or IP Address of an Active Directory server
ADTEST_PORT	Port to use - defaults to 389
ADTEST_BIND_UPN	userPrincipalName (user@domain.tld) of admin user
ADTEST_BIND_PASS	Password of admin user
ADTEST_BIND_SECURITY	`NONE` \|\| `TLS` \|\| `STARTTLS` \|\| `INSECURETLS` \|\| `INSECURESTARTTLS` - defaults to `STARTTLS`
ADTEST_BASEDN	LDAP Base DN - for testing the root DN is recommended, e.g. `DC=example,DC=com`
ADTEST_PASSWORD_UPN	userPrincipalName of a test user that will be used to test password changing functions

Nested Groups

Since v3.1.0, AuthenticateExtended and Conn.ObjectGroups will automatically search for nested groups. For example, if User A is a member of Group A, and Group A is a member of Group B, using Conn.ObjectGroups on User A will return both Group A and Group B.

Security

SQL Injection is a well known attack vector, and most SQL libraries provide mitigations such as prepared statements. Similarly, LDAP Injection, while not seen often in the wild, is something we should be concerned with.

Since v2.2.0, this library sanitizes inputs (with ldap.EscapeFilter) that are used to create LDAP filters in library functions, namely GetDN and GetAttributes. This means high level functions in this library are protected against malicious inputs. If you use Search or SearchOne, take care to sanitize any untrusted inputs you use in your LDAP filter.

korylprince / go-ad-auth

readme