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'