The LDAP configuration API
All methods require that the “OCS-APIREQUEST” header be set to “true”. Methods take an optional “format” parameter, which may be “xml” (the default) or “json”.
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
$ curl -X 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
$ curl -X 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
$ curl -X 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>(&(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
$ curl -X 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"
updates 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 |
ldapUserAvatarRule |
rw |
no |
Specify the avatar integration behavior, possible values: “default”, “none”, “data:$ATTRIBUTENAME” |
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 |