ldap

README

Gitea 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 '%[1]s' matching parameter will be substituted with the user's username.
  • Example: (&(objectClass=posixAccount)(|(uid=%[1]s)(mail=%[1]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 Search Base (optional)

  • 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 when a user should be allowed to log in. The %[1]s matching parameter will be substituted with the user's username.
  • Example: (&(objectClass=posixAccount)(|(cn=%[1]s)(mail=%[1]s)))
  • Example: (&(objectClass=posixAccount)(|(uid=%[1]s)(mail=%[1]s)))

Verify group membership in LDAP uses the following fields:

• Group Search Base (optional)

  • The LDAP DN used for groups.
  • Example: ou=group,dc=mydomain,dc=com

• Group Name Filter (optional)

  • An LDAP filter declaring how to find valid groups in the above DN.
  • Example: (|(cn=gitea_users)(cn=admins))

• User Attribute in Group (optional)

  • The user attribute that is used to reference a user in the group object.
  • Example: uid if the group objects contains a member: bender and the user object contains a uid: bender.
  • Example: dn if the group object contains a member: uid=bender,ou=users,dc=planetexpress,dc=com.

• Group Attribute for User (optional)

  • The attribute of the group object that lists/contains the group members.
  • Example: memberUid or member

• Team group map (optional)

  • Automatically add users to Organization teams, depending on LDAP group memberships.
  • Note: this function only adds users to teams, it never removes users.
  • Example: {"cn=MyGroup,cn=groups,dc=example,dc=org": {"MyGiteaOrganization": ["MyGiteaTeam1", "MyGiteaTeam2", ...], ...}, ...}

• Team group map removal (optional)

  • If set to true, users will be removed from teams if they are not members of the corresponding group.

Documentation

Index

• Variables
• type SearchResult
• type SecurityProtocol
  • func (s SecurityProtocol) Int() int
  • func (s SecurityProtocol) String() string
• type Source
  • func (source *Source) Authenticate(ctx context.Context, user *user_model.User, userName, password string) (*user_model.User, error)
  • func (source *Source) FromDB(bs []byte) error
  • func (source *Source) HasTLS() bool
  • func (source *Source) IsSkipLocalTwoFA() bool
  • func (source *Source) IsSkipVerify() bool
  • func (source *Source) ProvidesSSHKeys() bool
  • func (source *Source) SearchEntries() ([]*SearchResult, error)
  • func (source *Source) SearchEntry(name, passwd string, directBind bool) *SearchResult
  • func (source *Source) SecurityProtocolName() string
  • func (source *Source) SetAuthSource(authSource *auth.Source)
  • func (source *Source) Sync(ctx context.Context, updateExisting bool) error
  • func (source *Source) ToDB() ([]byte, error)
  • func (source *Source) UsePagedSearch() bool
  • func (source *Source) UseTLS() bool

Variables

var MockedSearchEntry func(source *Source, name, passwd string, directBind bool) *SearchResult

var SecurityProtocolNames = map[SecurityProtocol]string{
	SecurityProtocolUnencrypted: "Unencrypted",
	SecurityProtocolLDAPS:       "LDAPS",
	SecurityProtocolStartTLS:    "StartTLS",
}

SecurityProtocolNames contains the name of SecurityProtocol values.

Types

type SearchResult

type SearchResult struct {
	Username     string   // Username
	Name         string   // Name
	Surname      string   // Surname
	Mail         string   // E-mail address
	SSHPublicKey []string // SSH Public Key
	IsAdmin      bool     // if user is administrator
	IsRestricted bool     // if user is restricted
	LowerName    string   // LowerName
	Avatar       []byte
	Groups       container.Set[string]
}

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.

func (SecurityProtocol) Int

func (s SecurityProtocol) Int() int

Int returns the int value of the SecurityProtocol

func (SecurityProtocol) String

func (s SecurityProtocol) String() string

String returns the name of the SecurityProtocol

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
	BindPasswordEncrypt   string // Encrypted Bind BN password
	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)
	AttributeSSHPublicKey string // LDAP SSH Public Key attribute
	AttributeAvatar       string
	SearchPageSize        uint32 // Search with paging page size
	Filter                string // Query filter to validate entry
	AdminFilter           string // Query filter to check if user is admin
	RestrictedFilter      string // Query filter to check if user is restricted
	Enabled               bool   // if this source is disabled
	AllowDeactivateAll    bool   // Allow an empty search response to deactivate all users from this source
	GroupsEnabled         bool   // if the group checking is enabled
	GroupDN               string // Group Search Base
	GroupFilter           string // Group Name Filter
	GroupMemberUID        string // Group Attribute containing array of UserUID
	GroupTeamMap          string // Map LDAP groups to teams
	GroupTeamMapRemoval   bool   // Remove user from teams which are synchronized and user is not a member of the corresponding LDAP group
	UserUID               string // User Attribute listed in Group
	SkipLocalTwoFA        bool   `json:",omitempty"` // Skip Local 2fa for users authenticated with this source
	// contains filtered or unexported fields
}

Source Basic LDAP authentication service

func (*Source) Authenticate

func (source *Source) Authenticate(ctx context.Context, user *user_model.User, userName, password string) (*user_model.User, error)

Authenticate queries if login/password is valid against the LDAP directory pool, and create a local user if success when enabled.

func (*Source) FromDB

func (source *Source) FromDB(bs []byte) error

FromDB fills up a LDAPConfig from serialized format.

func (*Source) HasTLS

func (source *Source) HasTLS() bool

HasTLS returns if HasTLS

func (*Source) IsSkipLocalTwoFA

func (source *Source) IsSkipLocalTwoFA() bool

IsSkipLocalTwoFA returns if this source should skip local 2fa for password authentication

func (*Source) IsSkipVerify

func (source *Source) IsSkipVerify() bool

IsSkipVerify returns if SkipVerify is set

func (*Source) ProvidesSSHKeys

func (source *Source) ProvidesSSHKeys() bool

ProvidesSSHKeys returns if this source provides SSH Keys

func (*Source) SearchEntries

func (source *Source) SearchEntries() ([]*SearchResult, error)

SearchEntries : search an LDAP source for all users matching userFilter

func (*Source) SearchEntry

func (source *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

func (*Source) SecurityProtocolName

func (source *Source) SecurityProtocolName() string

SecurityProtocolName returns the name of configured security protocol.

func (*Source) SetAuthSource

func (source *Source) SetAuthSource(authSource *auth.Source)

SetAuthSource sets the related AuthSource

func (*Source) Sync

func (source *Source) Sync(ctx context.Context, updateExisting bool) error

Sync causes this ldap source to synchronize its users with the db

func (*Source) ToDB

func (source *Source) ToDB() ([]byte, error)

ToDB exports a LDAPConfig to a serialized format.

func (*Source) UsePagedSearch

func (source *Source) UsePagedSearch() bool

UsePagedSearch returns if need to use paged search

func (*Source) UseTLS

func (source *Source) UseTLS() bool

UseTLS returns if UseTLS