Server tab

Start with the Server tab. You may configure multiple servers if you have them.

Note

Do not configure any failover LDAP hosts here. See Advanced settings for instructions instead.

At a minimum you must supply the LDAP server’s hostname. If your server requires authentication, enter your credentials on this tab. Nextcloud will then attempt to auto-detect the server’s port and base DN. The base DN and port are mandatory, so if Nextcloud cannot detect them you must enter them manually.

Server configuration:

Configure one or more LDAP servers. Click the Delete Configuration button to remove the active configuration.

Host:

The host name or IP address of the LDAP server. It can also be a ldaps:// URI. If you enter the port number, it speeds up server detection.

Examples:

• directory.my-company.com

• ldaps://directory.my-company.com

• directory.my-company.com:9876

Port:

The port on which to connect to the LDAP server. The field is disabled in the beginning of a new configuration. If the LDAP server is running on a standard port, the port will be detected automatically. If you are using a non-standard port, Nextcloud will attempt to detect it. If this fails you must enter the port number manually.

Example:

• 389

User DN:

The name as DN of a user who has permissions to do searches in the LDAP directory. Leave it empty for anonymous access. We recommend that you have a special LDAP system user for this.

Example:

• uid=nextcloudsystemuser,cn=sysusers,dc=my-company,dc=com

Password:

The password for the user given above. Empty for anonymous access.

Base DN:

The base DN of LDAP, from where all users and groups can be reached. You may enter multiple base DNs, one per line. (Base DNs for users and groups can be set in the Advanced tab.) This field is mandatory. Nextcloud attempts to determine the Base DN according to the provided User DN or the provided Host, and you must enter it manually if Nextcloud does not detect it.

Example:

• dc=my-company,dc=com

Users tab

Use this to control which LDAP users are listed as Nextcloud users on your Nextcloud server. In order to control which LDAP users can login to your Nextcloud server use the Login Attributes tab. Those LDAP users who have access but are not listed as users (if there are any) will be hidden users. You may bypass the form fields and enter a raw LDAP filter if you prefer.

Only those object classes:

Nextcloud will determine the object classes that are typically available for user objects in your LDAP. Nextcloud will automatically select the object class that returns the highest amount of users. You may select multiple object classes.

Only from those groups:

If your LDAP server supports the member-of-overlay in LDAP filters, you can define that only users from one or more certain groups are allowed to appear in user listings in Nextcloud. By default, no value will be selected. You may select multiple groups.

If your LDAP server does not support the member-of-overlay in LDAP filters, the input field is disabled. Please contact your LDAP administrator.

Edit LDAP Query:

Clicking on this text toggles the filter mode and you can enter the raw LDAP filter directly. Example:

(&(objectClass=inetOrgPerson)(memberOf=cn=nextcloudusers,ou=groups,
dc=example,dc=com))

x users found:

This is an indicator that tells you approximately how many users will be listed in Nextcloud. The number updates automatically after any changes.

Login attributes tab

The settings in the Login Attributes tab determine which LDAP users can log in to your Nextcloud system and which attribute or attributes the provided login name is matched against (e.g. LDAP/AD username, email address). You may select multiple user details. (You may bypass the form fields and enter a raw LDAP filter if you prefer.)

You may override your User Filter settings on the Users tab by using a raw LDAP filter.

LDAP Username:

If this value is checked, the login value will be compared to the username in the LDAP directory. The corresponding attribute, usually uid or samaccountname will be detected automatically by Nextcloud.

LDAP Email Address:

If this value is checked, the login value will be compared to an email address in the LDAP directory; specifically, the mailPrimaryAddress and mail attributes.

Other Attributes:

This multi-select box allows you to select other attributes for the comparison. The list is generated automatically from the user object attributes in your LDAP server.

Edit LDAP Query:

Clicking on this text toggles the filter mode and you can enter the raw LDAP filter directly.

The %uid placeholder is replaced with the login name entered by the user upon login.

Examples:

