testdirectory

README

gldap.testdirectory

The testdirectory package provides an in-memory test LDAP service with support for capabilities which make writing tests that depend on an LDAP service much easier.

testdirectory is also a great working example of how you can use gldap to build a custom ldap server to meet your specific needs.

Example:

// this example demonstrates how can start a test directory for your 
// unit tests which will automatically stop when the test is complete. 
func TestDirectory_SimpleBindResponse(t *testing.T) {

	// start a test directory running ldaps on an available free port (defaults)
	// that allows anon binds (a default override)
	td := testdirectory.Start(t,
		testdirectory.WithDefaults(&testdirectory.Defaults{AllowAnonymousBind: true}),
	)
	// create some test new user entries (using defaults for ou, password, etc)
	users := testdirectory.NewUsers(t, []string{"alice", "bob"})
	// set the test directories user entries
	td.SetUsers(users...)
}

Documentation

Index

• Constants
• func FreePort(t TestingT) int
• func GetTLSConfig(t TestingT, opt ...Option) (s *tls.Config, c *tls.Config)
• func NewGroup(t TestingT, groupName string, memberNames []string, opt ...Option) *gldap.Entry
• func NewMemberOf(t TestingT, groupNames []string, opt ...Option) []string
• func NewUsers(t TestingT, userNames []string, opt ...Option) []*gldap.Entry
• type CleanupT
• type Defaults
• type Directory
  • func Start(t TestingT, opt ...Option) *Directory
  • func (d *Directory) AllowAnonymousBind() bool
  • func (d *Directory) Cert() string
  • func (d *Directory) ClientCert() string
  • func (d *Directory) ClientKey() string
  • func (d *Directory) Conn() *ldap.Conn
  • func (d *Directory) Controls() []gldap.Control
  • func (d *Directory) Groups() []*gldap.Entry
  • func (d *Directory) Host() string
  • func (d *Directory) Port() int
  • func (d *Directory) SetAllowAnonymousBind(enabled bool)
  • func (d *Directory) SetControls(controls ...gldap.Control)
  • func (d *Directory) SetGroups(groups ...*gldap.Entry)
  • func (d *Directory) SetTokenGroups(tokenGroups map[string][]*gldap.Entry)
  • func (d *Directory) SetUsers(users ...*gldap.Entry)
  • func (d *Directory) Stop()
  • func (d *Directory) TokenGroups() map[string][]*gldap.Entry
  • func (d *Directory) Users() []*gldap.Entry
• type HelperT
• type InfofT
• type Logger
  • func NewLogger(logger hclog.Logger) (*Logger, error)
  • func (l *Logger) Errorf(format string, args ...interface{})
  • func (l *Logger) FailNow()
  • func (l *Logger) Infof(format string, args ...interface{})
  • func (l *Logger) Log(i ...interface{})
• type Option
  • func WithDefaults(t TestingT, defaults *Defaults) Option
  • func WithDisablePanicRecovery(t TestingT, disable bool) Option
  • func WithHost(t TestingT, host string) Option
  • func WithLogger(t TestingT, l hclog.Logger) Option
  • func WithMTLS(t TestingT) Option
  • func WithMembersOf(t TestingT, membersOf ...string) Option
  • func WithNoTLS(t TestingT) Option
  • func WithPort(t TestingT, port int) Option
  • func WithTokenGroups(t TestingT, tokenGroupSID ...[]byte) Option
• type TestingT

Constants

const (
	// DefaultUserAttr is the "username" attribute of the entry's DN and is
	// typically either the cn in ActiveDirectory or uid in openLDAP  (default:
	// cn)
	DefaultUserAttr = "cn"

	// DefaultGroupAttr for the ClientConfig.GroupAttr
	DefaultGroupAttr = "cn"

	// DefaultUserDN defines a default base distinguished name to use when
	// searching for users for the Directory
	DefaultUserDN = "ou=people,dc=example,dc=org"

	// DefaultGroupDN defines a default base distinguished name to use when
	// searching for groups for the Directory
	DefaultGroupDN = "ou=groups,dc=example,dc=org"
)

