Why Go
- Case Studies
  
  Common problems companies solve with Go
- Use Cases
  
  Stories about how and why companies use Go
- Security
  
  How Go can help keep you secure by default
Learn
Docs
- Effective Go
  
  Tips for writing clear, performant, and idiomatic Go code
- Go User Manual
  
  A complete introduction to building software with Go
- Standard library
  
  Reference documentation for Go's standard library
- Release Notes
  
  Learn what's new in each Go release
- API
  
  Reference documentation for the pkg.go.dev API
Packages
Community
- Recorded Talks
  
  Videos from prior events
- Meetups
  
  Meet other local Go developers
- Conferences
  
  Learn and network with Go developers from around the world
- Go blog
  
  The Go project's official blog.
- Go project
  
  Get help and stay informed from Go
- Get connected

ldapauth

package module

Go to main page

Versions in this module

v1

v1.2.1

Aug 27, 2026

v1.2.0

Aug 27, 2026

Changes in this version

+ var ErrCacheTampered = errors.New("ldapauth: a cached value failed its integrity check")

+ type ByteStore interface

+ Get func(ctx context.Context, key string) (value []byte, hit bool, err error)

+ InvalidateAll func(ctx context.Context) (int, error)

+ InvalidateUser func(ctx context.Context, username string) (int, error)

+ Len func(ctx context.Context) (int, error)

+ Set func(ctx context.Context, key, username string, value []byte, ttl time.Duration) error

type Cache

+ func NewSealedCache(store ByteStore, secret []byte) (Cache, error)

type Option

+ func WithSealedCacheStore(store ByteStore) Option

v1.1.0

Aug 27, 2026

Changes in this version

+ const DefaultLockoutCooldown

+ const DefaultLockoutMaxAccounts

+ const DefaultLockoutWindow

+ const ResultThrottled

+ var ErrReferral = errors.New("ldapauth: the directory referred the search elsewhere")

+ var ErrTooManyAttempts = errors.New("ldapauth: too many recent failures for this account")

type AuthError

+ Reason RejectionReason

+ Referrals []string

+ type ControlBinder interface

+ SimpleBind func(request *ldap.SimpleBindRequest) (*ldap.SimpleBindResult, error)

type Option

+ func WithCacheUsernameHashing() Option

+ func WithLockoutProtection(attempts int, window, cooldown time.Duration) Option

+ func WithPasswordPolicyControl() Option

+ func WithReferralPolicy(policy ReferralPolicy) Option

+ type ReferralPolicy int

+ const ReferralFail

+ const ReferralIgnore

+ func (p ReferralPolicy) String() string

+ type RejectionReason uint8

+ const ReasonAccountDisabled

+ const ReasonAccountExpired

+ const ReasonAccountLocked

+ const ReasonBadPassword

+ const ReasonNoSuchUser

+ const ReasonPasswordExpired

+ const ReasonPasswordMustChange

+ const ReasonTimeRestricted

+ const ReasonUnspecified

+ const ReasonWorkstationRestricted

+ func ReasonFor(err error) RejectionReason

+ func (r RejectionReason) Actionable() bool

+ func (r RejectionReason) String() string

+ type Reloadable struct

+ func NewReloadable(client *Client) *Reloadable

+ func (r *Reloadable) Authenticate(ctx context.Context, username, password string) (Identity, error)

+ func (r *Reloadable) Close() error

+ func (r *Reloadable) Current() *Client

+ func (r *Reloadable) HealthCheck(ctx context.Context) error

+ func (r *Reloadable) InvalidateAll(ctx context.Context) (int, error)

+ func (r *Reloadable) InvalidateUser(ctx context.Context, username string) (int, error)

+ func (r *Reloadable) Lookup(ctx context.Context, username string) (Identity, error)

+ func (r *Reloadable) Replace(next *Client) (previous *Client)

+ func (r *Reloadable) Stats(ctx context.Context) Stats

