diff --git a/docs/backends.rst b/docs/backends.rst new file mode 100644 index 0000000..c5e9e2b --- /dev/null +++ b/docs/backends.rst @@ -0,0 +1,194 @@ +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: + +.. sourcecode:: ini + + [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 infered. + +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://: | ++--------------------------+----------+------------------------------------+--------------------------+--------------------------------------------+ +| 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 | ldap search filter | The user identifier is passed through | +| | | to recover a given user | template | the **username** variable (*%(username)s*).| ++--------------------------+----------+------------------------------------+--------------------------+--------------------------------------------+ +| group_filter_tmpl | backends | The search filter template to | ldap search filter | The following variables are usable: | +| | | recover the groups of a given user | template | * **username**: the user key attribute | +| | | | | * **userdn**: the user ldap dn | ++--------------------------+----------+------------------------------------+--------------------------+--------------------------------------------+ +| group_attr. | backends | Member attribute template value | template | * is the member attribute | +| | | | | in groups dn entries | +| | | | | * every user attributes are exposed | +| | | | | in the template | +| | | | | * multiple attributes can be set | ++--------------------------+----------+------------------------------------+--------------------------+--------------------------------------------+ +| objectclasses | backends | list of object classes for users | comma separated list | | ++--------------------------+----------+------------------------------------+--------------------------+--------------------------------------------+ +| dn_user_attr | backends | attribute used in users dn | dn attribute | | ++--------------------------+----------+------------------------------------+--------------------------+--------------------------------------------+ + + +Example +^^^^^^^ + +.. sourcecode:: ini + + [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 a user + ldap.user_filter_tmpl = '(uid=%(username)s)' + # ldapsearch filter to get groups of a user + ldap.group_filter_tmpl = '(member=uid=%(username)s,ou=People,dc=example,dc=org)' + # filter to search users + ldap.search_filter_tmpl = '(|(uid=%(searchstring)s*)(sn=%(searchstring)s*))' + + # ldap group attributes and how to fill them + ldap.group_attr.member = "%(dn)s" + #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 +------------------------ + +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://**:** | ++--------------------------+----------+------------------------------------+--------------------------+--------------------------------------------+ +| 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 | ++--------------------------+----------+------------------------------------+--------------------------+--------------------------------------------+ + + +Example +^^^^^^^ + +.. sourcecode:: ini + + # 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' diff --git a/docs/index.rst b/docs/index.rst index 993e2d1..a276d8e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -7,6 +7,7 @@ install deploy + backends full_configuration backend_api ppolicy_api