Functions

func FreePort

func FreePort(t TestingT) int

FreePort just returns an available free localhost port

func GetTLSConfig

func GetTLSConfig(t TestingT, opt ...Option) (s *tls.Config, c *tls.Config)

supports WithMTLS

func NewGroup

func NewGroup(t TestingT, groupName string, memberNames []string, opt ...Option) *gldap.Entry

NewGroup creates a group entry. Options supported: WithDefaults

func NewMemberOf

func NewMemberOf(t TestingT, groupNames []string, opt ...Option) []string

NewMemberOf creates memberOf attributes which can be assigned to user entries. Supported Options: WithDefaults

func NewUsers

func NewUsers(t TestingT, userNames []string, opt ...Option) []*gldap.Entry

NewUsers creates user entries. Options supported: WithDefaults, WithMembersOf

Types

type CleanupT

type CleanupT interface{ Cleanup(func()) }

CleanupT defines an single function interface for a testing.Cleanup(func()).

type Defaults

type Defaults struct {
	UserAttr string

	GroupAttr string

	// Users configures the user entries which are empty by default
	Users []*gldap.Entry

	// Groups configures the group entries which are empty by default
	Groups []*gldap.Entry

	// TokenGroups configures the tokenGroup entries which are empty be default
	TokenGroups map[string][]*gldap.Entry

	// UserDN is the base distinguished name to use when searching for users
	// which is "ou=people,dc=example,dc=org" by default
	UserDN string

	// GroupDN is the base distinguished name to use when searching for groups
	// which is "ou=groups,dc=example,dc=org" by default
	GroupDN string

	// AllowAnonymousBind determines if anon binds are allowed
	AllowAnonymousBind bool

	// UPNDomain is the userPrincipalName domain, which enables a
	// userPrincipalDomain login with [username]@UPNDomain (optional)
	UPNDomain string
}

Defaults define a type for composing all the defaults for Directory.Start(...)

type Directory

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

Directory is a local ldap directory that supports test ldap capabilities which makes writing tests much easier.

It's important to remember that the Directory is stateful (see any of its receiver functions that begin with Set*)

Once you started a Directory with Start(...), the following test ldap operations are supported:

• Bind
• StartTLS
• Search
• Modify
• Add

Making requests to the Directory is facilitated by:

• Directory.Conn() returns a *ldap.Conn connected to the Directory (honors WithMTLS options from start)
• Directory.Cert() returns the pem-encoded CA certificate used by the directory.
• Directory.Port() returns the port the directory is listening on.
• Directory.ClientCert() returns a client cert for mtls
• Directory.ClientKey() returns a client private key for mtls

func Start

func Start(t TestingT, opt ...Option) *Directory

Start creates and starts a running Directory ldap server. Support options: WithPort, WithMTLS, WithNoTLS, WithDefaults, WithLogger.

The Directory will be shutdown when the test and all its subtests are compted via a registered function with t.Cleanup(...)

func (*Directory) AllowAnonymousBind

func (d *Directory) AllowAnonymousBind() bool

AllowAnonymousBind returns the allow anon bind setting

func (*Directory) Cert

func (d *Directory) Cert() string

Cert returns the pem-encoded certificate used by the Directory.

func (*Directory) ClientCert

func (d *Directory) ClientCert() string

ClientCert returns the pem-encoded certificate which can be used by a client for mTLS.

func (*Directory) ClientKey

func (d *Directory) ClientKey() string

ClientKey returns the pem-encoded private key which can be used by a client for mTLS.

func (*Directory) Conn

func (d *Directory) Conn() *ldap.Conn

Conn returns an *ldap.Conn that's connected (using whatever tls.Config is appropriate for the directory) and ready send requests to the directory.

func (*Directory) Controls

func (d *Directory) Controls() []gldap.Control

Controls returns all the current bind controls for the Directory

func (*Directory) Groups

