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

<?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

<?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

<?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>(&amp;(objectclass=nextcloudUser)(nextcloudEnabled=TRUE))</ldapUserFilter>
  <ldapUserFilterMode>1</ldapUserFilterMode>
  <ldapGroupFilter>(&amp;(|(objectclass=nextcloudGroup)))</ldapGroupFilter>
  <ldapGroupFilterMode>0</ldapGroupFilterMode>
  <ldapGroupFilterObjectclass>nextcloudGroup</ldapGroupFilterObjectclass>
  <ldapGroupFilterGroups></ldapGroupFilterGroups>
  <ldapGroupMemberAssocAttr>memberUid</ldapGroupMemberAssocAttr>
  <ldapGroupDisplayName>cn</ldapGroupDisplayName>
  <ldapLoginFilter>(&amp;(|(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

<?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