Add LDAP doc

admin_manual/auth_ldap.rst

@@ -0,0 +1,250 @@
+User Authentication with LDAP
+=============================
+
+ownCloud ships an LDAP backend, which allows full use of ownCloud for user
+logging in with LDAP credentials including:
+
+* LDAP group support
+* File sharing with users and groups
+* Access via WebDAV and of course ownCloud Desktop Clien
+* Versioning, external Storages and all other ownCloud Goodies
+
+To connect to an LDAP server the configuration needs to be set up properly.
+Once the LDAP backend is activated (Settings→Apps, choose ``LDAP user and group
+backend``, click on ``Enable``) the configuration can be found on
+Settings→Admin. Read on for a detailed description of the configuration fields.
+
+Basic Settings
+--------------
+
+The basic settings are all you need. However, if you have a larger directory or
+custom requirements you want to have a look on the advanced settings
+afterwards. The basic part allows you to set up a working connection to your
+LDAP server and use it with ownCloud.
+
+.. figure:: images/ldap-basic-settings-oc451.png
+
+   LDAP Basic Settings
+
+Note that a hint will be shown on the right handside, when hovering with the
+mouse over an input field. This gives you more context information while
+filling out the settings.
+
+Settings Details
+~~~~~~~~~~~~~~~~
+
+:Host:
+  The hostname of the LDAP server. It can also be a ``ldaps://`` URI, for
+  instance. 
+
+  * *Example: directory.my-company.com*
+
+:Base DN:
+  The base DN of LDAP, from where all users and groups can be reached.
+  Seperated Base DNs for users and groups can be set in the Advanced
+  tab. Nevertheless, this field is mandatory.
+
+  * *Example: dc=my-company,dc=com*
+
+:User DN:
+  The name as DN of a user who is able to do searches in the LDAP
+  directory. Let it empty for anonymous access. It is recommended to have a
+  special system user for ownCloud.
+
+  * *Example: uid=owncloudsystemuser,cn=sysusers,dc=my-company,dc=com*
+  * formerly ``Name`` in oC 4.0
+
+:Password:
+  The password for the user given above. Empty for anonymous access.
+
+:User Login Filter:
+  The filter to use when a users tries to login. Use ``%uid`` as placeholder
+  for the username. Note, that login applies this filter only, but not User
+  List Filter. This may change in future. 
+
+  * Example (allows login with username and email adress): ``(|(uid=%uid)(email=$uid))``
+
+:User List Filter:
+  The filter to use when a search for users will be executed.
+
+  * Example: ``objectClass=posixAccount``
+
+:Group Filter:
+  The filter to use when a search for groups will be executed. In
+  case you do not want to use LDAP groups in ownCloud, leave it empty.
+
+  * Example: ``objectClass=posixGroup``
+
+Advanced Settings
+-----------------
+
+In the LDAP Advanced settings section you can define options, that are less
+common to set. They are not needed for a working connection, unless you use a
+non-standard Port, e.g. It can also have a positive effect on the performance
+to specifiy distinguished bases for user and group searches.
+
+.. figure:: images/ldap-advanced-settings-oc451.png
+
+   LDAP Advanced Settings
+
+Settings Details
+~~~~~~~~~~~~~~~~
+
+:Port:
+  The port LDAP server Example: 389 Base User Tree: The base DN of LDAP,
+  from where all users can be reached. It needs to be given completely despite
+  to the Base DN from the Basic settings.
+
+  * Example: ``cn=users,dc=my-company,dc=com``
+
+:Base Group Tree:
+  The base DN of LDAP, from where all groups can be reached.
+  It needs to be given completely despite to the Base DN from the Basic
+  settings.
+
+  * Example: ``cn=groups,dc=my-company,dc=com``
+
+:Group Member association:
+  The attribute that is used to indicate group memberships, i.e. the attribute
+  used by LDAP groups to refer to their users.
+
+  * Example: uniquemember
+
+:Use TLS:
+  Wether to use TLS encrypted connection to the LDAP server.
+  In case you use SSL connections (via ldaps) do not check it, it will fail.
+
+  * Example: [ ]
+
+:Case insensitive LDAP server (Windows): 
+  Wether theLDAP server is running on a Windows Host
+
+  * Example: [ ]
+
+:Turn off SSL certificate validation:
+  Turns of check of valid SSL certificates. Use it – if needed –
+  for testing, only!
+
+  * Example: [ ]
+
+:User Display Name Field: 
+  The attribute that should be used as ownCloud username. ownCloud allows
+  a limited set of characters ``(a-zA-Z0-9.-_@)``, every other character 
+  will be replaced in ownCloud. Once a username is assigned, it will not be
+  changed, i.e. changing this value will only have effect to new LDAP users.
+  The default, uid, does not exist in AD, switch to ``cn``, for example,
+  otherwise you will not see any users.
+
+  *  Example: displayName
+
+:Group Display Name Field: 
+  The attribute that should be used as ownCloud
+  groupname. ownCloud allows a limited set of characters (a-zA-Z0-9.-_@), every
+  other character will be replaced in ownCloud. Once a groupname is assigned, it
+  will not be changed, i.e. changing this value will only have effect to new
+  LDAP groups.
+
+  * Example: ``cn`` 
+
+:Quota Attribute: 
+  ownCloud can read an LDAP attribute and set the user quota
+  there from. Specify the attribute here, otherwise keep it empty.
+
+  * Example: ownCloudQuota
+  * formerly Quota Field in oC 4.0 
+
+:Quota Default: 
+  Override ownCloud default quota for LDAP users who do not 
+  have a quota set in the attribute given above.  
+
+  * Example: 15 GB
+
+:Email Attribute:
+  ownCloud can read an LDAP attribute and set the user email
+  there from. Specify the attribute here, otherwise keep it empty.
+
+  * Example: email
+
+:Cache Time-To-Live:
+  We introduced a cache to avoid unnecessary LDAP traffic,
+  for example lookups check wether the users exists on every page request or
+  WebDAV interaction. It is also supposed to speed up the Admin → User page or
+  list of users to share with, once it is populated. Changing this setting
+  empties the Cache. The time is given in seconds. 
+
+  * Example (10 min): 600
+
+:User Home Folder Naming Rule:
+  By default, the ownCloud creates the user
+  directory, where all files and meta data are kept, according to the ownCloud
+  username. You may want to override this setting and name it after an
+  attribute’s value. Once set for a user, the user name folder will not change,
+  i.e. changing this value will only have effect to new LDAP users. Leave it
+  empty to default behaviour
+
+  * Example: cn 
+
+Microsoft Active Directory
+--------------------------
+
+In case you want to connect to a Windows AD, you must change some values in the Advanced tab.
+
+* The default in User Display Name Field will not work with Active Directory.
+* The Group Member association must be set to “member (AD)” Check Case insensitive
+* LDAP server (Windows)
+
+Testing the configuration
+-------------------------
+
+In this version we introduced the ``Test Configuration`` button on the bottom
+of the LDAP settings section. It will always check the values as currently
+given in the input fields. You do not need to save before testíng. By clicking
+on the button, ownCloud will try to bind to the ownCloud server with the
+settings currently given in the input fields. The response will look like this:
+
+.. figure:: images/ldap-settings-invalid-oc45.png
+
+   Failure
+
+In case the configuration fails, you can see details in ownCloud’s log, which
+is in the data directory and called ``owncloud.log`` or on the bottom the
+``Settings →  Admin page``. Unfortunately it requires a reload – sorry for the
+inconvenience.
+
+.. figure:: images/ldap-settings-valid-oc45.png
+
+   Success 
+
+In this case, Save the settings. You can check if the users and groups are
+fetched correctly on the Settings → Users page.
+
+ownCloud LDAP Internals
+-----------------------
+
+Some parts of how the LDAP backend works are described here. May it be helpful.
+
+User and Group Mapping
+----------------------
+
+In ownCloud, the username is automatically the user ID, same applies for
+groups. That’s why we map the DN and UUID of the LDAP object to an ownCloud
+name. Those mappings are done in the database table ldap_user_mapping and
+ldap_group_mapping. The username is also used for the user’s folder, which
+contains files and meta data. Most ownCloud applications, like Sharing, use the
+username to refer to a user. Renaming a user (or a group) is not supported.
+That means that your LDAP configuration should be good and ready before putting
+it into production. The mapping tables are filled early, but as long as you are
+testing, you empty the tables any time. Don’t do this in production. If you
+want to rename a user or a group, be very careful.
+
+Caching
+-------
+
+For performance reasons a cache has been introduced to ownCloud. He we store
+all users and groups, group memberships or internal userExists-requests. Since
+ownCloud is written in PHP and each and every page rerquest (also done by Ajax)
+loads ownCloud and would execute one or more LDAP queries again, you do want to
+have some of those queries cached and save those requests and traffic. It is
+highly recommended to have the cache filled for a small amount of time, which
+comes also very handy when using the sync client, as it is yet another request
+for PHP.

admin_manual/index.rst

@@ -11,7 +11,8 @@ Contents
 
    introduction
    installation 
-   update 
+   update
+   auth_ldap 
 .. add more chapters