• only username:

  (&(objectClass=inetOrgPerson)(memberOf=cn=nextcloudusers,ou=groups,
  dc=example,dc=com)(uid=%uid)
  

• username or email address:

  ((&(objectClass=inetOrgPerson)(memberOf=cn=nextcloudusers,ou=groups,
  dc=example,dc=com)(|(uid=%uid)(mail=%uid)))
  

Groups tab

By default, no LDAP groups will be available in Nextcloud. The settings in the Groups tab determine which groups will be available in Nextcloud. You may also elect to enter a raw LDAP filter instead.

Only these object classes:

Nextcloud will determine the object classes that are typically available for group objects in your LDAP server. Nextcloud will only list object classes that return at least one group object. You can select multiple object classes. A typical object class is “group”, or “posixGroup”.

Only from these groups:

Nextcloud will generate a list of available groups found in your LDAP server. Then you select the group or groups that get access to your Nextcloud server.

Edit LDAP Query:

Clicking on this text toggles the filter mode and you can enter the raw LDAP filter directly.

Example:

• objectClass=group

• objectClass=posixGroup

y groups found:

This tells you approximately how many groups will be available in Nextcloud. The number updates automatically after any change.

Connection settings

Configuration Active:

Enables or Disables the current configuration. By default, it is turned off. When Nextcloud makes a successful test connection it is automatically turned on.

Backup (Replica) Host:

If you have a backup LDAP server, enter the connection settings here. Nextcloud will then automatically connect to the backup when the main server cannot be reached. The backup server must be a replica of the main server so that the object UUIDs match.

Example:

• directory2.my-company.com

Backup (Replica) Port:

The connection port of the backup LDAP server. If no port is given, but only a host, then the main port (as specified above) will be used.

Example:

• 389

Disable Main Server:

You can manually override the main server and make Nextcloud only connect to the backup server. This is useful for planned downtimes.

Turn off SSL certificate validation:

Turns off SSL certificate checking. Use it for testing only! Note: The effect of this setting depends on the PHP system configuration. It does for example not work with the [official Nextcloud container image](https://github.com/nextcloud/docker). To disable certificate verification for a particular use, append the following configuration line to your /etc/ldap/ldap.conf:

` TLS_REQCERT ALLOW `

Cache Time-To-Live:

A cache is introduced to avoid unnecessary LDAP traffic, for example caching usernames so they don’t have to be looked up for every page, and speeding up loading of the Users page. Saving the configuration empties the cache. The time is given in seconds.

Note that almost every PHP request requires a new connection to the LDAP server. If you require fresh PHP requests we recommend defining a minimum lifetime of 15s or so, rather than completely eliminating the cache.

Examples:

• ten minutes: 600

• one hour: 3600

See the Caching section below for detailed information on how the cache operates.

Directory settings

User Display Name Field:

The attribute that should be used as display name in Nextcloud.

• Example: displayName

2nd User Display Name Field:

An optional second attribute displayed in brackets after the display name, for example using the mail attribute displays as Molly Foo (molly@example.com).

Base User Tree:

The base DN of LDAP, from where all users can be reached. This must be a complete DN, regardless of what you have entered for your Base DN in the Basic setting. You can specify multiple base trees, one on each line.

• Example:

  cn=programmers,dc=my-company,dc=com

  cn=designers,dc=my-company,dc=com

User Search Attributes:

These attributes are used when searches for users are performed, for example in the share dialogue. The user display name attribute is the default. You may list multiple attributes, one per line.

If an attribute is not available on a user object, the user will not be listed, and will be unable to login. This also affects the display name attribute. If you override the default you must specify the display name attribute here.

• Example:

  displayName

  mail

Disable users missing from LDAP

If this is enabled, users which are missing from LDAP, also known as remnants, will behave as if disabled in Nextcloud. This means for instance that public shares by these users will not work anymore. see also LDAP user cleanup.

Group Display Name Field:

The attribute that should be used as Nextcloud group name. Nextcloud allows a limited set of characters (a-zA-Z0-9.-_@). Once a group name is assigned it cannot be changed.

• Example: cn

Base Group Tree:

The base DN of LDAP, from where all groups can be reached. This must be a complete DN, regardless of what you have entered for your Base DN in the Basic setting. You can specify multiple base trees, one in each line.

• Example:

  cn=barcelona,dc=my-company,dc=com

  cn=madrid,dc=my-company,dc=com

Group Search Attributes:

These attributes are used when a search for groups is done, for example in the share dialogue. By default the group display name attribute as specified above is used. Multiple attributes can be given, one in each line.

If you override the default, the group display name attribute will not be taken into account, unless you specify it as well.

• Example:

  cn

  description

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.

Nextcloud detects the value automatically. You should only change it if you have a very valid reason and know what you are doing.

• Example: uniquemember

Nested groups:

Enable group member retrieval from sub groups.

To allow user listing and login from nested groups, please see User listing and login per nested groups in the section Troubleshooting, Tips and Tricks.

Enable LDAP password changes per user:

Allow LDAP users to change their password and allow Super Administrators and Group Administrators to change the password of their LDAP users.

To enable this feature, the following requirements have to be met:

• General requirements:

• Access control policies must be configured on the LDAP server to grant permissions for password changes. The User DN as configured in Server Settings needs to have write permissions in order to update the userPassword attribute.

• Passwords are sent in plaintext to the LDAP server. Therefore, transport encryption must be used for the communication between Nextcloud and the LDAP server, e.g. employ LDAPS.

• Enabling password hashing on the LDAP server is highly recommended. While Active Directory stores passwords in a one-way format by default, OpenLDAP users could configure the ppolicy_hash_cleartext directive of the ppolicy overlay that ships with OpenLDAP.

• Additional requirements for Active Directory:

• At least a 128-bit transport encryption must be used for the communication between Nextcloud and the LDAP server.

• Make sure that the fUserPwdSupport char of the dSHeuristics is configured to employ the userPassword attribute as unicodePwd alias. While this is set accordingly on AD LDS by default, this is not the case on AD DS.

Default password policy DN:

This feature requires OpenLDAP with ppolicy. The DN of a default password policy will be used for password expiry handling in the absence of any user specific password policy. Password expiry handling features the following:

• When a LDAP password is about to expire, display a warning message to the user showing the number of days left before it expires. Password expiry warnings are displayed through the notifications app for Nextcloud.

• Prompt LDAP users with expired passwords to reset their password during login, provided that an adequate number of grace logins is still available.

Leave the setting empty to keep password expiry handling disabled.

For the password expiry handling feature to work, LDAP password changes per user must be enabled and the LDAP server must be running OpenLDAP with its ppolicy module configured accordingly.

• Example:

  cn=default,ou=policies,dc=my-company,dc=com

Special attributes

Quota Field:

Nextcloud can read an LDAP attribute and set the user quota according to its value. Specify the attribute here, and it will return human-readable values, e.g. “2 GB”.

• Example: NextcloudQuota

Warning

LDAP quota parameters override quota parameters set in the Nextcloud user management page.

Quota Default:

Specifies a default quota for LDAP users who do not have a quota set in the above Quota Field.

• Example: 15 GB

Warning

LDAP quota parameters override quota parameters set in the Nextcloud user management page.

Email Field:

Set the user’s email from their LDAP attribute. Leave it empty for default behavior.

• Example: mail

User Home Folder Naming Rule:

By default, the Nextcloud server creates the user directory in your Nextcloud data directory and gives it the Nextcloud username, .e.g /var/www/nextcloud/data/alice. You may want to override this setting and name it after an LDAP attribute value. The attribute can also return an absolute path, e.g. /mnt/storage43/alice. Leave it empty for default behavior.

• Example: cn

In new Nextcloud installations the home folder rule is enforced. This means that once you set a home folder naming rule (get a home folder from an LDAP attribute), it must be available for all users. If it isn’t available for a user, then that user will not be able to login. Also, the filesystem will not be set up for that user, so their file shares will not be available to other users.

In migrated Nextcloud installations the old behavior still applies, which is using the Nextcloud username as the home folder when an LDAP attribute is not set. You may change this enforcing the home folder rule with the occ command in Nextcloud, like this example on Ubuntu:

sudo -E -u www-data php occ config:app:set user_ldap enforce_home_folder_naming_rule --value=1

User Profile attributes

After configuring those attributes, the User Profile data will be overwritten with the according data from LDAP. The checksum of data from LDAP will be stored in user settings user_ldap, lastProfileChecksum and profile update is skipped as long as data from LDAP doesn’t change. If memcache.distributed is enabled in config.php the checksum will be cached and the checking will be skipped, as long as the cached value exists (expires after ldapCacheTTL seconds).

Please be aware:

• The user can change the data in profile, but it will get overwritten if changed in LDAP

• The user can change the visibility scope in profile

• The default visibility can be adjusted with setting the account_manager.default_property_scope array in config.php

• If multiple attribute values are present, only the first distributed value is used

• All user profile properties are limited to 2048 character

• Having misformatted data in LDAP will most probably leave you with empty user profile fields

• Setting the global profile.enabled => false on config.php skips the code

By calling sudo -E -u www-data php occ ldap:check-user --update <uid> the users data from LDAP will be displayed and the profile gets updated. To get the correct <uid> value for any user you can use php occ user:list.

Note

After unsetting an attribute name here, the data won’t be deleted from user profile. Setting an nonexisting attribute will empty the corresponding profile field.

Phone Field:

The LDAP Attribute holding the phone number, to copy to the Profile Phone field. The phone number has to be formatted in international syntax without delimiters (E.164). Be sure to format phone numbers like +4966612345678.

• Example: telephoneNumber

• Example: mobile

Note

You should set your default_phone_region in config.php.

Website Field:

The LDAP attribute holding the website URI. The URI must start with https:// or http:// others are currently not allowed in Nextcloud user profile. If using labeledURI attributes the label (everything after first SPACE) gets removed.

• Example: wWWHomePage

• Example: labeledURI

Address Field:

The LDAP attribute holding the users address. Named Location on user profile page. Nextcloud wants a single line value like city, country or somewhere under the loving sun. Multi line postalAddress format will get reformatted, DOLLAR sign delimiter gets replaced with COMMA+SPACE.

• Example: postalAddress

• Example: localityName

Twitter Field:

The LDAP attribute holding the Twitter account name.

Fediverse Field:

The LDAP attribute holding the users Fediverse address.

Organisation Field:

The LDAP attribute holding the Organisation name.

• Example: company

• Example: o or organizationName

Role Field:

The LDAP attribute holding the organizational role, within the organisation or job title.

• Example: title

Headline Field:

The LDAP attribute holding the users headline.

Biography Field:

The LDAP attribute holding the users about i.e. short biography. Multi line value with unix LF line ending. Windows CRLF and Macintosh CR line endings will be replaced with unix LF line ending.

Birthdate Field:

The LDAP attribute holding the user’s date of birth. Allowed formats:

• LDAP GeneralizedTime

• YYYY-MM-DD

• YYYYMMDD

Attribute update interval

The LDAP backend will update user information that is used within Nextcloud with the values provided by the LDAP server. For instance these are email, quota or the avatar. This happens on every login, the first detection of a user from LDAP and regularly by a background job.

The interval value determines the time between updates of the values and is used to avoid frequent overhead, including time-expensive write actions to the database.

The interval is described in seconds and it defaults to 86400 equalling a day. It is not a per-configuration option.

The value can be modified by:

sudo -E -u www-data php occ config:app:set user_ldap updateAttributesInterval --value=86400

A value of 0 will update it on every of the named occasions.

Administrative Group mapping

It is possible to promote one LDAP per connection as an admin group, so that all its members also have administrative privileges in Nextcloud.

A group can either be promoted via a dedicated occ call providing a group parameter that can be either a nextcloud group ID or a group name that will be search against. When a search is executed an exact match is required.

Example usage:

$ sudo -E -u www-data php occ ldap:promote-group --help
Description:
  declares the specified group as admin group (only one is possible per LDAP configuration)

Usage:
  ldap:promote-group [options] [--] <group>

Arguments:
  group                 the group ID in Nextcloud or a group name

Options:
  -y, --yes             do not ask for confirmation
…

# Example
$ sudo -E -u www-data php occ ldap:promote-group  "Nextcloud Admins"
Promote Nextcloud Admins to the admin group (y|N)? y
Group Nextcloud Admins was promoted

$ sudo -E -u www-data php occ ldap:promote-group  "Paramount Court"
Promote Nextcloud Admins to the admin group and demote Nextcloud Admins (Group ID: nextcloud_admins) (y|N)? y
Group Paramount Court was promoted

$ sudo -E -u www-data php occ ldap:promote-group  "Paramount Court"
The specified group is already promoted

Note

Note the group ID will only be displayed when it differs from the group’s display name.

It is also possible to set the admin group mapping using occ ldap:set-config $configId ldapAdminGroup $groupId, but as the Nextcloud group ID might not be known (yet) it is recommended (especially for automated setups) to use the promote-group command, that would also pull in the group and determine the group ID.

In order to demote or reset a promotion, an empty string should be set against to the targeted config’s ldapAdminGroup:

# Reset an admin group mapping via set-config
occ ldap:set-config $configId ldapAdminGroup ""
# Example
occ ldap:set-config s01 ldapAdminGroup ""

Tip

To have more than one administrative groups in a connection, create a holding group in your LDAP directory that contains the single groups as nested members, and promote this one.

Use a specific attribute or turn off loading of images

It is possible to turn off the avatar integration or specify a single, different attribute to read the image from. It is expected to contain image data just like jpegPhoto or thumbnailPhoto do.

The behaviour can be changed using the occ command line tool only. Essentially those options are available:

• The default behaviour as described above should be used

  occ ldap:set-config "s01" "ldapUserAvatarRule" "default"

• User images shall not be fetched from LDAP

  occ ldap:set-config "s01" "ldapUserAvatarRule" "none"

• The image should be read from the attribute “selfiePhoto”

  occ ldap:set-config "s01" "ldapUserAvatarRule" "data:selfiePhoto"

The “s01” refers to the configuration ID as can be retrieved per occ ldap:show-config.

Logging

Nextcloud’s LDAP implementation is capable of logging lots of additional details about its activities. When diagnosing problems, it can be useful to temporarily adjust your loglevel to INFO (1) or DEBUG (0).

SSL certificate verification (LDAPS, TLS)

A common mistake with SSL certificates is that they may not be known to PHP. If you have trouble with certificate validation make sure that

• You have the certificate of the server installed on the Nextcloud server

• The certificate is announced in the system’s LDAP configuration file (usually /etc/ldap/ldap.conf)

• Using LDAPS, also make sure that the port is correctly configured (by default 636)

Microsoft Active Directory

Compared to earlier Nextcloud versions, no further tweaks need to be done to make Nextcloud work with Active Directory. Nextcloud will automatically find the correct configuration in the set-up process.

memberOf / read memberof permissions

If you want to use memberOf within your filter you might need to give your querying user the permissions to use it. For Microsoft Active Directory this is described here.

User listing and login per nested groups

When it is intended to allow user listing and login based on a specific group having subgroups (“nested groups”), checking Nested groups on Directory Settings is not enough. Also the User (and Login) filter need to be changed, by specifying the LDAP_MATCHING_RULE_IN_CHAIN matching rule. Change the filter parts containing the memberof condition according to this example:

• (memberof=cn=Nextcloud Users Group,ou=Groups,…)

to

• (memberof:1.2.840.113556.1.4.1941:=cn=Nextcloud Users Group,ou=Groups,…)

Duplicating server configurations

In case you have a working configuration and want to create a similar one or “snapshot” configurations before modifying them you can do the following:

1. Go to the Server tab

2. On Server Configuration choose Add Server Configuration

3. Answer the question Take over settings from recent server configuration? with yes.

4. (optional) Switch to Advanced tab and uncheck Configuration Active in the Connection Settings, so the new configuration is not used on Save

5. Click on Save

Now you can modify and enable the configuration.

User and group mapping

In Nextcloud the user or group name is used to have all relevant information in the database assigned. To work reliably a permanent internal user name and group name is created and mapped to the LDAP DN and UUID. If the DN changes in LDAP it will be detected, and there will be no conflicts.

Those mappings are done in the database table ldap_user_mapping and ldap_group_mapping. The user name is also used for the user’s folder (except if something else is specified in User Home Folder Naming Rule), which contains files and meta data.

The internal user name and a visible display name are separated. This is not the case for group names, yet, i.e. a group name cannot be altered.

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 can empty the tables any time. Do not do this in production.

The attributes of users are fetched on demand (i.e. for sharing autocompletion or in the user management) and then stored inside the Nextcloud database to allow a better performance on our side. They are typically checked twice a day in batches from all users again. Beside that they are also refreshed during a login for this user or can be fetched manually via the occ command occ ldap:check-user --update USERID where USERID is Nextcloud’s user id.

For groups, a cache of memberships is stored in the database to be able to trigger events when a membership is added or removed. This cache is updated by a background job, and can be force updated using occ ldap:check-group --update GROUPID.

Caching

The LDAP information is cached in Nextcloud memory cache, and you must install and configure the memory cache (see Memory caching). The Nextcloud Cache helps to speed up user interactions and sharing. It is populated on demand, and remains populated until the Cache Time-To-Live for each unique request expires. User logins are not cached, so if you need to improve login times set up a slave LDAP server to share the load.

You can adjust the Cache Time-To-Live value to balance performance and freshness of LDAP data. All LDAP requests will be cached for 10 minutes by default, and you can alter this with the Cache Time-To-Live setting. The cache answers each request that is identical to a previous request, within the time-to-live of the original request, rather than hitting the LDAP server.

The Cache Time-To-Live is related to each single request. After a cache entry expires there is no automatic trigger for re-populating the information, as the cache is populated only by new requests, for example by opening the User administration page, or searching in a sharing dialog.

There is one trigger which is automatically triggered by a certain background job which keeps the user-group-mappings up-to-date, and always in cache.

Under normal circumstances, all users are never loaded at the same time. Typically the loading of users happens while page results are generated, in steps of 30 until the limit is reached or no results are left. For this to work on a Nextcloud-Server and LDAP-Server, Paged Results must be supported.

Nextcloud remembers which user belongs to which LDAP-configuration. That means each request will always be directed to the right server unless a user is defunct, for example due to a server migration or unreachable server. In this case the other servers will also receive the request.

Handling with backup server

When Nextcloud is not able to contact the main LDAP server, Nextcloud assumes it is offline and will not try to connect again for the time specified in Cache Time-To-Live. If you have a backup server configured Nextcloud will connect to it instead. When you have scheduled downtime, check Disable Main Server to avoid unnecessary connection attempts.