ldapcherry/docs/backends.rst

Backends

Backend id prefix

Each parameter of a backend instance must be prefixed by a backend id. This backend id must be unique.

For example:

[backends]

# configuration of the bk1 backend
bk1.module = 'my.backend.module'
bk1.display_name = 'My backend module'
bk1.param = 'value'

Warning

For the rest of the backends documentation, this prefix is inferred.

Common backend parameters

Every backend instance systematicaly has two parameters:

Parameter	Section	Description	Values	Comment
module	backends	Library path to the module	Python library path
display_name	backends	Display_name of the backend	Free text

Ldap Backend

Class path

The class path for the ldap backend is ldapcherry.backend.backendLdap.

Configuration

The ldap backend exposes the following parameters:

Parameter	Section	Description	Values	Comment
uri	backends	The ldap uri to access	ldap uri	use ldap:// for clear/starttls use ldaps:// for ssl custom port: ldap://<host>:<port>
ca	backends	Path to the CA file	file path	optional
starttls	backends	Use starttls	'on' or 'off'	optional
checkcert	backends	Check the server certificat	'on' or 'off'	optional
binddn	backends	The bind dn to use	ldap dn	This dn must have read/write permissions
password	backends	The password of the bind dn	password
timeout	backends	Ldap connexion timeout	integer (second)
password	backends	The password of the bind dn	password
groupdn	backends	The ldap dn where groups are	ldap dn
userdn	backends	The ldap dn where users are	ldap dn
user_filter_tmpl	backends	The search filter template to recover a given user	ldap search filter template	The user identifier is passed through the username variable (%(username)s) username is the content of the the attribute marked by 'key: True' in the attributes.yml file
group_filter_tmpl	backends	The search filter template to recover the groups of a given user recover the groups of a given user	ldap search filter template template	The following variables are usable: username: the user's key attribute userdn: the user's ldap dn
group_attr.<member attr>	backends	Member attribute template value	template	<member attr> is the member attribute in groups dn entries every user attributes are exposed in the template multiple <memver attr> attributes can be set (ex: group_attr.member (ex: group_attr.member, group_attr.usermemb)
objectclasses	backends	list of object classes for users	comma separated list
dn_user_attr	backends	attribute used in users dn	dn attribute

Example

[backends]

#####################################
#   configuration of ldap backend   #
#####################################

# name of the module
ldap.module = 'ldapcherry.backend.backendLdap'
# display name of the ldap
ldap.display_name = 'My Ldap Directory'

# uri of the ldap directory
ldap.uri = 'ldap://ldap.ldapcherry.org'
# ca to use for ssl/tls connexion
#ldap.ca = '/etc/dnscherry/TEST-cacert.pem'
# use start tls
#ldap.starttls = 'off'
# check server certificate (for tls)
#ldap.checkcert = 'off'
# bind dn to the ldap
ldap.binddn = 'cn=dnscherry,dc=example,dc=org'
# password of the bind dn
ldap.password = 'password'
# timeout of ldap connexion (in second)
ldap.timeout = 1

# groups dn
ldap.groupdn = 'ou=group,dc=example,dc=org'
# users dn
ldap.userdn = 'ou=people,dc=example,dc=org'

# ldapsearch filter to get one specific user
# %(username)s is content of the attribute marked 'key: True' in the attributes.file config file
ldap.user_filter_tmpl = '(uid=%(username)s)'
# ldapsearch filter to get groups of a user
# %(username)s is content of the attribute marked 'key: True' in the attributes.file config file
ldap.group_filter_tmpl = '(member=uid=%(username)s,ou=People,dc=example,dc=org)'
# filter to search users
# %(searchstring)s is the content passed through the search box
ldap.search_filter_tmpl = '(|(uid=%(searchstring)s*)(sn=%(searchstring)s*))'

# ldap group attributes and how to fill them
# 'member' is the name of the attribute
# for the template, any of the user's ldap attributes can be user
ldap.group_attr.member = "%(dn)s"
# same with memverUid and the uid user's attribute
#ldap.group_attr.memberUid = "%(uid)s"

# object classes of a user entry
ldap.objectclasses = 'top, person, posixAccount, inetOrgPerson'
# dn entry attribute for an ldap user
ldap.dn_user_attr = 'uid'

Active Directory Backend

Warning

This backend needs the cn and unicodePwd attributes to be declared in attributes.yml

Class path

The class path for the ldap backend is ldapcherry.backend.backendAD.

Configuration

Parameter	Section	Description	Values	Comment
uri	backends	The ldap uri to access	ldap uri	use ldap:// for clear/starttls use ldaps:// for ssl custom port: ldap://<host>:<port>
ca	backends	Path to the CA file	file path	optional
starttls	backends	Use starttls	'on' or 'off'	optional
checkcert	backends	Check the server certificat	'on' or 'off'	optional
domain	backends	Name of the domain	AD domain
login	backends	login used for connecting to AD	login	user used must have sufficient rights
password	backends	password if binding user	password

Example

[backends]

# Name of the backend
ad.module = 'ldapcherry.backend.backendAD'
# display name of the ldap
ad.display_name = 'My Active Directory'
# ad domain
ad.domain = 'dc.ldapcherry.org'
# ad login
ad.login  = 'administrator'
# ad password 
ad.password = 'qwertyP455'
# ad uri
ad.uri = 'ldap://ad.ldapcherry.org'

## ca to use for ssl/tls connexion
#ad.ca = '/etc/dnscherry/TEST-cacert.pem'
## use start tls
#ad.starttls = 'off'
## check server certificate (for tls)
#ad.checkcert = 'off'

Demo Backend

Warning

This backend is only meant for demo.

Class path

The class path for the ldap backend is ldapcherry.backend.backendDemo.

Configuration

Parameter	Section	Description	Values	Comment
admin.user	backends	Login for default admin	string	optional, default: 'admin'
admin.password	backends	Password for default admin	string	optional, default: 'admin'
admin.groups	backends	Groups for default admin	comma separated list
basic.user	backends	Login for default user	string	optional, default: 'user'
basic.password	backends	Password for default user	string	optional, default: 'user'
basic.groups	backends	Groups for default user	comma separated list
pwd_attr	backends	Password attribute name	string
search_attributes	backends	Attributes used for search	comma separated list

Example

[backends]

# path to the module
demo.module = 'ldapcherry.backend.backendDemo'
# display name of the module
demo.display_name  = 'Demo Backend'

## admin user login (optional, default: 'admin')
#demo.admin.user = 'admin'
## admin user password (optional: default 'admin')
#demo.admin.password = 'admin'
# groups for the default admin user (comma separated)
demo.admin.groups  = 'DnsAdmins'

## basic user login (optional, default: 'user')
#demo.basic.user = 'user'
## admin user password (optional: default 'user')
#demo.basic.password = 'user'
# groups for the default basic user (comma separated)
demo.basic.groups  = 'Test 2, Test 1'

# password attribute used for auth
demo.pwd_attr = 'userPassword'
# attributes to search on
demo.search_attributes = 'cn, sn, givenName, uid'