ldap

README

Gogs LDAP Authentication Module

About

This authentication module attempts to authorize and authenticate a user against an LDAP server. It provides two methods of authentication: LDAP via BindDN, and LDAP simple authentication.

LDAP via BindDN functions like most LDAP authentication systems. First, it queries the LDAP server using a Bind DN and searches for the user that is attempting to sign in. If the user is found, the module attempts to bind to the server using the user's supplied credentials. If this succeeds, the user has been authenticated, and his account information is retrieved and passed to the Gogs login infrastructure.

LDAP simple authentication does not utilize a Bind DN. Instead, it binds directly with the LDAP server using the user's supplied credentials. If the bind succeeds and no filter rules out the user, the user is authenticated.

LDAP via BindDN is recommended for most users. By using a Bind DN, the server can perform authorization by restricting which entries the Bind DN account can read. Further, using a Bind DN with reduced permissions can reduce security risk in the face of application bugs.

Usage

To use this module, add an LDAP authentication source via the Authentications section in the admin panel. Both the LDAP via BindDN and the simple auth LDAP share the following fields:

• Authorization Name (required)

  • A name to assign to the new method of authorization.

• Host (required)

  • The address where the LDAP server can be reached.
  • Example: mydomain.com

• Port (required)

  • The port to use when connecting to the server.
  • Example: 636

• Enable TLS Encryption (optional)

  • Whether to use TLS when connecting to the LDAP server.

• Admin Filter (optional)

  • An LDAP filter specifying if a user should be given administrator privileges. If a user accounts passes the filter, the user will be privileged as an administrator.
  • Example: (objectClass=adminAccount)

• First name attribute (optional)

  • The attribute of the user's LDAP record containing the user's first name. This will be used to populate their account information.
  • Example: givenName

• Surname attribute (optional)

  • The attribute of the user's LDAP record containing the user's surname This will be used to populate their account information.
  • Example: sn

• E-mail attribute (required)

  • The attribute of the user's LDAP record containing the user's email address. This will be used to populate their account information.
  • Example: mail

LDAP via BindDN adds the following fields:

• Bind DN (optional)

  • The DN to bind to the LDAP server with when searching for the user. This may be left blank to perform an anonymous search.
  • Example: cn=Search,dc=mydomain,dc=com

• Bind Password (optional)

  • The password for the Bind DN specified above, if any. Note: The password is stored in plaintext at the server. As such, ensure that your Bind DN has as few privileges as possible.

• User Search Base (required)

  • The LDAP base at which user accounts will be searched for.
  • Example: ou=Users,dc=mydomain,dc=com

• User Filter (required)

  • An LDAP filter declaring how to find the user record that is attempting to authenticate. The '%s' matching parameter will be substituted with the user's username.
  • Example: (&(objectClass=posixAccount)(uid=%s))

LDAP using simple auth adds the following fields:

• User DN (required)

  • A template to use as the user's DN. The %s matching parameter will be substituted with the user's username.
  • Example: cn=%s,ou=Users,dc=mydomain,dc=com
  • Example: uid=%s,ou=Users,dc=mydomain,dc=com

• User Filter (required)

  • An LDAP filter declaring when a user should be allowed to log in. The %s matching parameter will be substituted with the user's username.
  • Example: (&(objectClass=posixAccount)(cn=%s))
  • Example: (&(objectClass=posixAccount)(uid=%s))

Documentation

Overview

Package ldap provide functions & structure to query a LDAP ldap directory For now, it's mainly tested again an MS Active Directory service, see README.md for more information

Index

• type SearchResult
• type SecurityProtocol
• type Source
  • func (ls *Source) SearchEntries() []*SearchResult
  • func (ls *Source) SearchEntry(name, passwd string, directBind bool) *SearchResult

Types

type SearchResult

type SearchResult struct {
	Username string // Username
	Name     string // Name
	Surname  string // Surname
	Mail     string // E-mail address
	IsAdmin  bool   // if user is administrator
}

SearchResult : user data

type SecurityProtocol

type SecurityProtocol int

SecurityProtocol protocol type

const (
	SecurityProtocolUnencrypted SecurityProtocol = iota
	SecurityProtocolLDAPS
	SecurityProtocolStartTLS
)

Note: new type must be added at the end of list to maintain compatibility.

type Source

type Source struct {
	Name              string // canonical name (ie. corporate.ad)
	Host              string // LDAP host
	Port              int    // port number
	SecurityProtocol  SecurityProtocol
	SkipVerify        bool
	BindDN            string // DN to bind with
	BindPassword      string // Bind DN password
	UserBase          string // Base search path for users
	UserDN            string // Template for the DN of the user for simple auth
	AttributeUsername string // Username attribute
	AttributeName     string // First name attribute
	AttributeSurname  string // Surname attribute
	AttributeMail     string // E-mail attribute
	AttributesInBind  bool   // fetch attributes in bind context (not user)
	Filter            string // Query filter to validate entry
	AdminFilter       string // Query filter to check if user is admin
	Enabled           bool   // if this source is disabled
}

Source Basic LDAP authentication service

func (*Source) SearchEntries

func (ls *Source) SearchEntries() []*SearchResult

SearchEntries : search an LDAP source for all users matching userFilter

func (*Source) SearchEntry

func (ls *Source) SearchEntry(name, passwd string, directBind bool) *SearchResult

SearchEntry : search an LDAP source if an entry (name, passwd) is valid and in the specific filter