diff --git a/admin_manual/configuration_user/index.rst b/admin_manual/configuration_user/index.rst index 18ac09090..f3d3a9170 100644 --- a/admin_manual/configuration_user/index.rst +++ b/admin_manual/configuration_user/index.rst @@ -13,4 +13,5 @@ User Management user_auth_ftp_smb_imap user_auth_ldap user_auth_ldap_cleanup + user_auth_ldap_api user_provisioning_api diff --git a/admin_manual/configuration_user/user_auth_ldap_api.rst b/admin_manual/configuration_user/user_auth_ldap_api.rst new file mode 100644 index 000000000..82c97c5ce --- /dev/null +++ b/admin_manual/configuration_user/user_auth_ldap_api.rst @@ -0,0 +1,252 @@ +====================== +LDAP Configuration API +====================== + +Any used method requires the a header "OCS-APIREQUEST" set to "true". And any method takes an optional "format" parameter, which accepts "xml" (default) or "json". + +Methods +======= + +Creating a configuration +------------------------ + +Creates a new and empty LDAP configuration. It returns its ID. Authentication is done by sending a +basic HTTP authentication header. + +**Syntax: ocs/v2.php/apps/user_ldap/api/v1/config** + +* HTTP method: POST + +Example +^^^^^^^ + +* POST ``https://admin:secret@example.com/ocs/v2.php/apps/user_ldap/api/v1/config`` -H "OCS-APIREQUEST: true" +* Creates a new, empty configuration + +XML Output +^^^^^^^^^^ + +.. code-block:: xml + + + + + ok + 200 + OK + + + s01 + + + + +Deleting a configuration +------------------------ + +Deletes a given LDAP configuration. Authentication is done by sending a basic HTTP authentication header. + +**Syntax: ocs/v2.php/apps/user_ldap/api/v1/config/{configID}** + +* HTTP method: DELETE + +Example +^^^^^^^ + +* DELETE ``https://admin:secret@example.com/ocs/v2.php/apps/user_ldap/api/v1/config/s02 -H "OCS-APIREQUEST: true"`` +* deletes the LDAP configuration + +XML Output +^^^^^^^^^^ + +.. code-block:: xml + + + + + ok + 200 + OK + + + + + +Reading a configuration +----------------------- + +Returns all keys and values of the specified LDAP configuration. Authentication is done by sending a basic HTTP authentication header. + +**Syntax: ocs/v2.php/apps/user_ldap/api/v1/config/{configID}** + +* HTTP method: GET +* url argument: showPassword - int, optional, default 0, whether to return the password in clear text + +Example +^^^^^^^ + +* GET ``https://admin:secret@example.com/ocs/v2.php/apps/user_ldap/api/v1/config/s02?showPassword=1 -H "OCS-APIREQUEST: true"`` +* fetches the LDAP configuration + +XML Output +^^^^^^^^^^ + +.. code-block:: xml + + + + + ok + 200 + OK + + + ldap://ldap.server.tld + 389 + + + ou=Department XLII,dc=example,dc=com + ou=users,ou=Department XLII,dc=example,dc=com + ou=Department XLII,dc=example,dc=com + cn=root,dc=example,dc=com + Secret + 1 + 0 + + displayname + uid + gidNumber + inetOrgPerson + + (&(objectclass=nextcloudUser)(nextcloudEnabled=TRUE)) + 1 + (&(|(objectclass=nextcloudGroup))) + 0 + nextcloudGroup + + memberUid + cn + (&(|(objectclass=inetOrgPerson))(uid=%uid)) + 0 + 0 + 1 + + + 20 MB + mail + 600 + auto + auto + + 1 + uid;sn;givenname + + 0 + attr:mail + + 1 + 1 + + + + 0 + 0 + 500 + 1 + + + + + +Modifying a configuration +------------------------- + +Updates a configuration with the provided values. Authentication is done by sending a basic HTTP authentication header. + +**Syntax: ocs/v2.php/apps/user_ldap/api/v1/config/{configID}** + +* HTTP method: PUT +* url argument: configData - array, see table below for the fields. All fields are optional. The values must be url-encoded. + +Example +^^^^^^^ + +* PUT ``https://admin:secret@example.com/ocs/v2.php/apps/user_ldap/api/v1/config/s01 -H "OCS-APIREQUEST: true" -d "configData[ldapHost]=ldap%3A%2F%2Fldap.server.tld &configData[ldapPort]=389"`` +* fetches the LDAP configuration + +XML Output +^^^^^^^^^^ + +.. code-block:: xml + + + + + ok + 200 + OK + + + + +Configuration Keys +================== + + +-------------------------------+------+----------+-----------------------------------------------------------------------------------------------------------------------+ + | Key | mode | required |description | + +-------------------------------+------+----------+-----------------------------------------------------------------------------------------------------------------------+ + | ldapHost | rw | yes | LDAP server host, supports protocol | + | ldapPort | rw | yes | LDAP server port | + | ldapBackupHost | rw | no | LDAP replica host | + | ldapBackupPort | rw | no | LDAP replica port | + | ldapOverrideMainServer | rw | no | Whether replica should be used instead | + | ldapBase | rw | yes | Base | + | ldapBaseUsers | rw | no | Base for users, defaults to general base if not specified | + | ldapBaseGroups | rw | no | Base for groups, defaults to general base if not specified | + | ldapAgentName | rw | no | DN for the (service) user to connect to LDAP | + | ldapAgentPassword | rw | no | Password for the service user | + | ldapTLS | rw | no | Whether to use StartTLS | + | turnOffCertCheck | rw | no | Turns off certificate validation for TLS connections | + | ldapIgnoreNamingRules | rw | no | Backwards compatibility, do not set it. | + | ldapUserDisplayName | rw | yes | Attribute used as display name for users | + | ldapUserDisplayName2 | rw | no | Additional attribute, if set show on brackets next to the main attribute | + | ldapGidNumber | rw | no | group ID attribute, needed for primary groups on OpenLDAP (and compatible) | + | ldapUserFilterObjectclass | rw | no | set by the Settings Wizard (web UI) | + | ldapUserFilterGroups | rw | no | set by the Settings Wizard (web UI) | + | ldapUserFilter | rw | yes | LDAP Filter used to retrieve user | + | ldapUserFilterMode | rw | no | used by the Settings Wizard, set to 1 for manual editing | + | ldapAttributesForUserSearch | rw | no | attributes to be matched when searching for users. separate by ; | + | ldapGroupFilter | rw | no | LDAP Filter used to retrieve groups | + | ldapGroupFilterMode | rw | no | used by the Settings Wizard, set to 1 for manual editing | + | ldapGroupFilterObjectclass | rw | no | set by the Settings Wizard (web UI) | + | ldapGroupFilterGroups | rw | no | set by the Settings Wizard (web UI) | + | ldapGroupMemberAssocAttr | rw | no | attribute that indicates group members, one of: member, memberUid, uniqueMember, gidNumber | + | ldapGroupDisplayName | rw | no | Attribute used as display name for groups, required if groups are used | + | ldapAttributesForGroupSearch | rw | no | attributes to be matched when searching for groups. separate by ; | + | ldapLoginFilter | rw | yes | LDAP Filter used to authenticate users | + | ldapLoginFilterMode | rw | no | used by the Settings Wizard, set to 1 for manual editing | + | ldapLoginFilterEmail | rw | no | set by the Settings Wizard (web UI) | + | ldapLoginFilterUsername | rw | no | set by the Settings Wizard (web UI) | + | ldapLoginFilterAttributes | rw | no | set by the Settings Wizard (web UI) | + | ldapQuotaAttribute | rw | no | LDAP attribute containing the quote value (per user) | + | ldapQuotaDefault | rw | no | Default Quota, if specified quota attribute is empty | + | ldapEmailAttribute | rw | no | LDAP attribute containing the email address (takes first if multiple are stored) | + | ldapCacheTTL | rw | no | How long results from LDAP are cached, defaults to 10min | + | ldapUuidUserAttribute | r | no | set in runtime | + | ldapUuidGroupAttribute | r | no | set in runtime | + | ldapConfigurationActive | rw | no | whether this configuration is active. 1 is on, 0 is off. | + | ldapExperiencedAdmin | rw | no | used by the Settings Wizard, set to 1 for manual editing | + | homeFolderNamingRule | rw | no | LDAP attribute to use a user folder name | + | hasPagedResultSupport | r | no | set in runtime | + | hasMemberOfFilterSupport | r | no | set in runtime | + | useMemberOfToDetectMembership | rw | no | Whether to use memberOf to detect group memberships | + | ldapExpertUsernameAttr | rw | no | LDAP attribute to use as internal username. Might be modified (e.g. to avoid name collisions, character restrictions) | + | ldapExpertUUIDUserAttr | rw | no | override the LDAP servers UUID attribute to identify LDAP user records | + | ldapExpertUUIDGroupAttr | rw | no | override the LDAP servers UUID attribute to identify LDAP group records | + | lastJpegPhotoLookup | r | no | set in runtime | + | ldapNestedGroups | rw | no | Whether LDAP supports nested groups | + | ldapPagingSize | rw | no | Number of results to return per page | + | turnOnPasswordChange | rw | no | Whether users are allowed to change passwords (hashing must happen on LDAP!) | + | ldapDynamicGroupMemberURL | rw | no | URL for dynamic groups | + | ldapDefaultPPolicyDN | rw | no | PPolicy DN for password rules | + +-------------------------------+------+----------+-----------------------------------------------------------------------------------------------------------------------+