type Stats

+ BlockedAccounts int

v1.0.0

Aug 27, 2026

Changes in this version

+ const CacheCoalesced

+ const CacheError

+ const CacheHit

+ const CacheMiss

+ const CacheNegativeHit

+ const DefaultCacheMaxEntries

+ const DefaultCacheTTL

+ const DefaultDialTimeout

+ const DefaultFailoverCooldown

+ const DefaultGroupNameAttribute

+ const DefaultMemberOfAttribute

+ const DefaultNegativeCacheTTL

+ const DefaultNestedGroupDepth

+ const DefaultOperationTimeout

+ const DefaultPasswordMaxLength

+ const DefaultPoolMaxIdleTime

+ const DefaultPoolMaxLifetime

+ const DefaultPoolSize

+ const DefaultRequestTimeout

+ const DefaultRetryBaseDelay

+ const DefaultRetryMaxAttempts

+ const DefaultRetryMaxDelay

+ const DefaultRetryMaxElapsed

+ const DefaultRetryMultiplier

+ const DefaultUsernameMaxLength

+ const MaxCacheTTL

+ const ResultError

+ const ResultInvalidCredentials

+ const ResultRejected

+ const ResultSuccess

+ const ScopeBaseObject

+ const ScopeSingleLevel

+ const ScopeWholeSubtree

+ var ErrAmbiguousUser = errors.New("ldapauth: user search matched more than one entry")

+ var ErrClosed = errors.New("ldapauth: authenticator closed")

+ var ErrEmptyPassword = errors.New("ldapauth: empty password")

+ var ErrEmptyUsername = errors.New("ldapauth: empty username")

+ var ErrInvalidCredentials = errors.New("ldapauth: invalid credentials")

+ var ErrInvalidOption = errors.New("ldapauth: invalid option")

+ var ErrInvalidPassword = errors.New("ldapauth: invalid password")

+ var ErrInvalidUsername = errors.New("ldapauth: invalid username")

+ var ErrNoServerAvailable = errors.New("ldapauth: no LDAP server available")

+ var ErrNoSuchGroupAttribute = errors.New("ldapauth: group membership attribute not present")

+ var ErrPoolExhausted = errors.New("ldapauth: connection pool exhausted")

+ var ErrTLSRequired = errors.New("ldapauth: TLS required")

+ var ErrUserNotFound = errors.New("ldapauth: user not found")

+ type AuthError struct

+ Err error

+ Op string

+ ResultCode uint16

+ URL string

+ Username string

+ func (e *AuthError) Error() string

+ func (e *AuthError) Unwrap() error

+ type Authenticator interface

+ Authenticate func(ctx context.Context, username, password string) (Identity, error)

+ Close func() error

+ HealthCheck func(ctx context.Context) error

+ InvalidateAll func(ctx context.Context) (int, error)

+ InvalidateUser func(ctx context.Context, username string) (int, error)

+ Lookup func(ctx context.Context, username string) (Identity, error)

+ Stats func(ctx context.Context) Stats

+ type Cache interface

+ Get func(ctx context.Context, key string) (identity Identity, hit bool, err error)

+ InvalidateAll func(ctx context.Context) (int, error)

+ InvalidateUser func(ctx context.Context, username string) (int, error)

+ Len func(ctx context.Context) (int, error)

+ Set func(ctx context.Context, key, username string, identity Identity, ...) error

+ func NewMemoryCache(maxEntries int, now func() time.Time) Cache

+ type Client struct

+ func New(opts ...Option) (*Client, error)

+ func (a *Client) Authenticate(ctx context.Context, username, password string) (Identity, error)

+ func (a *Client) Close() error

+ func (a *Client) HealthCheck(ctx context.Context) error

+ func (a *Client) InvalidateAll(ctx context.Context) (int, error)

+ func (a *Client) InvalidateUser(ctx context.Context, username string) (int, error)

