goat

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:

• github.com/go-ldap/ldap
• golang.org/x/text/encoding/unicode

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

Documentation

Index

• func Authenticate(config *Config, username, password string) (bool, error)
• func AuthenticateExtended(config *Config, username, password string, attrs, groups []string) (status bool, entry *ldap.Entry, userGroups []string, err error)
• func UpdatePassword(config *Config, username, oldPasswd, newPasswd string) error
• type Config
  • func (c *Config) Connect() (*Conn, error)
  • func (c *Config) Domain() (string, error)
  • func (c *Config) UPN(username string) (string, error)
• 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

Functions

func Authenticate

func Authenticate(config *Config, username, password string) (bool, error)

Authenticate checks if the given credentials are valid, or returns an error if one occurred. username may be either the sAMAccountName or the userPrincipalName.

func AuthenticateExtended

func AuthenticateExtended(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.

func UpdatePassword

func UpdatePassword(config *Config, username, oldPasswd, newPasswd string) error

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.

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

func (c *Config) Connect() (*Conn, error)

Connect returns an open connection to an Active Directory server or an error if one occurred.

func (*Config) Domain

func (c *Config) Domain() (string, error)

Domain returns the domain derived from BaseDN or an error if misconfigured.

func (*Config) UPN

func (c *Config) UPN(username string) (string, error)

UPN returns the userPrincipalName for the given username or an error if misconfigured.

type Conn

type Conn struct {
	Conn   *ldap.Conn
	Config *Config
}

Conn represents an Active Directory connection.

func (*Conn) Bind

func (c *Conn) Bind(upn, password string) (bool, error)

Bind authenticates the connection with the given userPrincipalName and password and returns the result or an error if one occurred.

func (*Conn) GetAttributes

func (c *Conn) GetAttributes(attr, value string, attrs []string) (*ldap.Entry, error)

GetAttributes returns the *ldap.Entry with the given attributes for the object with the given attribute value or an error if one occurred.

func (*Conn) GetDN

func (c *Conn) GetDN(attr, value string) (string, error)

GetDN returns the DN for the object with the given attribute value or an error if one occurred.

func (*Conn) GroupDN

func (c *Conn) GroupDN(group string) (string, error)

GroupDN returns the DN of the group with the given cn or an error if one occurred.

func (*Conn) ModifyDNPassword

func (c *Conn) ModifyDNPassword(dn, newPasswd string) error

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

func (c *Conn) ObjectGroups(attr, value string, groups []string) ([]string, error)

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.

func (*Conn) Search

func (c *Conn) Search(filter string, attrs []string, sizeLimit int) ([]*ldap.Entry, error)

Search returns the entries for the given search criteria or an error if one occurred.

func (*Conn) SearchOne

func (c *Conn) SearchOne(filter string, attrs []string) (*ldap.Entry, error)

SearchOne returns the single entry for the given search criteria or an error if one occurred. An error is returned if exactly one entry is not returned.

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
	SecurityStartTLS
)

Security will default to SecurityNone if not given.