goactivedirectory

README

go-activedirectory

go-activedirectory is an ldap client around go-ldap for authN (authentication) and authZ (authorization) for Microsoft Active Directory with range retrieval support for large Active Directory installations.

Installing

Using Go modules

go get github.com/gaikwadpratik/go-activedirectory

Dependencies:

• github.com/go-ldap/ldap

Usage

Example: Basic usage

conf := goactivedirectory.ActiveDirectoryConnConfig{
    ServerConfig: &goactivedirectory.ServerConfig{
		Url: os.Getenv("ldapUrl"),
	},
	AdminUsername: os.Getenv("AdminUsername"),
	AdminPassword: os.Getenv("AdminPassword"),
	BaseDN:        os.Getenv("DefaultNamingContext"),
}

adInstance, err = goactivedirectory.NewActiveDirectory(&conf)
if err != nil {
	log.Fatal(err)
}

adInstance now can be used to perform all other functionality from the library.

if BaseDN is not known, it can be retrieved with below example:

serverConfig := &activedirectory.ServerConfig{
	Url: os.Getenv("ldapUrl"),
}
val, err := activedirectory.GetAttributeOnRootDSE(serverConfig, "defaultNamingContext")

The username and password specified in the configuration are what are used for user and group lookup operations. So they should be of an elevated or admin user

Cloning and Testing

Clone the repo using

git clone git@github.com:GaikwadPratik/go-activedirectory.git

Run test cases run ginkgo -r after setting below Environment variables in .env file

