README
¶
About
go-ad-auth is a simple wrapper around the great ldap library to help with Active Directory authentication.
Installing
go get gopkg.in/korylprince/go-ad-auth.v2
Dependencies:
If you have any issues or questions create an issue.
New API
The v2 API is almost a complete rewrite of the older gopkg.in/korylprince/go-ad-auth.v1 API. There are similarities, but v2 is not backwards-compatible.
The new API is cleaner, more idiomatic, exposes a lot more functionality and is fully testable.
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, v2's AuthenticateExtended will return true if the user authenticated successfully, regardless if they were in any of the specified groups or not.
Usage
godoc gopkg.in/korylprince/go-ad-auth.v2
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 examples on GoDoc.
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 - 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 |
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.
Documentation
¶
Index ¶
- func Authenticate(config *Config, username, password string) (bool, error)
- func AuthenticateExtended(domain string, config *Config, username, password string, ...) (status bool, entry *ldap.Entry, userGroups []string, err error)
- func UpdatePassword(config *Config, username, oldPasswd, newPasswd string) error
- type Config
- type Conn
- func (c *Conn) Bind(upn, password string) (bool, error)
- func (c *Conn) GetAttributes(attr, value string, attrs []string) (*ldap.Entry, error)
- func (c *Conn) GetDN(attr, value string) (string, error)
- func (c *Conn) GroupDN(group string) (string, error)
- func (c *Conn) ModifyDNPassword(dn, newPasswd string) error
- func (c *Conn) ObjectGroups(attr, value string, groups []string) ([]string, error)
- func (c *Conn) Search(filter string, attrs []string, sizeLimit int) ([]*ldap.Entry, error)
- func (c *Conn) SearchOne(filter string, attrs []string) (*ldap.Entry, error)
- type SecurityType
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Authenticate ¶
Authenticate checks if the given credentials are valid, or returns an error if one occurred. username may be either the sAMAccountName or the userPrincipalName.
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
}
Output:
func AuthenticateExtended ¶
func AuthenticateExtended(domain string, config *Config, username, password string, attrs, groups []string) (status bool, entry *ldap.Entry, userGroups []string, err error)
AuthenticateExtended checks if the given credentials are valid, or returns an error if one occurred. username may be either the sAMAccountName or the userPrincipalName. entry is the *ldap.Entry that holds the DN and any request attributes of the user. If groups is non-empty, userGroups will hold which of those groups the user is a member of. groups can be a list of groups referenced by DN or cn and the format provided will be the format returned.
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, entry, groups, err := auth.AuthenticateExtended(config, username, password, []string{"cn"}, []string{"Domain Admins"})
if err != nil {
//handle err
return
}
if !status {
//handle failed authentication
return
}
if len(groups) == 0 {
//handle user not being in any groups
return
}
//get attributes
cn := entry.GetAttributeValue("cn")
fmt.Println(cn)
Output:
func UpdatePassword ¶
UpdatePassword checks if the given credentials are valid and updates the password if they are, or returns an error if one occurred. UpdatePassword is used for users resetting their own password.
Example ¶
config := &auth.Config{
Server: "ldap.example.com",
Port: 389,
BaseDN: "OU=Users,DC=example,DC=com",
Security: auth.SecurityStartTLS,
}
username := "user"
password := "pass"
newPassword := "Super$ecret"
if err := auth.UpdatePassword(config, username, password, newPassword); err != nil {
//handle err
}
Output:
Types ¶
type Config ¶
type Config struct {
Server string
Port int
BaseDN string
Security SecurityType
}
Config contains settings for connecting to an Active Directory server.
func (*Config) Connect ¶
Connect returns an open connection to an Active Directory server or an error if one occurred.
type Conn ¶
type Conn struct {
Conn *ldap.Conn
Config *Config
}
Conn represents an Active Directory connection.
func (*Conn) Bind ¶
Bind authenticates the connection with the given userPrincipalName and password and returns the result or an error if one occurred.
func (*Conn) GetAttributes ¶
GetAttributes returns the *ldap.Entry with the given attributes for the object with the given attribute value or an error if one occurred. attr and value are sanitized.
func (*Conn) GetDN ¶
GetDN returns the DN for the object with the given attribute value or an error if one occurred. attr and value are sanitized.
func (*Conn) GroupDN ¶
GroupDN returns the DN of the group with the given cn or an error if one occurred.
func (*Conn) ModifyDNPassword ¶
ModifyDNPassword sets a new password for the given user or returns an error if one occurred. ModifyDNPassword is used for resetting user passwords using administrative privileges.
func (*Conn) ObjectGroups ¶
ObjectGroups returns which of the given groups (referenced by DN) the object with the given attribute value is in, if any, or an error if one occurred.
type SecurityType ¶
type SecurityType int
SecurityType specifies the type of security to use when connecting to an Active Directory Server.
const ( SecurityNone SecurityType = iota SecurityTLS SecurityBlindTLS SecurityStartTLS )
Security will default to SecurityNone if not given.
Source Files