mirror of
https://github.com/nextcloud/documentation.git
synced 2026-01-03 02:09:45 +07:00
document LDAP API
Signed-off-by: Arthur Schiwon <blizzz@arthur-schiwon.de>
This commit is contained in:
Arthur Schiwon
committed by
Morris Jobke
Morris Jobke
parent
9c9fc50375
commit
14127bec2a
@@ -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
|
||||
|
||||
252
admin_manual/configuration_user/user_auth_ldap_api.rst
Normal file
252
admin_manual/configuration_user/user_auth_ldap_api.rst
Normal file
@@ -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
|
||||
|
||||
<?xml version="1.0"?>
|
||||
<ocs>
|
||||
<meta>
|
||||
<status>ok</status>
|
||||
<statuscode>200</statuscode>
|
||||
<message>OK</message>
|
||||
</meta>
|
||||
<data>
|
||||
<configID>s01</configID>
|
||||
</data>
|
||||
</ocs>
|
||||
|
||||
|
||||
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
|
||||
|
||||
<?xml version="1.0"?>
|
||||
<ocs>
|
||||
<meta>
|
||||
<status>ok</status>
|
||||
<statuscode>200</statuscode>
|
||||
<message>OK</message>
|
||||
</meta>
|
||||
<data/>
|
||||
</ocs>
|
||||
|
||||
|
||||
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
|
||||
|
||||
<?xml version="1.0"?>
|
||||
<ocs>
|
||||
<meta>
|
||||
<status>ok</status>
|
||||
<statuscode>200</statuscode>
|
||||
<message>OK</message>
|
||||
</meta>
|
||||
<data>
|
||||
<ldapHost>ldap://ldap.server.tld</ldapHost>
|
||||
<ldapPort>389</ldapPort>
|
||||
<ldapBackupHost></ldapBackupHost>
|
||||
<ldapBackupPort></ldapBackupPort>
|
||||
<ldapBase>ou=Department XLII,dc=example,dc=com</ldapBase>
|
||||
<ldapBaseUsers>ou=users,ou=Department XLII,dc=example,dc=com</ldapBaseUsers>
|
||||
<ldapBaseGroups>ou=Department XLII,dc=example,dc=com</ldapBaseGroups>
|
||||
<ldapAgentName>cn=root,dc=example,dc=com</ldapAgentName>
|
||||
<ldapAgentPassword>Secret</ldapAgentPassword>
|
||||
<ldapTLS>1</ldapTLS>
|
||||
<turnOffCertCheck>0</turnOffCertCheck>
|
||||
<ldapIgnoreNamingRules/>
|
||||
<ldapUserDisplayName>displayname</ldapUserDisplayName>
|
||||
<ldapUserDisplayName2>uid</ldapUserDisplayName2>
|
||||
<ldapGidNumber>gidNumber</ldapGidNumber>
|
||||
<ldapUserFilterObjectclass>inetOrgPerson</ldapUserFilterObjectclass>
|
||||
<ldapUserFilterGroups></ldapUserFilterGroups>
|
||||
<ldapUserFilter>(&(objectclass=nextcloudUser)(nextcloudEnabled=TRUE))</ldapUserFilter>
|
||||
<ldapUserFilterMode>1</ldapUserFilterMode>
|
||||
<ldapGroupFilter>(&(|(objectclass=nextcloudGroup)))</ldapGroupFilter>
|
||||
<ldapGroupFilterMode>0</ldapGroupFilterMode>
|
||||
<ldapGroupFilterObjectclass>nextcloudGroup</ldapGroupFilterObjectclass>
|
||||
<ldapGroupFilterGroups></ldapGroupFilterGroups>
|
||||
<ldapGroupMemberAssocAttr>memberUid</ldapGroupMemberAssocAttr>
|
||||
<ldapGroupDisplayName>cn</ldapGroupDisplayName>
|
||||
<ldapLoginFilter>(&(|(objectclass=inetOrgPerson))(uid=%uid))</ldapLoginFilter>
|
||||
<ldapLoginFilterMode>0</ldapLoginFilterMode>
|
||||
<ldapLoginFilterEmail>0</ldapLoginFilterEmail>
|
||||
<ldapLoginFilterUsername>1</ldapLoginFilterUsername>
|
||||
<ldapLoginFilterAttributes></ldapLoginFilterAttributes>
|
||||
<ldapQuotaAttribute></ldapQuotaAttribute>
|
||||
<ldapQuotaDefault>20 MB</ldapQuotaDefault>
|
||||
<ldapEmailAttribute>mail</ldapEmailAttribute>
|
||||
<ldapCacheTTL>600</ldapCacheTTL>
|
||||
<ldapUuidUserAttribute>auto</ldapUuidUserAttribute>
|
||||
<ldapUuidGroupAttribute>auto</ldapUuidGroupAttribute>
|
||||
<ldapOverrideMainServer></ldapOverrideMainServer>
|
||||
<ldapConfigurationActive>1</ldapConfigurationActive>
|
||||
<ldapAttributesForUserSearch>uid;sn;givenname</ldapAttributesForUserSearch>
|
||||
<ldapAttributesForGroupSearch></ldapAttributesForGroupSearch>
|
||||
<ldapExperiencedAdmin>0</ldapExperiencedAdmin>
|
||||
<homeFolderNamingRule>attr:mail</homeFolderNamingRule>
|
||||
<hasPagedResultSupport></hasPagedResultSupport>
|
||||
<hasMemberOfFilterSupport>1</hasMemberOfFilterSupport>
|
||||
<useMemberOfToDetectMembership>1</useMemberOfToDetectMembership>
|
||||
<ldapExpertUsernameAttr></ldapExpertUsernameAttr>
|
||||
<ldapExpertUUIDUserAttr></ldapExpertUUIDUserAttr>
|
||||
<ldapExpertUUIDGroupAttr></ldapExpertUUIDGroupAttr>
|
||||
<lastJpegPhotoLookup>0</lastJpegPhotoLookup>
|
||||
<ldapNestedGroups>0</ldapNestedGroups>
|
||||
<ldapPagingSize>500</ldapPagingSize>
|
||||
<turnOnPasswordChange>1</turnOnPasswordChange>
|
||||
<ldapDynamicGroupMemberURL></ldapDynamicGroupMemberURL>
|
||||
<ldapDefaultPPolicyDN></ldapDefaultPPolicyDN>
|
||||
</data>
|
||||
</ocs>
|
||||
|
||||
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
|
||||
|
||||
<?xml version="1.0"?>
|
||||
<ocs>
|
||||
<meta>
|
||||
<status>ok</status>
|
||||
<statuscode>200</statuscode>
|
||||
<message>OK</message>
|
||||
</meta>
|
||||
<data/>
|
||||
</ocs>
|
||||
|
||||
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 |
|
||||
+-------------------------------+------+----------+-----------------------------------------------------------------------------------------------------------------------+
|
||||
Reference in New Issue
Block a user