+ func (a *Client) Lookup(ctx context.Context, username string) (Identity, error)

+ func (a *Client) Stats(ctx context.Context) Stats

+ type Conn interface

+ Bind func(username, password string) error

+ Close func() error

+ IsClosing func() bool

+ Search func(request *ldap.SearchRequest) (*ldap.SearchResult, error)

+ SearchWithPaging func(request *ldap.SearchRequest, pagingSize uint32) (*ldap.SearchResult, error)

+ SetTimeout func(timeout time.Duration)

+ WhoAmI func(controls []ldap.Control) (*ldap.WhoAmIResult, error)

+ type Dialer interface

+ DialContext func(ctx context.Context, url string) (Conn, error)

+ type FailoverPolicy int

+ const FailoverInOrder

+ const FailoverRandom

+ const FailoverRoundRobin

+ func (p FailoverPolicy) String() string

+ type GroupRequest struct

+ DN string

+ Entry *ldap.Entry

+ Search Searcher

+ Username string

+ type GroupResolver interface

+ ResolveGroups func(ctx context.Context, request GroupRequest) ([]string, error)

+ type GroupResolverFunc func(ctx context.Context, request GroupRequest) ([]string, error)

+ func (f GroupResolverFunc) ResolveGroups(ctx context.Context, request GroupRequest) ([]string, error)

+ type GroupSource int

+ const GroupsDisabled

+ const GroupsFromMemberOf

+ const GroupsFromSearch

+ func (g GroupSource) String() string

+ type Identity interface

+ Clone func() Identity

+ GetAttribute func(name string) string

+ GetAttributeValues func(name string) []string

+ GetDN func() string

+ GetDisplayName func() string

+ GetEmail func() string

+ GetGroups func() []string

+ GetUsername func() string

+ InAllGroups func(names ...string) bool

+ InAnyGroup func(names ...string) bool

+ InGroup func(name string) bool

+ type Mapping struct

+ DN string

+ Entry *ldap.Entry

+ Groups []string

+ Username string

+ type Metrics interface

+ AuthAttempt func(result string, d time.Duration)

+ CacheEvent func(event string)

+ ConnClosed func(reason string)

+ ConnOpened func(url string)

+ PoolStats func(inUse, idle int)

+ RetryScheduled func(op string, attempt int, delay time.Duration)

+ type NoGroups struct

+ func (NoGroups) ResolveGroups(context.Context, GroupRequest) ([]string, error)

+ type NoopMetrics struct

+ func (NoopMetrics) AuthAttempt(string, time.Duration)

+ func (NoopMetrics) CacheEvent(string)

+ func (NoopMetrics) ConnClosed(string)

+ func (NoopMetrics) ConnOpened(string)

+ func (NoopMetrics) PoolStats(int, int)

+ func (NoopMetrics) RetryScheduled(string, int, time.Duration)

+ type Option func(*config) error

+ func WithActiveDirectoryGroups(baseDN string) Option

+ func WithAnonymousServiceBind() Option

+ func WithAttributes(names ...string) Option

+ func WithCache(ttl time.Duration) Option

+ func WithCacheSecret(secret []byte) Option

+ func WithCacheSize(entries int) Option

+ func WithCacheStore(store Cache) Option

+ func WithCaseFoldUsername() Option

+ func WithClientCertificate(cert tls.Certificate) Option

+ func WithClientCertificateFiles(certFile, keyFile string) Option

+ func WithClock(now func() time.Time) Option

+ func WithDerefAliases(deref int) Option

+ func WithDialTimeout(d time.Duration) Option

+ func WithDialer(d Dialer) Option

+ func WithDirectBind(dnTemplate string) Option

+ func WithDisplayNameAttribute(name string) Option

+ func WithEmailAttribute(name string) Option

+ func WithFailoverCooldown(d time.Duration) Option

+ func WithFailoverPolicy(p FailoverPolicy) Option