Name	Description
ldapUrl	Url of server to connect (ldaps://example.com or ldap://example.com)
BaseDN	LDAP Base DN - for testing the root DN is recommended, e.g. DC=example,DC=com
AdminUsername	userPrincipalName (user@domain.tld) of admin user
AdminPassword	Password of admin user
GroupName	commonName of a test group that DOES exist
GroupNonexistantName	commonName of a test group that does NOT exist
GroupDNName	distinguishedName of a test group DOES exist
GroupInvalidDNName	distinguishedName of a test group that does NOT exist or is wrong
GroupNonexistantDNName	distinguishedName of a test group that does NOT exist
Username	commonName of a test user that DOES exist
UsernameNonexistant	commonName of a test user that does NOT exist
UsernameDN	distinguishedName of a test user DOES exist
UsernameDNInvalid	distinguishedName of a test user that does NOT exist or is wrong
UsernameNonexistantDN	distinguishedName of a test user that does NOT exist
Password	Password of test user
PasswordInvalid	Invalid or some random password
Upn	userPrincipalName of a test user that will be used

Documentation

Index

• func GetAttributeOnRootDSE(config *ServerConfig, attributeName string) (string, error)
• func GetRootDSE(config *ServerConfig) ([]*ldap.Entry, error)
• type ActiveDirectory
  • func NewActiveDirectory(config *ActiveDirectoryConnConfig) (*ActiveDirectory, error)
  • func (ad ActiveDirectory) Authenticate(username string, password string) (bool, error)
  • func (ad ActiveDirectory) Cleanup() error
  • func (ad ActiveDirectory) FindGroup(groupName string) (*ActiveDirectoryGroup, error)
  • func (ad ActiveDirectory) FindGroups() ([]*ActiveDirectoryGroup, error)
  • func (ad ActiveDirectory) FindUser(username string) (*ActiveDirectoryUser, error)
  • func (ad ActiveDirectory) FindUsers() ([]*ActiveDirectoryUser, error)
  • func (ad ActiveDirectory) GetGroupDistinguishedName(groupName string) (string, error)
  • func (ad ActiveDirectory) GetMemberOfForGroup(input GroupParentsRequest) ([]string, error)
  • func (ad ActiveDirectory) GetMemberOfForUser(input UserParentsRequest) ([]string, error)
  • func (ad ActiveDirectory) GetUPN(username string) (string, error)
  • func (ad ActiveDirectory) GetUserDistinguishedName(userName string) (string, error)
  • func (ad ActiveDirectory) GetUsersForGroup(request UsersForGroupRequest) ([]string, error)
• type ActiveDirectoryConnConfig
• type ActiveDirectoryGroup
• type ActiveDirectoryUser
• type GroupParentsRequest
• type ServerConfig
• type UserParentsRequest
• type UsersForGroupRequest

Functions

func GetAttributeOnRootDSE

func GetAttributeOnRootDSE(config *ServerConfig, attributeName string) (string, error)

GetAttributeOnRootDSE returns a specific attribute value

func GetRootDSE

func GetRootDSE(config *ServerConfig) ([]*ldap.Entry, error)

Returns root configuration of the server

Types

type ActiveDirectory

type ActiveDirectory struct {
	// contains filtered or unexported fields
}

func NewActiveDirectory

func NewActiveDirectory(config *ActiveDirectoryConnConfig) (*ActiveDirectory, error)

NewActiveDirectory initiates a new connection based on provided configuration

func (ActiveDirectory) Authenticate

func (ad ActiveDirectory) Authenticate(username string, password string) (bool, error)

Authenticate Authenticates the username and password by doing a simple bind with the specified credentials. username may be either the sAMAccountName or the userPrincipalName.

func (ActiveDirectory) Cleanup

func (ad ActiveDirectory) Cleanup() error

Cleanup unbinds a user and closes any open connection

func (ActiveDirectory) FindGroup

func (ad ActiveDirectory) FindGroup(groupName string) (*ActiveDirectoryGroup, error)

FindGroup Retrieves the specified group. groupname can be CommonName(cn) or distinguishedName (dn).

func (ActiveDirectory) FindGroups

func (ad ActiveDirectory) FindGroups() ([]*ActiveDirectoryGroup, error)

FindGroups lists all the groups

func (ActiveDirectory) FindUser

func (ad ActiveDirectory) FindUser(username string) (*ActiveDirectoryUser, error)

FindUser Retrieves the specified user. username The username to retrieve information about. Optionally can pass in the distinguishedName (dn) of the user to retrieve.

func (ActiveDirectory) FindUsers

func (ad ActiveDirectory) FindUsers() ([]*ActiveDirectoryUser, error)

FindUsers lists all the users

func (ActiveDirectory) GetGroupDistinguishedName

func (ad ActiveDirectory) GetGroupDistinguishedName(groupName string) (string, error)

GetGroupDistinguishedName returns the distinguished name for the specified group (cn).

func (ActiveDirectory) GetMemberOfForGroup

func (ad ActiveDirectory) GetMemberOfForGroup(input GroupParentsRequest) ([]string, error)

GetMemberOfForGroup For the specified group, get all of the groups that the group is a member of.

func (ActiveDirectory) GetMemberOfForUser

func (ad ActiveDirectory) GetMemberOfForUser(input UserParentsRequest) ([]string, error)

GetMemberOfForUser For the specified username, get all of the groups that the user is a member of returns the DN of the groups

func (ActiveDirectory) GetUPN

func (ad ActiveDirectory) GetUPN(username string) (string, error)

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

func (ActiveDirectory) GetUserDistinguishedName

func (ad ActiveDirectory) GetUserDistinguishedName(userName string) (string, error)

GetUserDistinguishedName the distinguished name for the specified user (userPrincipalName/email or sAMAccountName).

func (ActiveDirectory) GetUsersForGroup

func (ad ActiveDirectory) GetUsersForGroup(request UsersForGroupRequest) ([]string, error)

GetUsersForGroup For the specified group, retrieve all of the users that belong to the group. returns DN of the users

type ActiveDirectoryConnConfig

type ActiveDirectoryConnConfig struct {
	*ServerConfig
	//Username to be used to for login. Can be a service account username as well
	//Should always be of the form username@domainname to avoid any confusion
	AdminUsername string
	//Password for the admin or service account
	AdminPassword string
	//BaseDN is the root where the search will happen. If not known, can be found
	// using <cref="GetAttributeOnRootDSE"/>
	BaseDN string
}

ActiveDirectoryConnConfig basic configuration used for connecting to AD server

type ActiveDirectoryGroup

type ActiveDirectoryGroup struct {
	DistinguishedName string   `activedirectory:"distinguishedName"`
	SAMAccountName    string   `activedirectory:"sAMAccountName"`
	CommonName        string   `activedirectory:"cn"`
	Description       string   `activedirectory:"description"`
	SID               string   `activedirectory:"objectSid"`
	ObjectCategory    string   `activedirectory:"objectCategory"`
	Members           []string `activedirectory:"member"`
}

type ActiveDirectoryUser

type ActiveDirectoryUser struct {
	DistinguishedName string `activedirectory:"distinguishedName"`
	UserPrincipalName string `activedirectory:"userPrincipalName"`
	SAMAccountName    string `activedirectory:"sAMAccountName"`
	SID               string `activedirectory:"objectSid"`
	Mail              string `activedirectory:"mail"`
	// LockoutTime        *time.Time `activedirectory:"lockoutTime"`
	// WhenCreated        *time.Time `activedirectory:"whenCreated"`
	// PwdLastSet         *time.Time `activedirectory:"pwdLastSet"`
	UserAccountControl string `activedirectory:"userAccountControl"`
	EmployeeID         string `activedirectory:"employeeID"`
	Surname            string `activedirectory:"sn"`
	GivenName          string `activedirectory:"givenName"`
	Initials           string `activedirectory:"initials"`
	CommonName         string `activedirectory:"cn"`
	DisplayName        string `activedirectory:"displayName"`
	Comment            string `activedirectory:"comment"`
	Description        string `activedirectory:"description"`
	OU                 string `activedirectory:"ou"`
	ObjectCategory     string `activedirectory:"objectCategory"`
}

type GroupParentsRequest

type GroupParentsRequest struct {
	GroupName string
}

GroupParentsRequest represents request for getting parents of a group by DN

type ServerConfig

type ServerConfig struct {
	//Url for connecting to server
	//example may include `ldaps://xyz.lan` or `ldap://xyz.lan`
	Url string
	//Chain of certs required for TLS connection
	RootCAs *x509.CertPool
}

ServerConfig is basic configuration required for opening a socket to AD

type UserParentsRequest

type UserParentsRequest struct {
	UserName string
}

UserParentsRequest represents request for getting parents of a user by DN

type UsersForGroupRequest

type UsersForGroupRequest struct {
	GroupName string
}