func (d *Directory) Groups() []*gldap.Entry

Groups returns all the current group entries in the Directory

func (*Directory) Host

func (d *Directory) Host() string

Host returns the host the directory is listening on

func (*Directory) Port

func (d *Directory) Port() int

Port returns the port the directory is listening on

func (*Directory) SetAllowAnonymousBind

func (d *Directory) SetAllowAnonymousBind(enabled bool)

SetAllowAnonymousBind enables/disables anon binds

func (*Directory) SetControls

func (d *Directory) SetControls(controls ...gldap.Control)

SetControls sets the bind controls.

func (*Directory) SetGroups

func (d *Directory) SetGroups(groups ...*gldap.Entry)

SetGroups sets the group entries.

func (*Directory) SetTokenGroups

func (d *Directory) SetTokenGroups(tokenGroups map[string][]*gldap.Entry)

SetTokenGroups will set the tokenGroup entries.

func (*Directory) SetUsers

func (d *Directory) SetUsers(users ...*gldap.Entry)

SetUsers sets the user entries.

func (*Directory) Stop

func (d *Directory) Stop()

Stop will stop the Directory if it wasn't started with a *testing.T if it was started with *testing.T then Stop() is ignored.

func (*Directory) TokenGroups

func (d *Directory) TokenGroups() map[string][]*gldap.Entry

TokenGroups will return the tokenGroup entries

func (*Directory) Users

func (d *Directory) Users() []*gldap.Entry

Users returns all the current user entries in the Directory

type HelperT

type HelperT interface{ Helper() }

HelperT defines a single function interface for a testing.Helper()

type InfofT

type InfofT interface {
	Infof(format string, args ...interface{})
}

InfofT defines a single function interface for a Info(format string, args ...interface{})

type Logger

type Logger struct {
	Logger hclog.Logger
}

Logger defines a logger that will implement the TestingT interface so it can be used with Directory.Start(...) as its t TestingT parameter.

func NewLogger

func NewLogger(logger hclog.Logger) (*Logger, error)

NewLogger makes a new TestingLogger

func (*Logger) Errorf

func (l *Logger) Errorf(format string, args ...interface{})

Errorf will output the error to the log

func (*Logger) FailNow

func (l *Logger) FailNow()

FailNow will panic

func (*Logger) Infof

func (l *Logger) Infof(format string, args ...interface{})

Infof will output the info to the log

func (*Logger) Log

func (l *Logger) Log(i ...interface{})

type Option

type Option func(interface{})

Option defines a common functional options type which can be used in a variadic parameter pattern.

func WithDefaults

func WithDefaults(t TestingT, defaults *Defaults) Option

WithDefaults provides an option to provide a set of defaults to Directory.Start(...) which make it much more composable.

func WithDisablePanicRecovery

func WithDisablePanicRecovery(t TestingT, disable bool) Option

func WithHost

func WithHost(t TestingT, host string) Option

WithHost provides an optional hostname for the directory

func WithLogger

func WithLogger(t TestingT, l hclog.Logger) Option

WithLogger provides the optional logger for the directory.

func WithMTLS

func WithMTLS(t TestingT) Option

WithMTLS provides the option to use mTLS for the directory.

func WithMembersOf

func WithMembersOf(t TestingT, membersOf ...string) Option

WithMembersOf specifies optional memberOf attributes for user entries

func WithNoTLS

func WithNoTLS(t TestingT) Option

WithNoTLS provides the option to not use TLS for the directory.

func WithPort

func WithPort(t TestingT, port int) Option

WithPort provides an optional port for the directory. 0 causes a started server with a random port. Any other value returns a started server on that port.

func WithTokenGroups

func WithTokenGroups(t TestingT, tokenGroupSID ...[]byte) Option

WithTokenGroups specifies optional test tokenGroups SID attributes for user entries

type TestingT

type TestingT interface {
	Errorf(format string, args ...interface{})
	FailNow()
	Log(...interface{})
}

TestingT defines a very slim interface required by a Directory and any test functions it uses.