+ func WithGroupDNs() Option

+ func WithGroupNameAttribute(name string) Option

+ func WithGroupResolver(resolver GroupResolver) Option

+ func WithGroupSearch(baseDN, filterTemplate string) Option

+ func WithGroupSearchScope(scope int) Option

+ func WithInsecureNoTLS() Option

+ func WithInsecureSkipVerify() Option

+ func WithLogger(logger *slog.Logger) Option

+ func WithMemberOfAttribute(name string) Option

+ func WithMemberOfGroups() Option

+ func WithMetrics(m Metrics) Option

+ func WithMinTLSVersion(version uint16) Option

+ func WithNegativeCache(ttl time.Duration) Option

+ func WithNestedGroupDepth(depth int) Option

+ func WithNestedGroups() Option

+ func WithOperationTimeout(d time.Duration) Option

+ func WithPagingSize(size uint32) Option

+ func WithPasswordMaxLength(n int) Option

+ func WithPoolHealthCheck(enabled bool) Option

+ func WithPoolMaxIdleTime(d time.Duration) Option

+ func WithPoolMaxLifetime(d time.Duration) Option

+ func WithPoolMinIdle(n int) Option

+ func WithPoolSize(n int) Option

+ func WithPrincipalMapper(mapper PrincipalMapper) Option

+ func WithRequestTimeout(d time.Duration) Option

+ func WithRetry(attempts int) Option

+ func WithRetryBackoff(base, max time.Duration, multiplier float64) Option

+ func WithRetryMaxElapsed(d time.Duration) Option

+ func WithRootCAFile(path string) Option

+ func WithRootCAs(pool *x509.CertPool) Option

+ func WithSearchSizeLimit(limit int) Option

+ func WithServerName(name string) Option

+ func WithServiceAccount(dn, password string) Option

+ func WithStartTLS() Option

+ func WithTLSConfig(t *tls.Config) Option

+ func WithURL(url string) Option

+ func WithURLs(urls ...string) Option

+ func WithUserSearch(baseDN, filterTemplate string) Option

+ func WithUserSearchScope(scope int) Option

+ func WithUsernameAttribute(name string) Option

+ func WithUsernameMaxLength(n int) Option

+ func WithUsernameRedaction() Option

+ func WithoutRetry() Option

+ type Principal struct

+ Attributes map[string][]string

+ DN string

+ DisplayName string

+ Email string

+ Extra any

+ Groups []string

+ Username string

+ func AsPrincipal(identity Identity) (*Principal, bool)

+ func (p *Principal) Clone() Identity

+ func (p *Principal) GetAttribute(name string) string

+ func (p *Principal) GetAttributeValues(name string) []string

+ func (p *Principal) GetDN() string

+ func (p *Principal) GetDisplayName() string

+ func (p *Principal) GetEmail() string

+ func (p *Principal) GetGroups() []string

+ func (p *Principal) GetUsername() string

+ func (p *Principal) InAllGroups(names ...string) bool

+ func (p *Principal) InAnyGroup(names ...string) bool

+ func (p *Principal) InGroup(name string) bool

+ type PrincipalMapper interface

+ MapPrincipal func(mapping Mapping) (Identity, error)

+ type PrincipalMapperFunc func(mapping Mapping) (Identity, error)

+ func (f PrincipalMapperFunc) MapPrincipal(mapping Mapping) (Identity, error)

+ type Searcher interface

+ Search func(ctx context.Context, request *ldap.SearchRequest) (*ldap.SearchResult, error)

+ type SearcherFunc func(ctx context.Context, request *ldap.SearchRequest) (*ldap.SearchResult, error)

+ func (f SearcherFunc) Search(ctx context.Context, request *ldap.SearchRequest) (*ldap.SearchResult, error)

+ type Stats struct

+ CacheEntries int

+ HealthyServers int

+ PoolIdle int

+ PoolInUse int

+ PoolSize int

+ Servers int