## Please edit system and help pages ONLY in the moinmaster wiki! For more
## information, please see MoinMaster:MoinPagesEditorGroup.
##master-page:none
##master-date:none
#acl MoinPagesEditorGroup:read,write,delete,revert All:read,write
#format wiki
#language en
= LDAP based user authentication =
== How it works ==
The LDAP auth module of MoinMoin enables single-sign-on (SSO) - assuming you already have a LDAP directory with your users, passwords, email adresses. On Linux this could be some OpenLDAP server, on a Windows server (usually the domain controller) this is called "Active Directory" (short: AD).

It works like this:
 * User enters his name and password via moin's login action and clicks on the login button.
 * On login, ldap_login auth module checks username/password against LDAP.
  * If username/password is ok for LDAP, it creates or updates a user profile with values from ldap (name, alias, email) and creates a user object in the !MoinMoin process, then it hands over to the next auth module...
  * If username/password is not ok for LDAP, it vetoes the login and aborts the chain of login modules.
 * Usually, you want to use moin_session as the final auth module to establish the session with the user. It uses a cookie to keep the session and create the user object on all subsequent non-login requests.

== Installing ==
You need to install python-ldap module (and everything it depends on, see its documentation).

You need an LDAP or AD server. :)

== Configuring LDAP authentication ==
Put this into your wiki config (indented in the same way as the other settings there):
{{{
    from MoinMoin.auth.ldap_login import ldap_login
    from MoinMoin.auth import moin_session
    auth = [ldap_login, moin_session]

    import ldap
    ldap_uri = 'ldap://ad.example.org' # ldap / active directory server URI

    # We can either use some fixed user and password for binding to LDAP.
    # Be careful if you need a % char in those strings - as they are used as
    # a format string, you have to write %% to get a single % in the end.
    #ldap_binddn = 'binduser@example.org'
    #ldap_bindpw = 'secret'

    # Also, if your OpenLDAP is for samba 3 or another model of domain controller 
    # auth backend, you need add as binddn and bindpw your rootdn chain (Manager
    # or any other) and respective password.
    #ldap_binddn = 'cn=Manager,dc=example,dc=org'
    #ldap_bindpw = 'secret'

    # or we can use the username and password we got from the user:
    ldap_binddn = '%(username)s@example.org' # DN we use for first bind (AD)
    #ldap_binddn = 'cn=admin,dc=example,dc=org' # DN we use for first bind (OpenLDAP)
    ldap_bindpw = '%(password)s' # password we use for first bind

    ldap_base = 'ou=SOMEUNIT,dc=example,dc=org' # base DN we use for searching
    ldap_scope = ldap.SCOPE_SUBTREE # scope of the search we do
    ldap_filter = '(sAMAccountName=%(username)s)' # ldap filter used for searching
    # for openLDAP in domain controller, the ldap_filter need a change:
    #ldap_filter = '(uid=%(username)s)' # ldap filter used for ldap in samba domain controller
    # you can also do more complex filtering like:
    # "(&(cn=%(username)s)(memberOf=CN=WikiUsers,OU=Groups,DC=example,DC=org))"

    ldap_givenname_attribute = 'givenName' # ldap attribute we get the first name from
    ldap_surname_attribute = 'sn' # ldap attribute we get the family name from
    ldap_aliasname_attribute = 'displayName' # ldap attribute we get the aliasname from
    ldap_email_attribute = 'mail' # ldap attribute we get the email address from
    ldap_email_callback = None # the function that is called with a dict as the first argument that provides LDAP data. the function has to return the e-mail address that was generated from the dict input

    ldap_coding = 'utf-8' # coding used for ldap queries and result values
    ldap_timeout = 10 # how long we wait for the ldap server [s]
    ldap_verbose = True # if True, put lots of LDAP debug info into the log

    cookie_lifetime = 1 # 1 hour after last access ldap login is required again
    user_autocreate = True

    # we don't allow the user to change those values on UserPreferences page
    user_form_disable = ['name', 'aliasname', 'email', ]
    # we remove those fields as they are not used for ldap based logins
    user_form_remove = ['password', 'password2', ]
}}}
 
== Problems? ==
!MoinMoin support does not know your LDAP server setup, so please follow these steps before asking for help:
 * Use ldap_verbose and look into your log file<<FootNote(this file is into your wiki data dir)>>.
 * Verify your settings and your user/password by e.g. using ldapsearch to query your LDAP server.
  * /!\ As long as you don't manage talking to your LDAP server with such a tool, you don't need to try with !MoinMoin.
 * Ask the administrator of your LDAP/AD server for help / for correct settings.
 * Maybe look into `MoinMoin/auth/ldap_login.py`, if you can debug or fix your problem there.

/!\ Only ask !MoinMoin support if you successfully used ldapsearch (or some similar tool) and you double checked your wiki config and it does still not work with moin.
