# Users # User management - [User management](/link/1010) - [Resetting a lost admin password](/link/1011) - [Resetting a user password](/link/1012) - [User password policy](/link/1013) - [Authentication](/link/1014) - [Two-factor authentication](/link/1015) - [User authentication with LDAP](/link/1016) - [LDAP user cleanup](/link/1017) - [The LDAP configuration API](/link/1018) - [User provisioning API](/link/1019) - [Profiles](/link/1022) - [User authentication with OpenID Connect](/link/1023) # User management On the User management page of your Nextcloud Web UI you can: - Create new users - View all of your users in a single scrolling window - Filter users by group - See what groups they belong to - Edit their full names and passwords - See their data storage locations - View and set quotas - Create and edit their email addresses - Send an automatic email notification to new users - Disable and enable users - Delete them with a single click The default view displays basic information about your users. ![](https://docs.cocobook.com/uploads/images/gallery/2026-10/user-config.png) The group filters on the left sidebar let you quickly filter users by their group memberships and create new groups. ![](https://docs.cocobook.com/uploads/images/gallery/2026-10/user-config-groups.png) > **提示** > > User counts for certain groups, such as "All accounts," may not be visible when using certain backends such as LDAP/AD/SAML. Click the gear icon on the lower left sidebar to set a default storage quota, and to display additional fields: **Show storage location, Show last log in, Show user backend, Send email to new users,** and **Show email address**. ![](https://docs.cocobook.com/uploads/images/gallery/2026-10/user-config-settings.png) User accounts have the following properties: *Login Name (Username)* The unique ID of a Nextcloud user, which cannot be changed. *Full Name* The user's display name that appears on file shares, the Nextcloud Web interface, and emails. Admins and users may change the Full Name at any time. If the Full Name is not set, it defaults to the login name. *Password* The admin sets the new user's initial password. Both the user and the admin can change the user's password at any time. *Email address* You can set an email address for a user. This address can be used when you first set up an account so the user receives an email asking them to create a password if none is provided. This address can also be used for password reset requests. *Groups* You may create groups and assign group memberships to users. By default, new users are not assigned to any groups. *Group Admin* Group admins are granted administrative privileges for specific groups and can create and remove users from their groups. This means they can modify the username, password, email, quota, etc., of members of the group. Group admins are not allowed to add existing users to their groups. *Quota* The maximum disk space assigned to each user. Any user who exceeds the quota cannot upload or sync data. You have the option to include external storage in user quotas. *Manager* Every user can have one organizational manager. The manager property goes into the system address book card of the user and is used for the Contacts app's organization chart, for example. Setting a manager does **not** change any authorization level of the user or their manager. ## Creating a new user To create a user account: - Enter the new user's **Login Name** and their initial **Password** - Optionally, assign **Groups** memberships - Click the **Create** button ![](https://docs.cocobook.com/uploads/images/gallery/2026-10/user-config-new-user.png) Login names may contain letters (a-z, A-Z), numbers (0-9), dashes (-), underscores (\_), periods (.), spaces ( ), and at signs (@). After creating the user, you may fill in their **Full Name** if it is different from the login name, or leave it for the user to complete. If you have checked **Send email to new user** in the control panel on the lower left sidebar, you may also enter the new user's email address, and Nextcloud will automatically send them a notification with their new login information. You may edit this email using the email template editor on your Admin page (see [Email](/link/929)). If you check the **Send email to new user** checkbox, you can leave the **Password** field empty. The user will receive an activation email to set their own password. ## Reset a user's password You cannot recover a user's password, but you can set a new one: - Hover your cursor over the user's **Password** field - Click on the **pencil icon** - Enter the user's new password in the password field, and remember to provide the user with their password If you have encryption enabled, there are special considerations for user password resets. Please see [Server-side Encryption](/link/966). ## Renaming a user Each Nextcloud user has two names: a unique **Login Name** used for authentication, and a **Full Name**, which is their display name. You can edit the display name of a user, but you cannot change the login name of any user. To set or change a user's display name: - Hover your cursor over the user's **Full Name** field - Click on the **pencil icon** - Enter the user's new display name ## Granting administrator privileges to a user Nextcloud has two types of administrators: **Super Administrators** and **Group Administrators**. Group administrators have the rights to create, edit, and delete users in their assigned groups. Group administrators cannot access system settings or add or modify users in groups for which they are not **Group Administrators**. Use the dropdown menus in the **Group Admin** column to assign group admin privileges. ![](https://docs.cocobook.com/uploads/images/gallery/2026-10/user-config-group-admin.png) **Super Administrators** have full rights on your Nextcloud server and can access and modify all settings. To assign the **Super Administrators** role to a user, simply add them to the `admin` group. ## Managing groups You can assign new users to groups when you create them and create new groups when you create new users. You may also use the **Add Group** button at the top of the left pane to create new groups. New group members will immediately have access to file shares that belong to their new groups. ## Setting storage quotas Click the gear icon on the lower left pane to set a default storage quota. This is automatically applied to new users. You may assign a different quota to any user by selecting from the **Quota** dropdown, selecting either a preset value or entering a custom value. When you create custom quotas, use the standard abbreviations for your storage values, such as 500 MB, 5 GB, 5 TB, and so on. You now have a configurable option in `config.php` that controls whether external storage is counted against users' quotas. This is still experimental and may not work as expected. The default is to not count external storage as part of user storage quotas. If you prefer to include it, then change the default `false` to `true`. 'quota_include_external_storage' => false, > **提示** > > If an external storage is defined as root, the quota will not be calculable and will be **ignored**. Metadata (such as thumbnails, temporary files, and encryption keys) takes up about 10% of disk space but is not counted against user quotas. Users can check their used and available space on their Personal pages. Only files that originate with users count against their quotas, and not files shared with them that originate from other users. For example, if you upload files to a different user's share, those files count against your quota. If you re-share a file that another user shared with you, that file does not count against your quota, but the originating user's. Encrypted files are a little larger than unencrypted files; the unencrypted size is calculated against the user's quota. Deleted files that are still in the trash bin do not count against quotas. The trash bin is set at 50% of quota. Deleted file aging is set at 30 days. When deleted files exceed 50% of quota, the oldest files are removed until the total is below 50%. When version control is enabled, older file versions are not counted against quotas. When a user creates a public share via URL and allows uploads, any uploaded files count against that user's quota. ## Disable and enable users ![](https://docs.cocobook.com/uploads/images/gallery/2026-10/user-config-actions.png) Sometimes you may want to disable a user without permanently deleting their settings and files. The user can be activated again at any time, without data loss. Hover your cursor over their name on the **Users** page until the "..." menu icon appears at the far right. After clicking on it, you will see the **Disable** option. The user will no longer be able to access their Nextcloud until you enable them again. Also, all external shares, via public link or email, will not be accessible. Internal shares will still be working, so other users on Nextcloud can continue working. If you wish for internal shares to be disabled as well when a user is disabled, activate the configuration option files_sharing:hide_disabled_user_shares: occ config:app:set files_sharing hide_disabled_user_shares --value yes You will find all disabled users in the **disabled** section on the left pane. Enabling users is as easy as disabling them. Just click on the "..." menu, and select **Enable**. ## Deleting users ![](https://docs.cocobook.com/uploads/images/gallery/2026-10/user-config-actions.png) Deleting a user is easy: hover your cursor over their name on the **Users** page until the "..." menu icon appears at the far right. After clicking on it, you will see the **Delete** option. Clicking on it deletes a user with all their data immediately. You'll see an undo button at the top of the page, which remains for a few seconds. When the undo button is gone, you cannot recover the deleted user. All of the files owned by the user are deleted as well, including all files they have shared. If you need to preserve the user's files and shares, you must first download them from your Nextcloud Files page, which compresses them into a zip file, or use a sync client to copy them to your local computer. See [File Sharing](/link/951) to learn how to create persistent file shares that survive user deletions. ## Disabling the "Your email address \[...\] was changed" email If an email address of a user is changed by an admin, then it triggers an email to the user that states "Your email address on \[URL\] was changed by an administrator.". In some cases this should not be triggered, because it was a normal maintenance change. To disable this specific email the appconfig option `disable_email.email_address_changed_by_admin` can be set to `yes`: occ config:app:set settings disable_activity.email_address_changed_by_admin --value yes To disable this behaviour change it to any other value or delete the app config: occ config:app:delete settings disable_activity.email_address_changed_by_admin # Resetting a lost admin password The normal ways to recover a lost password are: 1. Click the password reset link on the login screen; this appears after a failed login attempt. This works only if you have entered your email address on your Personal page in the Nextcloud Web interface, so that the Nextcloud server can email a reset link to you. 2. Ask another Nextcloud server admin to reset it for you. If neither of these is an option, then you have a third option, and that is using the `occ` command. See [Using the occ command](/link/937) to learn more about using the `occ` command. $ sudo -E -u www-data php /var/www/nextcloud/occ user:resetpassword admin Enter a new password: Confirm the new password: Successfully reset password for admin If your Nextcloud username is not `admin`, then substitute your Nextcloud username. # Resetting a user password The Nextcloud login screen displays a **Wrong password. Reset it?** message after a user enters an incorrect password, and then Nextcloud automatically resets their password. However, if you are using a read-only authentication backend such as LDAP or Active Directory, this will not work. In this case you may specify a custom URL in your `config.php` file to direct your user to a server that can handle an automatic reset: 'lost_password_link' => 'https://example.org/link/to/password/reset', # User password policy A password policy is a set of rules designed to enhance computer security by encouraging users to employ strong passwords and use them properly. In the security-section of your administrator-settings you can configure - a minimal length of a password. Default is 10 characters. - a password history - a password expiration period - a lockout policy - to forbid common passwords like 'password' or 'login'. - to enforce upper and lower case characters - to enforce numeric characters - to enforce special characters like ! or : - to check the password against the list of breached passwords from haveibeenpwnd.com (hashed check via haveibeenpwnd.com-API) ![](https://docs.cocobook.com/uploads/images/gallery/2026-10/user-password-policy-configuration-app.png) # Authentication ## App passwords App passwords allow users to authenticate multiple client applications against their Nextcloud account without giving the application the login password. App passwords are mandatory for accounts with [two-factor authentication](/link/1015) enabled. Some clients support *remote wipe*, which makes the connected application delete its local data. ### Automated clean-up > *New in version 30* Nextcloud will delete unused passwords. Passwords set for *remote wipe* are deleted after 60 days of no usage. App passwords of client applications are deleted after 365 days of no usage. The time spans can be overwritten with configuration: sudo -E -u www-data php occ config:system:set token_auth_wipe_token_retention --type=int --value 2592000 # 60*60*24*30 - 30 days sudo -E -u www-data php occ config:system:set token_auth_token_retention --type=int --value 63072000 # 60*60*24*365*2 - 2 years Values are set in **seconds**. # Two-factor authentication Two-factor authentication adds an additional layer of security to user accounts. In order to log in on an account when two-factor authentication (2FA) is enabled, you must provide both the login password and another factor. To use 2FA two things must happen: - At least one 2FA provider must be enabled by the administrator. - A user must activate 2FA on their account (or) the administrator must enforce the use of 2FA. Both steps are described below. ## Enabling two-factor authentication 2FA in Nextcloud is pluggable, meaning that various 2FA providers can be used to support different types of factors. Three providers are automatically installed (but may need to be enabled): **Two-Factor TOTP Provider** - A 2FA factor provider that enables the use of a [TOTP](https://en.wikipedia.org/wiki/Time-based_One-time_Password_Algorithm) (RFC 6238) app installed on a phone (or other device) to be used as the secondary factor - Compatible with any RFC 6238 compliant TOTP client app (such as [Aegis](https://github.com/beemdevelopment/aegis) or Google Authenticator). - Disabled by default. Go to *Apps-\>Disabled apps* and find *Two-Factor TOTP Provider* to enable this factor. **Two-Factor Authentication via Nextcloud notifications** - A 2FA factor provider that enables the use of a logged in device as the secondary factor. - Disabled by default. Go to *Apps-\>Disabled apps* and find *Two-Factor Authentication via Nextcloud notification* to enable this factor. **Two-Factor Backup Codes** - A special 2FA factor provider enables users to generate backup codes. - Facilitates recovery of access if a 2FA device is unavailable (i.e. gets stolen or is not working). - Generates ten backup codes (which can, of course, only be used once). - Always enabled. Other 2FA providers may be found in the App Store. ![](https://docs.cocobook.com/uploads/images/gallery/2026-10/2fa-app-install.png) Developers can also [implement new two-factor provider apps](https://docs.nextcloud.com/server/latest/developer_manual/digging_deeper/two-factor-provider.html). ## Enforcing two-factor authentication By default 2FA is *optional*, hence users are given the choice whether to enable it for their account [under their personal settings](/link/880). Admins may, however, enforce the use of 2FA. Enforcement is possible system-wide (all users) or for selected groups only. Select groups can also be excluded from 2FA requirements. These settings can be found under *Administration Settings-\>Security*. ![](https://docs.cocobook.com/uploads/images/gallery/2026-10/2fa-admin-settings.png) When groups are selected/excluded, they use the following logic to determine if a user has 2FA enforced: - If no groups are selected, 2FA is enabled for everyone except members of the excluded groups - If groups are selected, 2FA is enabled for all members of these. If a user is both in a selected *and* excluded group, the selected takes precedence and 2FA is enforced. ## Provider removal Nextcloud keeps records about the enabled two-factor authentication providers of every user. If a provider is simply removed/[disabled](/link/938), Nextcloud will still consider the provider active for the user at login and show a warning like *Could not load at least one of your enabled two-factor auth methods*. The associations of removed providers can be cleaned up via [occ](/link/937): sudo -E -u www-data php occ twofactorauth:cleanup > **注意** > > This operation is irreversible. Only run it for providers you do not intend to enable again as then you have to setup the configuration for all users from scratch. ## Disabling two-factor authentication Two-factor providers can be disabled via [occ](/link/937): sudo -E -u www-data php occ twofactorauth:disable This can be useful if the user forgot or lost their second factor. Afterwards users are free to enable this provider again via their personal settings. > **提示** > > This operation has to be supported by the provider. If this support is missing, Nextcloud will abort and show an error. It is also possible to check the current two-factor user status via [occ](/link/937): sudo -E -u www-data php occ twofactorauth:state # User authentication with LDAP Nextcloud ships with an LDAP application to allow LDAP users (including Active Directory) to appear in your Nextcloud user listings. These users will authenticate to Nextcloud with their LDAP credentials, so you don't have to create separate Nextcloud user accounts for them. You will manage their Nextcloud group memberships, quotas, and sharing permissions just like any other Nextcloud user. > **提示** > > The PHP LDAP module is required; this is supplied by `php-ldap` on most distributions. The LDAP application supports: - LDAP group support - File sharing with Nextcloud users and groups - Access via WebDAV and Nextcloud Desktop Client - Versioning, external Storage and all other Nextcloud features - Seamless connectivity to Active Directory, with no extra configuration required - Support for primary groups in Active Directory - Auto-detection of LDAP attributes such as base DN, email, and the LDAP server port number - Only read access to your LDAP (edit or delete of users on your LDAP is not supported) - Optional: Allow users to change their LDAP password from Nextcloud > **提示** > > A non-blocking or correctly configured SELinux setup is needed for the LDAP backend to work. Please refer to the [SELinux configuration](/link/901). ## Configuration First enable the `LDAP user and group backend` app on the Apps page in Nextcloud. Then go to your Admin page to configure it. The LDAP configuration panel has four tabs. A correctly completed first tab ("Server") is mandatory to access the other tabs. A green indicator lights when the configuration is correct. Hover your cursor over the fields to see some pop-up tooltips. ### Server tab Start with the Server tab. You may configure multiple servers if you have them. > **提示** > > Do not configure any failover LDAP hosts here. See [Advanced settings](/link/1016) 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. ![LDAP wizard, server tab](https://docs.cocobook.com/uploads/images/gallery/2026-10/ldap-wizard-1-server.png) 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. ![User filter](https://docs.cocobook.com/uploads/images/gallery/2026-10/ldap-wizard-2-user.png) 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. ![Login filter](https://docs.cocobook.com/uploads/images/gallery/2026-10/ldap-wizard-3-login.png) 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. ![Group filter](https://docs.cocobook.com/uploads/images/gallery/2026-10/ldap-wizard-4-group.png) 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. ## Advanced settings The LDAP Advanced Setting section contains options that are not needed for a working connection. This provides controls to disable the current configuration, configure replica hosts, and various performance-enhancing options. The Advanced Settings are structured into four parts: - Connection Settings - Directory Settings - Special Attributes - User Profile Attributes ### Connection settings ![Advanced settings](https://docs.cocobook.com/uploads/images/gallery/2026-10/ldap-advanced-1-connection.png) 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\](). 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 ![Directory settings.](https://docs.cocobook.com/uploads/images/gallery/2026-10/ldap-advanced-2-directory.png) 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](/link/1017). 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 ![Special Attributes.](https://docs.cocobook.com/uploads/images/gallery/2026-10/ldap-advanced-3-attributes.png) 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* > **注意** > > 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* > **注意** > > 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 ![User Profile Attributes.](https://docs.cocobook.com/uploads/images/gallery/2026-10/ldap-advanced-4-attributes.png) After configuring those attributes, the User Profile data will be overwritten with the corresponding 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 ` the users data from LDAP will be displayed and the profile gets updated. To get the correct `` value for any user you can use `php occ user:list`. > **提示** > > 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* > **提示** > > 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 user's biography (short description). 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](https://ldapwiki.com/wiki/Wiki.jsp?page=GeneralizedTime) - `YYYY-MM-DD` - `YYYYMMDD` ## Expert settings ![Expert settings.](https://docs.cocobook.com/uploads/images/gallery/2026-10/ldap-expert.png) In the Expert Settings fundamental behavior can be adjusted to your needs. The configuration should be well-tested before starting production use. Internal Username: The internal username is the identifier in Nextcloud for LDAP users. By default it will be created from the UUID attribute. The UUID attribute ensures that the username is unique, and that characters do not need to be converted. Only these characters are allowed: `[a-zA-Z0-9_.@-]`. Other characters are replaced with their ASCII equivalents, or are simply omitted. The LDAP backend ensures that there are no duplicate internal usernames in Nextcloud, i.e. that it is checking all other activated user backends (including local Nextcloud users). On collisions a random number (between 1000 and 9999) will be attached to the retrieved value. For example, if "alice" exists, the next username may be "alice_1337". The internal username is the default name for the user home folder in Nextcloud. It is also a part of remote URLs, for instance for all \*DAV services. You can override all of this with the Internal Username setting. Leave it empty for default behavior. Changes will affect only newly mapped LDAP users. When configuring this, be aware that the username in Nextcloud is considered immutable and cannot be changed afterwards. This can cause issues when using an attribute that might change, e.g. the email address of a user that will get changed during name change. - Example: *uid* Override UUID detection By default, Nextcloud auto-detects the UUID attribute. The UUID attribute is used to uniquely identify LDAP users and groups. The internal username will be created based on the UUID, if not specified otherwise. You can override the setting and pass an attribute of your choice. You must make sure that the attribute of your choice can be fetched for both users and groups and it is unique. Leave it empty for default behavior. Changes will have effect only on newly mapped LDAP users and groups. It also will have effect when a user's or group's DN changes and an old UUID was cached, which will result in a new user. Because of this, the setting should be applied before putting Nextcloud in production use and clearing the bindings (see the `User and Group Mapping` section below). - Example: *cn* Username-LDAP User Mapping Nextcloud uses usernames as keys to store and assign data. In order to precisely identify and recognize users, each LDAP user will have a internal username in Nextcloud. This requires a mapping from Nextcloud username to LDAP user. The created username is mapped to the UUID of the LDAP user. Additionally the DN is cached as well to reduce LDAP interaction, but it is not used for identification. If the DN changes, the change will be detected by Nextcloud by checking the UUID value. The same is valid for groups. The internal Nextcloud name is used all over in Nextcloud. Clearing the Mappings will have leftovers everywhere. Never clear the mappings in a production environment, but only in a testing or experimental server. > **注意** > > Clearing the Mappings is not configuration sensitive, it affects all LDAP configurations! ## Testing the configuration > **注意** > > Before testing, make sure the **Configuration Active** checkbox is enabled. It is disabled by default and will cause authentication to fail with a "wrong password" error even if all other settings are correct. Nextcloud only enables it automatically after a successful test connection. The **Test Configuration** button checks the values as currently given in the input fields. You do not need to save before testing. By clicking on the button, Nextcloud will try to bind to the Nextcloud server using the settings currently given in the input fields. If the binding fails you'll see a yellow banner with the error message "The configuration is invalid. Please have a look at the logs for further details." When the configuration test reports success, save your settings and check if the users and groups are fetched correctly on the Users page. ## Additional configuration options via occ Few configuration settings can only be set on command line via `occ`. ### Background sync interval The LDAP backend updates user attributes (email, quota, avatar, and others) on every login, on first detection of a new user, and periodically via a background job. The background job recalculates its run interval after each cycle. The goal is to process every known LDAP user approximately once per day. The interval is derived from the total number of mapped users and the smallest configured LDAP paging size, then clamped to a minimum of 30 minutes and a maximum of 12 hours. ### 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] [--] 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 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 "" > **提示** > > 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. ## Nextcloud avatar integration Nextcloud supports user profile pictures, which are also called avatars. If a user has a photo stored in the *jpegPhoto* or *thumbnailPhoto* attribute on your LDAP server, it will be used as their avatar. In this case the user cannot alter their avatar (on their Personal page) as it must be changed in LDAP. *jpegPhoto* is preferred over *thumbnailPhoto*. ![Profile picture fetched from LDAP.](https://docs.cocobook.com/uploads/images/gallery/2026-10/ldap-fetched-avatar.png) If the *jpegPhoto* or *thumbnailPhoto* attribute is not set or empty, then users can upload and manage their avatars on their Nextcloud Personal pages. Avatars managed in Nextcloud are not stored in LDAP. The *jpegPhoto* or *thumbnailPhoto* attribute is fetched once a day to make sure the current photo from LDAP is used in Nextcloud. LDAP avatars override Nextcloud avatars, and when an LDAP avatar is deleted then the most recent Nextcloud avatar replaces it. Photos served from LDAP are automatically cropped and resized in Nextcloud. This affects only the presentation, and the original image is not changed. ### 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`. ## Troubleshooting, tips and tricks ### 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](https://serverfault.com/questions/167371/what-permissions-are-required-for-enumerating-users-groups-in-active-directory/167401#167401). ### 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. ## Nextcloud LDAP internals Some parts of how the LDAP backend works are described here. ### 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](/link/926)). 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. ## Note When a LDAP object's name or surname, that is display name attribute, by default "displayname", is left empty, Nextcloud will treat it as an empty object, therefore no results from this user or AD-Object will be shown to avoid gathering of technical accounts. # LDAP user cleanup LDAP User Cleanup is a new feature in the `LDAP user and group backend` application. LDAP User Cleanup is a background process that automatically searches the Nextcloud LDAP mappings table, and verifies if the LDAP users are still available. Any users that are not available are marked as `deleted` in the `oc_preferences` database table. Then you can run a command to display this table, displaying only the users marked as `deleted`, and then you have the option of removing their data from your Nextcloud data directory. These items are removed upon cleanup: - Local Nextcloud group assignments - User preferences (DB table `oc_preferences`) - User's Nextcloud home folder - User's corresponding entry in `oc_storages` There are two prerequisites for LDAP User Cleanup to operate: 1. Set `ldapUserCleanupInterval` in `config.php` to your desired check interval in minutes. The default is 51 minutes. 2. All configured LDAP connections are enabled and operating correctly. As users can exist on multiple LDAP servers, you want to be sure that all of your LDAP servers are available so that a user on a temporarily disconnected LDAP server is not marked as `deleted`. The background process examines 50 users at a time, and runs at the interval you configured with `ldapUserCleanupInterval`. For example, if you have 200 LDAP users and your `ldapUserCleanupInterval` is 20 minutes, the process will examine the first 50 users, then 20 minutes later the next 50 users, and 20 minutes later the next 50, and so on. The amount of users to check can be set to a custom value via occ command. The following example sets it to 300: `sudo -E -u www-data php occ config:app:set --value=300 user_ldap cleanUpJobChunkSize` There are two `occ` commands to use for examining a table of users marked as deleted, and then manually deleting them. The `occ` command is in your Nextcloud directory, for example `/var/www/nextcloud/occ`, and it must be run as your HTTP user. To learn more about `occ`, see [Using the occ command](/link/937). These examples are for Ubuntu Linux: 1. `sudo -E -u www-data php occ ldap:show-remnants` displays a table with all users that have been marked as deleted, and their LDAP data. 2. `sudo -E -u www-data php occ user:delete [user]` removes the user's data from the Nextcloud data directory. This example shows what the table of users marked as `deleted` looks like: $ sudo -E -u www-data php occ ldap:show-remnants +-----------------+-----------------+------------------+--------------------------------------+ | Nextcloud name | Display Name | LDAP UID | LDAP DN | +-----------------+-----------------+------------------+--------------------------------------+ | aaliyah_brown | aaliyah brown | aaliyah_brown | uid=aaliyah_brown,ou=people,dc=com | | aaliyah_hammes | aaliyah hammes | aaliyah_hammes | uid=aaliyah_hammes,ou=people,dc=com | | aaliyah_johnston| aaliyah johnston| aaliyah_johnston | uid=aaliyah_johnston,ou=people,dc=com| | aaliyah_kunze | aaliyah kunze | aaliyah_kunze | uid=aaliyah_kunze,ou=people,dc=com | +-----------------+-----------------+------------------+--------------------------------------+ Following flags can be specified additionally: - `--short-date`: formats the dates for `Last login` and `Detected on` in a short Y-m-d format (e.g. 2019-01-14) - `--json`: instead of a table, the output is json-encoded. This makes it easy to process the data programmatically. Then you can run `sudo -E -u www-data php occ user:delete aaliyah_brown` to delete user aaliyah_brown. You must use the user's Nextcloud name. ## Deleting local Nextcloud users You may also use `occ user:delete [user]` to remove a local Nextcloud user; this removes their user account and their data. # 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 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 $ 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 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 $ 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 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 $ 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 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 | | ldapUserAvatarRule | rw | no | Specify the avatar integration behavior, possible values: "default", "none", "" | | 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 | | ldapConnectionTimeout | rw | no | Set the `LDAP_OPT_NETWORK_TIMEOUT` connection options. Default to 15 sec. | # User provisioning API The Provisioning API application enables a set of APIs that external systems can use to create, edit, delete and query user attributes, query, set and remove groups, set quota and query total storage used in Nextcloud. Group admin users can also query Nextcloud and perform the same functions as an admin for groups they manage. HTTP requests can be used via a Basic Auth header to perform any of the functions listed above. The Provisioning API app is enabled by default. The base URL for all calls to the Provisioning API is `https://cloud.example.com/ocs/v1.php/cloud`. All calls to OCS endpoints require the `OCS-APIRequest` header to be set to `true`. All POST requests require the `Content-Type: application/x-www-form-urlencoded` header. (Note: Some libraries like cURL set this header automatically, others require setting the header explicitly.) - [Instruction set for users](/link/1020) - [Instruction set for groups](/link/1021) # Instruction set for users ## Add a new user Create a new user on the Nextcloud server. Authentication is done by sending a basic HTTP authentication header. **Syntax: ocs/v1.php/cloud/users** - HTTP method: POST - POST argument: userid - string, the required username for the new user - POST argument: password - string, the password for the new user, leave empty to send welcome mail - POST argument: displayName - string, the display name for the new user - POST argument: email - string, the email for the new user, required if password empty - POST argument: groups - array, the groups for the new user - POST argument: subadmin - array, the groups in which the new user is subadmin - POST argument: quota - string, quota for the new user - POST argument: language - string, language for the new user Status codes: - 101 - invalid argument - 102 - user already exists - 103 - cannot create sub-admins for admin group - 104 - group does not exist - 105 - insufficient privileges for group - 106 - no group specified (required for sub-admins) - 107 - hint exceptions - 108 - an email address is required, to send a password link to the user. - 109 - sub-admin group does not exist - 110 - required email address was not provided - 111 - could not create non-existing user ID ### Example $ curl -X POST http://admin:secret@example.com/ocs/v1.php/cloud/users -d userid="Frank" -d password="frankspassword" -H "OCS-APIRequest: true" - Creates the user `Frank` with password `frankspassword` - optionally groups can be specified by one or more `groups[]` query parameters: `URL -d groups[]="admin" -D groups[]="Team1"` ### XML output ``` xml ok 100 ``` ## Search/get users Retrieves a list of users from the Nextcloud server. Authentication is done by sending a Basic HTTP Authorization header. **Syntax: ocs/v1.php/cloud/users** - HTTP method: GET - url arguments: search - string, optional search string - url arguments: limit - int, optional limit value - url arguments: offset - int, optional offset value Status codes: - 100 - successful ### Example $ curl -X GET http://admin:secret@example.com/ocs/v1.php/cloud/users?search=Frank -H "OCS-APIRequest: true" - Returns list of users matching the search string. ### XML output ``` xml 100 ok Frank ``` ## Get data of a single user Retrieves information about a single user. Authentication is done by sending a Basic HTTP Authorization header. **Syntax: ocs/v1.php/cloud/users/{userid}** - HTTP method: GET Status codes: - 100 - successful ### Example $ curl -X GET http://admin:secret@example.com/ocs/v1.php/cloud/users/Frank -H "OCS-APIRequest: true" - Returns information on the user `Frank` ### XML output ``` xml 100 ok true Frank 0 frank@example.org Frank K. Frank K. 0123 / 456 789
Foobar 12, 12345 Town
https://nextcloud.com Nextcloud group1 group2 ``` ## Edit data of a single user Edits attributes related to a user. Users are able to edit email, displayname and password; admins can also edit the quota value. Further restrictions may apply, check the [List of editable data fields](#bkmrk-list-of-editable-dat) endpoint. Authentication is done by sending a Basic HTTP Authorization header. **Syntax: ocs/v1.php/cloud/users/{userid}** - HTTP method: PUT - PUT argument: key, the field to edit: - email - quota - displayname - display (**deprecated** use displayname instead) - phone - address - website - twitter - password - PUT argument: value, the new value for the field Status codes: - 101 - invalid argument - 107 - password policy (hint exception) - 112 - Setting the password is not supported by the users backend - 113 - editing field not allowed / field doesn’t exist ### Examples $ curl -X PUT http://admin:secret@example.com/ocs/v1.php/cloud/users/Frank -d key="email" -d value="franksnewemail@example.org" -H "OCS-APIRequest: true" - Updates the email address for the user `Frank` $ curl -X PUT http://admin:secret@example.com/ocs/v1.php/cloud/users/Frank -d key="quota" -d value="100MB" -H "OCS-APIRequest: true" - Updates the quota for the user `Frank` ### XML output ``` xml 100 ok ``` ## List of editable data fields Edits attributes related to a user. Users are able to edit email, displayname and password; admins can also edit the quota value. Authentication is done by sending a Basic HTTP Authorization header. **Syntax: ocs/v1.php/cloud/user/fields** - HTTP method: GET Status codes: - 100 - successful ### Examples $ curl -X GET http://admin:secret@example.com/ocs/v1.php/cloud/user/fields -H "OCS-APIRequest: true" - Gets the list of fields ### XML output ``` xml ok 100 OK displayname email phone address website twitter ``` ## Disable a user Disables a user on the Nextcloud server so that the user cannot login anymore. Authentication is done by sending a Basic HTTP Authorization header. **Syntax: ocs/v1.php/cloud/users/{userid}/disable** - HTTP method: PUT Statuscodes: - 100 - successful - 101 - failure ### Example $ curl -X PUT http://admin:secret@example.com/ocs/v1.php/cloud/users/Frank/disable -H "OCS-APIRequest: true" - Disables the user `Frank` ### XML output ``` xml ok 100 ``` ## Enable a user Enables a user on the Nextcloud server so that the user can login again. Authentication is done by sending a Basic HTTP Authorization header. **Syntax: ocs/v1.php/cloud/users/{userid}/enable** - HTTP method: PUT Statuscodes: - 100 - successful - 101 - failure ### Example $ curl -X PUT http://admin:secret@example.com/ocs/v1.php/cloud/users/Frank/enable -H "OCS-APIRequest: true" - Enables the user `Frank` ### XML output ``` xml ok 100 ``` ## Delete a user Deletes a user from the Nextcloud server. Authentication is done by sending a Basic HTTP Authorization header. **Syntax: ocs/v1.php/cloud/users/{userid}** - HTTP method: DELETE Statuscodes: - 100 - successful - 101 - failure ### Example $ curl -X DELETE http://admin:secret@example.com/ocs/v1.php/cloud/users/Frank -H "OCS-APIRequest: true" - Deletes the user `Frank` ### XML output ``` xml 100 ok ``` ## Get user's groups Retrieves a list of groups the specified user is a member of. Authentication is done by sending a Basic HTTP Authorization header. **Syntax: ocs/v1.php/cloud/users/{userid}/groups** - HTTP method: GET Status codes: - 100 - successful ### Example $ curl -X GET http://admin:secret@example.com/ocs/v1.php/cloud/users/Frank/groups -H "OCS-APIRequest: true" - Retrieves a list of groups of which `Frank` is a member ### XML output ``` xml 100 ok admin group1 ``` ## Add user to group Adds the specified user to the specified group. Authentication is done by sending a Basic HTTP Authorization header. **Syntax: ocs/v1.php/cloud/users/{userid}/groups** - HTTP method: POST - POST argument: groupid, string - the group to add the user to Status codes: - 100 - successful - 101 - no group specified - 102 - group does not exist - 103 - user does not exist - 104 - insufficient privileges - 105 - failed to add user to group ### Example $ curl -X POST http://admin:secret@example.com/ocs/v1.php/cloud/users/Frank/groups -d groupid="newgroup" -H "OCS-APIRequest: true" - Adds the user `Frank` to the group `newgroup` ### XML output ``` xml 100 ok ``` ## Remove user from group Removes the specified user from the specified group. Authentication is done by sending a Basic HTTP Authorization header. **Syntax: ocs/v1.php/cloud/users/{userid}/groups** - HTTP method: DELETE - DELETE argument: groupid, string - the group to remove the user from Status codes: - 100 - successful - 101 - no group specified - 102 - group does not exist - 103 - user does not exist - 104 - insufficient privileges - 105 - failed to remove user from group ### Example $ curl -X DELETE http://admin:secret@example.com/ocs/v1.php/cloud/users/Frank/groups -d groupid="newgroup" -H "OCS-APIRequest: true" - Removes the user `Frank` from the group `newgroup` ### XML output ``` xml 100 ok ``` ## Promote user to subadmin Makes a user the subadmin of a group. Authentication is done by sending a Basic HTTP Authorization header. **Syntax: ocs/v1.php/cloud/users/{userid}/subadmins** - HTTP method: POST - POST argument: groupid, string - the group of which to make the user a subadmin Status codes: - 100 - successful - 101 - user does not exist - 102 - group does not exist - 103 - unknown failure ### Example $ curl -X POST https://admin:secret@example.com/ocs/v1.php/cloud/users/Frank/subadmins -d groupid="group" -H "OCS-APIRequest: true" - Makes the user `Frank` a subadmin of the `group` group ### XML output ``` xml 100 ok ``` ## Demote user from subadmin Removes the subadmin rights for the user specified from the group specified. Authentication is done by sending a Basic HTTP Authorization header. **Syntax: ocs/v1.php/cloud/users/{userid}/subadmins** - HTTP method: DELETE - DELETE argument: groupid, string - the group from which to remove the user's subadmin rights Status codes: - 100 - successful - 101 - user does not exist - 102 - user is not a subadmin of the group / group does not exist - 103 - unknown failure ### Example $ curl -X DELETE https://admin:secret@example.com/ocs/v1.php/cloud/users/Frank/subadmins -d groupid="oldgroup" -H "OCS-APIRequest: true" - Removes `Frank's` subadmin rights from the `oldgroup` group ### XML output ``` xml 100 ok ``` ## Get user's subadmin groups Returns the groups in which the user is a subadmin. Authentication is done by sending a Basic HTTP Authorization header. **Syntax: ocs/v1.php/cloud/users/{userid}/subadmins** - HTTP method: GET Status codes: - 100 - successful - 101 - user does not exist - 102 - unknown failure ### Example $ curl -X GET https://admin:secret@example.com/ocs/v1.php/cloud/users/Frank/subadmins -H "OCS-APIRequest: true" - Returns the groups of which `Frank` is a subadmin ### XML output ``` xml ok 100 testgroup ``` ## Resend the welcome email The request to this endpoint triggers the welcome email for this user again. **Syntax: ocs/v1.php/cloud/users/{userid}/welcome** - HTTP method: POST Status codes: - 100 - successful - 101 - email address not available - 102 - sending email failed ### Example $ curl -X POST https://admin:secret@example.com/ocs/v1.php/cloud/users/Frank/welcome -H "OCS-APIRequest: true" - Sends the welcome email to `Frank` ### XML output ``` xml ok 100 ``` # Instruction set for groups ## Search/get groups Retrieves a list of groups from the Nextcloud server. Authentication is done by sending a Basic HTTP Authorization header. **Syntax: ocs/v1.php/cloud/groups** - HTTP method: GET - url arguments: search - string, optional search string - url arguments: limit - int, optional limit value - url arguments: offset - int, optional offset value Status codes: - 100 - successful ### Example $ curl -X GET http://admin:secret@example.com/ocs/v1.php/cloud/groups?search=adm -H "OCS-APIRequest: true" - Returns list of groups matching the search string. ### XML output ``` xml 100 ok admin ``` ## Create a group Adds a new group. Authentication is done by sending a Basic HTTP Authorization header. **Syntax: ocs/v1.php/cloud/groups** - HTTP method: POST - POST argument: groupid, string - the new groups name Status codes: - 100 - successful - 101 - invalid input data - 102 - group already exists - 103 - failed to add the group ### Example $ curl -X POST http://admin:secret@example.com/ocs/v1.php/cloud/groups -d groupid="newgroup" -H "OCS-APIRequest: true" - Adds a new group called `newgroup` ### XML output ``` xml 100 ok ``` ## Get members of a group Retrieves a list of group members. Authentication is done by sending a Basic HTTP Authorization header. **Syntax: ocs/v1.php/cloud/groups/{groupid}** - HTTP method: GET Status codes: - 100 - successful ### Example $ curl -X GET http://admin:secret@example.com/ocs/v1.php/cloud/groups/admin -H "OCS-APIRequest: true" - Returns a list of users in the `admin` group ### XML output ``` xml 100 ok Frank ``` ## Get subadmins of a group Returns subadmins of the group. Authentication is done by sending a Basic HTTP Authorization header. **Syntax: ocs/v1.php/cloud/groups/{groupid}/subadmins** - HTTP method: GET Status codes: - 100 - successful - 101 - group does not exist - 102 - unknown failure ### Example $ curl -X GET https://admin:secret@example.com/ocs/v1.php/cloud/groups/mygroup/subadmins -H "OCS-APIRequest: true" - Return the subadmins of the group: `mygroup` ### XML output ``` xml ok 100 Tom ``` ## Edit data of a single group Edits attributes related to a group. Authentication is done by sending a Basic HTTP Authorization header. **Syntax: ocs/v1.php/cloud/groups/{groupid}** - HTTP method: PUT - PUT argument: key, string - the field to edit: - displayname - PUT argument: value, string - the new value for the field Status codes: - 100 - successful - 101 - not supported by backend ### Examples $ curl -X PUT http://admin:secret@example.com/ocs/v1.php/cloud/groups/mygroup -d key="displayname" -d value="My Group Name" -H "OCS-APIRequest: true" - Updates the display name for the group `mygroup` ### XML output ``` xml 100 ok ``` ## Delete a group Removes a group. Authentication is done by sending a Basic HTTP Authorization header. **Syntax: ocs/v1.php/cloud/groups/{groupid}** - HTTP method: DELETE Status codes: - 100 - successful - 101 - group does not exist - 102 - failed to delete group ### Example $ curl -X DELETE http://admin:secret@example.com/ocs/v1.php/cloud/groups/mygroup -H "OCS-APIRequest: true" - Delete the group `mygroup` ### XML output ``` xml 100 ok ``` # Profiles The user profile displays information about an account. Profiles are enabled by default. Users can enable or disable their own profile in **Personal settings** under **Personal info**. As an administrator, you can: - set the default profile state for new users, and - disable profiles globally. Profile data can also be used by other features (for example the [system address book](/link/1036)), but what is exposed depends on privacy controls. > **提示** > > Profile visibility is layered. > > - **Profile enablement** determines if the profile feature is active at all. > - **Profile field visibility settings** control whether a field is shown. > - **Account property scopes** (for example `private`, `local`, `federated`, `published`) define the intended audience for each property. > - **Discovery restrictions** (for example sharing/autocomplete enumeration rules) can further reduce what other accounts can find or see. > > In short: effective visibility is the most restrictive result of all applicable controls. ## Configuration ### Set the profile default for new users In **Administration settings** -\> **Basic settings**, use the profile default toggle. ![](https://docs.cocobook.com/uploads/images/gallery/2026-10/profile-default-setting.png) You can also set this via `occ`: occ config:app:set settings profile_enabled_by_default --value="0" Use `--value="1"` to enable it by default again. See [Using the occ command](/link/937) for more `occ` usage details. ### Disable profiles globally To disable profile functionality for all users, add this to `config.php`: 'profile.enabled' => false, ## Profile field visibility settings Each profile field has its own **profile visibility** setting (stored per user in the profile configuration): - **Show to everyone** (`show`): visible to anyone, including unauthenticated visitors, *subject to the field's property scope*. - **Show to logged in accounts only** (`show_users_only`): visible only to authenticated users, *subject to the field's property scope*. - **Hide** (`hide`): never shown on profile surfaces regardless of property scope. These correspond to the visibility options in **Personal settings** -\> **Personal info** -\> **Edit your Profile visibility**. > **说明** > > Effective visibility is the most restrictive result of **both** controls: the profile visibility setting and the property scope. ### Defaults Most profile fields default to **Show to everyone**, while some contact-related fields (e.g. address, email, and phone) default to **Show to logged in accounts only**. Administrators should note that these defaults are independent from the default *property scopes* described below. Server configuration preset categories can override these initial defaults: - **Shared**, **School**, and **University**: address, email, and phone default to **Hide**. - **Private**, **Family**, and **Club**: email defaults to **Show to everyone**. - **Small**, **Medium**, and **Large**: email and phone default to **Show to everyone**. These are initial per-user profile-visibility values. Existing stored profile visibility settings are not changed merely by selecting or changing a preset. ## Property visibility scopes User properties (Display name, Address, Website, Role, etc.) have visibility scopes: Private, Local, Federated, Published. These scopes are evaluated per attribute. A profile being reachable does not imply that all its attributes are visible. The visibility scopes are: Private The most restrictive level. Data is hidden from public profiles, federation, and public lookup. On the local server, it is only shown in specific features and typically only to authenticated users who have a recognized relationship with the account owner (for example, as a known contact). Local Contact details visible on the local instance and in some public contexts where profile/account attributes are required (for example owner/uploader metadata). Not shared to federated servers and not published to the public lookup server. Federated Contact details visible on the local instance, in relevant public contexts, and on trusted federated servers. Published Contact details visible on the local instance, in relevant public contexts, on trusted federated servers, and published to the public lookup server. > **提示** > > **Public lookup server**: a public directory used to find users across Nextcloud instances. Only profile fields marked Published may be exposed there. > **提示** > > Not all fields are eligible for lookup publication even if their scope is set to `Published`. Some fields are intentionally never published (for example Biography, Headline, Organisation, Role, Birthdate). > > In other words: `Published` is necessary but not always sufficient for lookup publication. > **说明** > > A reachable profile does not mean all attributes are public. Each attribute is filtered by its own scope, and effective visibility can also depend on the consuming feature. > **说明** > > On profile surfaces, the effective visibility is the more restrictive of profile-visibility settings and property scope. ### Scope visibility matrix | Scope | User themself \[1\] | Other users on same local instance | Public contexts (feature-dependent) | Trusted federation | Public lookup server | |----|----|----|----|----|----| | Private | Yes | Limited on profile surfaces: authenticated + known-user relation required \[3\] | No | No | No | | Local | Yes | Yes | Yes (where applicable) \[2\] | No | No | | Federated | Yes | Yes | Yes (where applicable) \[2\] | Yes | No | | Published | Yes | Yes | Yes (where applicable) \[2\] | Yes | Yes | Notes: 1. Scope primarily governs exposure to others; owner access follows account/endpoint behavior. 2. Public-context visibility depends on feature path; scope alone does not guarantee display. 3. Some non-profile surfaces may exclude Private-scoped properties entirely (for example generated system address book cards), even for authenticated users. > **提示** > > The matrix describes **profile visibility behavior**. Other consuming features may apply additional filtering and may not expose Private-scoped properties at all. ### Known-user rule for `Private` scope For `Private` properties, Nextcloud may allow visibility on specific local feature paths only when the requester is considered a *known user* of the target user. In practical terms, this relation is derived by server-side *known-contact matching*. In current Nextcloud versions this matching is primarily established via **phone-number matching** (for example through the Talk mobile contact integration), and it is directional (e.g., Alice might be known to Bob, but Bob isn't necessarily known to Alice). Users are always known to themselves. ### What local users can see A common question is what one user can see about another user on the same instance. In general, profile visibility is controlled by each property's scope, but the exact UI/API surface depends on the consuming feature (for example profile page, share dialogs, search, mentions, Contacts, and other integrations). For local users on the same instance: - `Private`: not generally visible to all local users; visibility is restricted on applicable paths to authenticated users that satisfy the known-user relation and other feature constraints. - `Local`: visible on the local instance. - `Federated`: visible on the local instance (and also shared with trusted federated servers). - `Published`: visible on the local instance (and also federated + public lookup). > **提示** > > System address book exposure is scope-aware and context-aware: private/empty-scope properties are excluded from generated cards, and federated reads strip local-scoped properties. ### How to verify scope behavior Because effective visibility can vary by feature path, administrators should verify scope behavior in their own deployment. Recommended test procedure: 1. Create test users: - `alice` (target profile owner) - `bob` (authenticated local user) - `charlie` (second local user for control) 2. As `alice`, set distinct test values for profile fields and assign different scopes where possible (for example Private vs Local via the UI, and Federated/Published via API/administrative tooling if supported in your deployment). 3. Verify as `alice`: - Confirm owner-visible values as expected. 4. Verify as `bob` (authenticated local user): - Check the feature paths used in your instance (for example profile page, user card, share dialog, search, mentions, Contacts integrations). - Confirm `Local/Federated/Published` fields are visible where expected. - Confirm `Private` fields are visible only on paths that satisfy the known-user relation and other feature constraints. 5. Verify as unauthenticated user (private browser session): - Confirm only public-appropriate fields are visible. 6. Verify federation/publication behavior (if enabled): - From a trusted federated server, confirm Federated/Published behavior. - Confirm only Published fields are exposed to the public lookup server. 7. Re-test with a newly created user after changing `account_manager.default_property_scope`: - Confirm new defaults apply only to newly initialized accounts. - Confirm existing users retain stored scopes unless explicitly changed. ### Scope defaults and precedence Visibility is determined per property using this order: 1. **Server defaults** from `OC\Accounts\AccountManager::DEFAULT_SCOPES`. 2. **Administrator default override** via `account_manager.default_property_scope`. 3. **User-set value** in personal/profile settings (subject to server-side constraints). Practical implications: - Admin overrides in `account_manager.default_property_scope` are applied at account initialization and therefore affect **new users**. - Existing users keep already stored scopes unless changed explicitly. - `PROPERTY_DISPLAYNAME` and `PROPERTY_EMAIL` cannot be `Private`; server-side validation/enforcement requires at least `Local`. ### Default scope values (reference) Default values are defined in server code and may change over time. The authoritative source is the `DEFAULT_SCOPES` constant in `OC\Accounts\AccountManager`: [latest source](https://github.com/nextcloud/server/blob/master/lib/private/Accounts/AccountManager.php). Example defaults (verify against your deployed version): | Property | Default visibility scope | |--------------|--------------------------| | Display name | Federated | | Address | Local | | Website | Local | | Email | Federated | | Avatar | Federated | | Phone | Local | | Twitter | Local | | Bluesky | Local | | Fediverse | Local | | Organisation | Local | | Role | Local | | Headline | Local | | Biography | Local | | Birthdate | Local | | Pronouns | Federated | ### Override default scopes in `config.php` To override one or several default visibility scopes for *new users*, use `account_manager.default_property_scope` (default: empty array): ``` php 'account_manager.default_property_scope' => [ \OCP\Accounts\IAccountManager::PROPERTY_PHONE => \OCP\Accounts\IAccountManager::SCOPE_PRIVATE, \OCP\Accounts\IAccountManager::PROPERTY_ROLE => \OCP\Accounts\IAccountManager::SCOPE_FEDERATED, ] ``` In the above example, phone and role are overwritten to `Private` and `Federated` respectively. > **提示** > > Use `\OCP\Accounts\IAccountManager` constants for both property keys and scope values. ### FAQ: How to lock profile visibility down If your goal is maximum privacy: 1. Disable profiles globally (strictest option): ``` php 'profile.enabled' => false, ``` Effect: - Profile functionality is removed. - Profile-based discoverability/usability features are reduced accordingly. 2. If profiles must remain enabled, set restrictive defaults for new users: ``` php 'account_manager.default_property_scope' => [ \OCP\Accounts\IAccountManager::PROPERTY_ADDRESS => \OCP\Accounts\IAccountManager::SCOPE_PRIVATE, \OCP\Accounts\IAccountManager::PROPERTY_PHONE => \OCP\Accounts\IAccountManager::SCOPE_PRIVATE, \OCP\Accounts\IAccountManager::PROPERTY_WEBSITE => \OCP\Accounts\IAccountManager::SCOPE_PRIVATE, \OCP\Accounts\IAccountManager::PROPERTY_TWITTER => \OCP\Accounts\IAccountManager::SCOPE_PRIVATE, \OCP\Accounts\IAccountManager::PROPERTY_BLUESKY => \OCP\Accounts\IAccountManager::SCOPE_PRIVATE, \OCP\Accounts\IAccountManager::PROPERTY_FEDIVERSE => \OCP\Accounts\IAccountManager::SCOPE_PRIVATE, \OCP\Accounts\IAccountManager::PROPERTY_ORGANISATION => \OCP\Accounts\IAccountManager::SCOPE_PRIVATE, \OCP\Accounts\IAccountManager::PROPERTY_ROLE => \OCP\Accounts\IAccountManager::SCOPE_PRIVATE, \OCP\Accounts\IAccountManager::PROPERTY_HEADLINE => \OCP\Accounts\IAccountManager::SCOPE_PRIVATE, \OCP\Accounts\IAccountManager::PROPERTY_BIOGRAPHY => \OCP\Accounts\IAccountManager::SCOPE_PRIVATE, \OCP\Accounts\IAccountManager::PROPERTY_BIRTHDATE => \OCP\Accounts\IAccountManager::SCOPE_PRIVATE, \OCP\Accounts\IAccountManager::PROPERTY_PRONOUNS => \OCP\Accounts\IAccountManager::SCOPE_PRIVATE, \OCP\Accounts\IAccountManager::PROPERTY_AVATAR => \OCP\Accounts\IAccountManager::SCOPE_PRIVATE, ] ``` Notes: - `PROPERTY_DISPLAYNAME` and `PROPERTY_EMAIL` cannot be set to `Private`; server-side enforcement requires at least `Local`. - Defaults apply to **new users**. Existing users keep stored scopes unless changed. #### What becomes limited when you lock it down? With more restrictive scopes (especially `Private`), expect reduced visibility in: - User discovery/search/user cards - Share dialogs and mention/autocomplete context - Public/share-related contexts where account metadata may be shown - Federated visibility of profile attributes - Public lookup publication (only `Published` appears there) In short: tighter privacy reduces profile-based convenience and discoverability. ## Scopes and existing users The `account_manager.default_property_scope` config only applies to **new** users. Existing users keep their stored scopes. There is currently no admin-level mechanism to bulk-change scopes for existing users. The OCS provisioning API only allows users to change their **own** scopes — admins cannot set scopes on behalf of other users. Users can update their own scopes in **Personal settings** → **Personal info** → **Edit your Profile visibility**, or via the API: curl -s -u alice:password -X PUT \ "https://cloud.example.com/ocs/v2.php/cloud/users/alice" \ -H "OCS-APIRequest: true" \ -d "key=phoneScope&value=v2-private" The scope key is the property name with `Scope` appended. Available keys: `displaynameScope`, `emailScope`, `phoneScope`, `addressScope`, `websiteScope`, `twitterScope`, `blueskyScope`, `fediverseScope`, `organisationScope`, `roleScope`, `headlineScope`, `biographyScope`, `birthdateScope`, `avatarScope`, `pronounsScope` Allowed scope values: - `v2-private` — Private - `v2-local` — Local - `v2-federated` — Federated - `v2-published` — Published > **提示** > > `displaynameScope` and `emailScope` cannot be set to `v2-private`. The server enforces a minimum of `v2-local` for these properties. ## See also - [File Sharing](/link/951) — sharing and autocomplete settings that interact with profile visibility - [User manual: Personal settings](/link/878) — user-facing profile and personal info settings # User authentication with OpenID Connect Nextcloud users can authenticate via an external identity provider. Nextcloud can also be an identity provider itself. ## Authentication in Nextcloud The [OpenID Connect user backend app](https://apps.nextcloud.com/apps/user_oidc) makes it possible for users to authenticate using external Oidc identity providers. This app can optionally be in charge of user provisioning (by creating users when they first connect) or rely on other user backends and only take care of authentication. [More details in the project's README](https://github.com/nextcloud/user_oidc#user_oidc) ## Using Nextcloud as an identity provider The [OIDC Identity Provider community app](https://apps.nextcloud.com/apps/oidc) can be installed to make Nextcloud an identity provider for other services. This app will allow any Nextcloud user (managed by any user backend) to authenticate during an Oidc login flow. This is useful if you want your Nextcloud instance to be the authority regarding authentication and user profile data among multiple services. ## Bearer token validation Nextcloud can accept Oidc ID tokens and access tokens as valid bearer token for API requests. If using an external identity provider, only the `user_oidc` app is necessary. If Nextcloud is the identity provider, you will naturally need the `oidc` app to make Nextcloud an Oidc provider, and also the `user_oidc` app because it will take care of validating API requests authentication. In user_oidc, the `oidc_provider_bearer_validation` config flag needs to be set to true so `user_oidc` knows it needs to ask the `oidc` app to validate the received bearer tokens. [More details on bearer token validation](https://github.com/nextcloud/user_oidc#bearer-token-validation) # Desktop Clients Available for Windows, macOS, and various Linux distributions, the Nextcloud Desktop Sync client enables you to: - Specify one or more directories on your computer that you want to synchronize to the Nextcloud server. - Always have the latest files synchronized, wherever they are located. Your files are always automatically synchronized between your Nextcloud server, computer and mobile device. - [Desktop Client Deployment and Setup](/link/1025) - [Block desktop client access at the HTTP layer](/link/1026) - [Troubleshooting](/link/1027) You can find additional information here: - [User manual](/link/865) - [Developer manual](https://docs.nextcloud.com/server/latest/developer_manual/desktop/index.html) # Desktop Client Deployment and Setup This chapter describes administrator-facing deployment and setup options for the Nextcloud Desktop client. These options are intended for managed rollouts and other administrative scenarios, such as deployment scripts, software-management platforms, login scripts, MDM or RMM workflows, and other automated installation or configuration processes. Depending on your deployment goals, you can use the desktop client in one of several ways: - customize Windows installation behavior, - create an account automatically during deployment without user interaction, or - prefill or constrain the interactive setup wizard. ## Choosing the right approach Use the option that best matches your deployment goal: **I want to customize how the client is installed on managed Windows systems.** See [Advanced Windows deployment options](/link/1025). **I want to silently create an account during deployment.** See [Non-interactive account provisioning](/link/1025). **I want users to complete setup interactively, but with predefined values or restrictions.** See [Interactive wizard preconfiguration](/link/1025). ## Advanced Windows deployment options If you just want to install the desktop client on your local system, simply launch the `.msi` file and follow the installation wizard. The following options are intended for advanced Windows installations, for example when automating deployment or customizing installed features. > **提示** > > Windows installation customization controls how the client is installed. It does not by itself create or configure a desktop-client account. If you want to configure an account after installation, see [Non-interactive account provisioning](/link/1025) or [Interactive wizard preconfiguration](/link/1025). ### Features The MSI installer provides several features that can be installed or removed individually, which you can also control via the command line. If you are automating the installation, run the following command: msiexec /passive /i Nextcloud-x.y.z-x64.msi The command installs the client into the default location with the default features enabled. If you want to disable, for example, desktop shortcut icons, you can change the command to the following: msiexec /passive /i Nextcloud-x.y.z-x64.msi REMOVE=DesktopShortcut See the following table for a list of available features: | Feature | Enabled by default | Description | Property to disable | |----|----|----|----| | Client | Yes, required | The actual client | | | DesktopShortcut | Yes | Adds a shortcut to the desktop | `NO_DESKTOP_SHORTCUT` | | StartMenuShortcuts | Yes | Adds a shortcut to the start menu | `NO_START_MENU_SHORTCUTS` | | ShellExtensions | Yes | Adds Explorer integration | `NO_SHELL_EXTENSIONS` | ### Installation You can also choose to only install the client itself by using the following command: msiexec /passive /i Nextcloud-x.y.z-x64.msi ADDDEFAULT=Client For example, if you want to install everything except the `DesktopShortcut` and the `ShellExtensions` feature, you have two possibilities: 1. Explicitly name all the features you actually want to install (whitelist), where `Client` is always installed anyway: msiexec /passive /i Nextcloud-x.y.z-x64.msi ADDDEFAULT=StartMenuShortcuts 2. Pass the `NO_DESKTOP_SHORTCUT` and `NO_SHELL_EXTENSIONS` properties: msiexec /passive /i Nextcloud-x.y.z-x64.msi NO_DESKTOP_SHORTCUT="1" NO_SHELL_EXTENSIONS="1" > **提示** > > The Nextcloud `.msi` remembers these properties, so you do not need to specify them again on upgrades. > **提示** > > You cannot use these to change the installed features after installation. If you want to do that, see the next section. ### Changing installed features You can change the installed features later by using the `REMOVE` and `ADDDEFAULT` properties. To add the desktop shortcut later, run the following command: msiexec /passive /i Nextcloud-x.y.z-x64.msi ADDDEFAULT="DesktopShortcut" To remove it, run the following command: msiexec /passive /i Nextcloud-x.y.z-x64.msi REMOVE="DesktopShortcut" Windows keeps track of the installed features, and `REMOVE` or `ADDDEFAULT` affects only the specified features. > **提示** > > You cannot specify `REMOVE` on initial installation, as it will disable all features. ### Installation folder You can adjust the installation folder by specifying the `INSTALLDIR` property: msiexec /passive /i Nextcloud-x.y.z-x64.msi INSTALLDIR="C:\Program Files\Non Standard Nextcloud Client Folder" Be careful when using PowerShell instead of `cmd.exe`; getting the whitespace escaping right can be tricky. Specifying `INSTALLDIR` like this only works on first installation; you cannot simply re-run the `.msi` with a different path. If you still need to change it, uninstall the client first and then reinstall it to the new location. ### Disabling automatic updates To disable automatic updates, pass the `SKIPAUTOUPDATE` property: msiexec /passive /i Nextcloud-x.y.z-x64.msi SKIPAUTOUPDATE="1" ### Launch after installation To launch the client automatically after installation, pass the `LAUNCH` property: msiexec /i Nextcloud-x.y.z-x64.msi LAUNCH="1" This option also removes the checkbox that lets users decide whether to launch the client during non-passive or non-quiet installations. > **提示** > > This option does not have any effect without a GUI. ### No reboot after installation The client schedules a reboot after installation to make sure the Explorer extension is correctly loaded or unloaded. If you are handling reboots yourself, you can set the `REBOOT` property: msiexec /i Nextcloud-x.y.z-x64.msi REBOOT=ReallySuppress This makes `msiexec` exit with error `ERROR_SUCCESS_REBOOT_REQUIRED` (3010). If your deployment tooling interprets this as an actual error and you want to avoid that, you may want to set `DO_NOT_SCHEDULE_REBOOT` instead: msiexec /i Nextcloud-x.y.z-x64.msi DO_NOT_SCHEDULE_REBOOT="1" ## Non-interactive account provisioning The Nextcloud Desktop client supports non-interactive account provisioning from the command line. This is intended for deployment automation and other managed-installation scenarios where an administrator wants to create a desktop-client account without requiring the user to go through the graphical setup wizard. In a typical deployment workflow, you deploy the desktop client package first, then invoke the desktop client executable with provisioning parameters as part of your automation. When the required parameters are provided, the client attempts to create an account and store it in the client's normal configuration so that subsequent launches behave as if the account had been added through the graphical user interface. If account creation succeeds, the client exits with code `0`. If account creation fails, the client exits with code `1`. Detailed status and failure information is written to the desktop client logs. > **提示** > > This workflow is distinct from interactive wizard preconfiguration. If you want to prefill or constrain the setup wizard instead of directly provisioning an account, see [Interactive wizard preconfiguration](/link/1025). ### Required parameters The following parameters are required for non-interactive account provisioning: `--userid` The user ID to configure in the desktop client. `--apppassword` The app password to use for authentication. App passwords should be used instead of a user's regular login password. See the server documentation for the login flow and app password generation process. `--serverurl` The base URL of the Nextcloud server to use for the account. ### Optional parameters `--localdirpath` The local path to use for the sync folder. If omitted, the desktop client chooses its normal default sync-folder location for the platform. If this option is provided and the target directory already exists and is not empty, account provisioning fails. If this option is provided and the directory does not yet exist, the client attempts to create it. `--remotedirpath` The remote path to sync. If omitted, the default is `/` (the account root on the server). Example: if the server contains folders such as `/Photos`, `/Documents`, and `/Music`, specifying `/Music` creates a sync connection for that remote subfolder instead of the entire account root. `--isvfsenabled` Controls whether the created sync connection should use virtual files. Use `1` to enable virtual files and `0` to disable them. Virtual file support depends on the client build, operating system, and runtime availability of the required virtual-file functionality. Only enable this option on platforms and builds where virtual files are supported. `--confdir` Overrides the configuration directory used by the client process. This is a general client option rather than a provisioning-specific option. It is only needed if you intentionally want to use a non-default configuration directory. If you use this option during provisioning, subsequent desktop-client launches must use the same configuration directory, or the provisioned account may not appear in later GUI sessions. ### Behavior When started with the required provisioning parameters, the desktop client attempts to: 1. validate the provided command-line parameters, 2. create the local sync folder if needed, 3. authenticate to the server using the provided app password, 4. verify server access, and 5. store the resulting account in the client's normal configuration. On later launches, the configured account is available as a normal desktop-client account, provided the client is started with the same configuration context. > **说明** > > The desktop client does not mount the server into the local path like a network filesystem. It creates a sync connection. An empty local folder does not by itself mean that provisioning failed. ### Common failure cases Account provisioning can fail for reasons including: - one or more required parameters are missing or invalid, - an account for the same user and server already exists, - the specified local sync folder already exists and is not empty, - the specified local sync folder could not be created, - the server URL is incorrect, - the app password is invalid, - the authenticated request is redirected unexpectedly, - the server denies access to the configured account, or - the server returns an invalid response to the authenticated WebDAV request. In these cases, the client exits with code `1` and writes more detailed information to the logs. ### Examples Windows: ``` powershell "C:\Program Files\Nextcloud\nextcloud.exe" ^ --userid admin ^ --apppassword Jliy12356785jxnHa2ZCiZ9MX48ncECwDso95Pq3a5HABjY34ZvhZiXrPfpKWUg7aOHAX5 ^ --serverurl https://cloud.example.com ^ --localdirpath "D:\Nextcloud-sync-folder" ^ --remotedirpath /Music ^ --isvfsenabled 1 ``` Linux: ``` bash nextcloud \ --userid admin \ --apppassword Jliy12356785jxnHa2ZCiZ9MX48ncECwDso95Pq3a5HABjY34ZvhZiXrPfpKWUg7aOHAX5 \ --serverurl https://cloud.example.com \ --localdirpath "/home/admin/Nextcloud-sync-folder" \ --remotedirpath /Music \ --isvfsenabled 0 ``` macOS: ``` bash nextcloud \ --userid admin \ --apppassword Jliy12356785jxnHa2ZCiZ9MX48ncECwDso95Pq3a5HABjY34ZvhZiXrPfpKWUg7aOHAX5 \ --serverurl https://cloud.example.com \ --localdirpath "/Users/admin/Nextcloud-sync-folder" \ --remotedirpath /Music \ --isvfsenabled 1 ``` ### Recommendations For reliable deployment automation: - use app passwords rather than regular user passwords, - ensure that the server URL is the correct base URL for the Nextcloud instance, - use a new or empty local sync directory, - validate that the target remote path exists and is accessible to the user, - enable `--isvfsenabled` only on supported platforms and builds, and - avoid `--confdir` unless you intentionally need a non-default configuration location. ## Interactive wizard preconfiguration If you want to automate the Account Setup Wizard so that users can skip entering the server URL and local sync folder path in the UI, you can use command-line parameters. When you specify both, the desktop client's Account Setup Wizard will jump straight to opening a browser for account authentication or connection without the need to enter any of the connection details. The local sync folder will also be selected to the one you specify instead of using the default path. The following parameters are supported: `--overridelocaldir` Specify a local directory to be used in the account setup wizard. Example: `/home/nextcloud-sync-folder` `--overrideserverurl` Specify a server URL to use for the force override in the account setup wizard. Example: `https://cloud.example.com` ### Behavior These options affect the behavior of the interactive setup wizard. They do not directly create an account in the same way as non-interactive account provisioning. Use this approach when you want the user to complete setup interactively, but want to prefill, constrain, or guide the process. ### Examples Windows: ``` powershell "C:\Program Files\Nextcloud\nextcloud.exe" --overridelocaldir "D:/work/nextcloud-sync-folder" --overrideserverurl https://cloud.example.com ``` Linux and macOS: ``` bash nextcloud --overridelocaldir "/home//nextcloud-sync-folder" --overrideserverurl https://cloud.example.com ``` ### Important distinction from non-interactive provisioning Use wizard preconfiguration when you still want the user to complete setup in the graphical interface. Use non-interactive account provisioning when you want deployment automation to create the account directly. In other words: - non-interactive provisioning creates the account automatically; - wizard preconfiguration influences the setup wizard, but still relies on interactive completion. ## Summary The Nextcloud Desktop client supports multiple administrator-facing deployment and setup workflows. Choose the workflow that best matches your environment: - use advanced Windows deployment options to control installation behavior on managed Windows systems, - use non-interactive account provisioning to create desktop-client accounts automatically during deployment, - use interactive wizard preconfiguration to guide users through a constrained or prefilled first-run setup process. # Block desktop client access at the HTTP layer Server administrators can reject Nextcloud Desktop requests at a web server, reverse proxy, or web application firewall (WAF) by matching the HTTP `User-Agent` header. This can be useful as a compatibility guard or an operational policy, for example to temporarily block all desktop clients or require a particular client release. > **注意** > > This is not a security boundary. The client controls the `User-Agent` header and can change or omit it. Do not use this rule as the only control when access must be prevented against a deliberately modified client. ## Identify desktop client requests The standard desktop client sends a header with this shape: ```text Mozilla/5.0 (Macintosh) mirall/34.0.2 (Nextcloud, macos-25.5.0 ClientArchitecture: arm64 OsArchitecture: arm64) ``` The stable marker is `mirall/`; the value immediately after it is the desktop client version. The current client constructs this value in [Utility::userAgentString()](https://github.com/nextcloud/desktop/blob/master/src/common/utility.cpp). Use a case-insensitive match for: ```text mirall/ ``` Apply the rule to every request reaching the Nextcloud virtual host. Blocking only one OCS or WebDAV endpoint does not block desktop access because the client uses multiple OCS, WebDAV, login-flow, status, and provisioning endpoints. Nextcloud Server's `USER_AGENT_CLIENT_DESKTOP` [matcher](https://github.com/nextcloud-deps/ocp/blob/22f259b5b27e65a70b6797e1c0c0ecd4b02c0ef9/OCP/IRequest.php) also recognizes the legacy marker `csyncoC/`. To include those clients, replace `mirall/` with `(mirall|csyncoC)/` in regular-expression rules, or add a second substring rule where the configuration format does not support regular expressions. ## Choose the policy ### Block every standard desktop client Match the case-insensitive substring: ```text mirall/ ``` ### Block releases older than 34.0.2 Web-server regular expressions do not compare arbitrary version strings as semantic versions. The following case-insensitive expression is deliberately written for one minimum release, `34.0.2`: ```text mirall/(([0-9]|[12][0-9]|3[0-3])[.]|34[.]0[.](0|1)([^0-9]|$)) ``` It has these results: | Desktop version | Result | |-----------------|----------------------| | `3.14.3` | blocked | | `33.0.0` | blocked | | `34.0.0` | blocked | | `34.0.1` | blocked | | `34.0.2` | allowed by this rule | | `34.1.0` | allowed by this rule | | `35.0.0` | allowed by this rule | The expression assumes normal release versions with three numeric components. Do not change only the version text in the expression. Build and test a new set of numeric ranges whenever the minimum release changes. A WAF that can extract the version and compare three integer fields is preferable when the minimum changes frequently. Return `403 Forbidden`. Do not return `401 Unauthorized`: by HTTP semantics, that status asks the client to authenticate and obscures that this is an administrative policy. The desktop client is not guaranteed to display a custom response body, so the administrator should communicate the policy separately to users. The examples below assume that Nextcloud has its own virtual host at `cloud.example.com`. If the host serves other applications, additionally scope the rule to the Nextcloud URL prefix. ## nginx Define one `map` in the `http` context. Enable exactly one of the two match entries: ```text http { map $http_user_agent $block_nextcloud_desktop { default 0; # Policy A: block every standard desktop client. ~*mirall/ 1; # Policy B: instead block releases older than 34.0.2. # ~*mirall/(([0-9]|[12][0-9]|3[0-3])[.]|34[.]0[.](0|1)([^0-9]|$)) 1; } server { server_name cloud.example.com; if ($block_nextcloud_desktop) { return 403 "Nextcloud desktop client access is disabled.\n"; } # The existing Nextcloud configuration follows here. } } ``` The `map` directive is valid only in the `http` context. The resulting variable is then checked in the Nextcloud `server` block. A conditional containing only `return` is sufficient here; no URI rewrite is involved. Validate and reload the configuration with the commands appropriate to the installation, commonly: ```console nginx -t systemctl reload nginx ``` See the nginx documentation for [map](https://nginx.org/en/docs/http/ngx_http_map_module.html) and [return](https://nginx.org/en/docs/http/ngx_http_rewrite_module.html#return). ## Apache HTTP Server 2.4 Place `SetEnvIfNoCase` in the Nextcloud virtual host and deny requests carrying the resulting environment variable. Enable exactly one `SetEnvIfNoCase` line: ```text ServerName cloud.example.com # Policy A: block every standard desktop client. SetEnvIfNoCase User-Agent "mirall/" block_nextcloud_desktop # Policy B: instead block releases older than 34.0.2. # SetEnvIfNoCase User-Agent "mirall/(([0-9]|[12][0-9]|3[0-3])[.]|34[.]0[.](0|1)([^0-9]|$))" block_nextcloud_desktop Require all granted Require not env block_nextcloud_desktop # The existing Nextcloud configuration follows here. ``` For a subdirectory installation, such as `https://cloud.example.com/nextcloud`, use `` instead. The modules `mod_setenvif` and `mod_authz_core` must be enabled. Validate and reload the configuration with the commands appropriate to the installation, commonly: ```console apachectl configtest systemctl reload apache2 ``` The Apache documentation describes this [SetEnvIfNoCase and Require blocking pattern](https://httpd.apache.org/docs/2.4/rewrite/avoid.html#blocked-bot) and also notes that a client can circumvent a `User-Agent` rule. ## Caddy 2 Place the matcher and response before the existing Nextcloud handler. Enable exactly one matcher line: ```text cloud.example.com { # Policy A: block every standard desktop client. @blockedNextcloudDesktop header_regexp User-Agent (?i)mirall/ # Policy B: instead block releases older than 34.0.2. # @blockedNextcloudDesktop header_regexp User-Agent (?i)mirall/(([0-9]|[12][0-9]|3[0-3])[.]|34[.]0[.](0|1)([^0-9]|$)) respond @blockedNextcloudDesktop "Nextcloud desktop client access is disabled." 403 # The existing Nextcloud file_server, php_fastcgi, or reverse_proxy # directives follow here. } ``` Caddy uses RE2 regular expressions. The example therefore uses capturing groups rather than PCRE-only constructs. Validate and reload the configuration with the commands appropriate to the installation, commonly: ```console caddy validate --config /etc/caddy/Caddyfile systemctl reload caddy ``` See the Caddy documentation for [header_regexp](https://caddyserver.com/docs/caddyfile/matchers#header-regexp) and [respond](https://caddyserver.com/docs/caddyfile/directives/respond). ## HAProxy Add the ACL and deny action to the HTTP `frontend` that receives Nextcloud traffic. Enable exactly one `blocked_nextcloud_desktop` ACL: ```text frontend https_frontend bind :443 ssl crt /etc/haproxy/certs/cloud.example.com.pem acl nextcloud_host hdr(host) -i cloud.example.com cloud.example.com:443 # Policy A: block every standard desktop client. acl blocked_nextcloud_desktop req.hdr(User-Agent) -m sub -i mirall/ # Policy B: instead block releases older than 34.0.2. # acl blocked_nextcloud_desktop req.hdr(User-Agent) -m reg -i mirall/(([0-9]|[12][0-9]|3[0-3])[.]|34[.]0[.](0|1)([^0-9]|$)) http-request deny deny_status 403 if nextcloud_host blocked_nextcloud_desktop # The existing backend selection follows here. ``` Keep the host ACL when this frontend serves more than Nextcloud. Validate and reload the configuration with the commands appropriate to the installation, commonly: ```console haproxy -c -f /etc/haproxy/haproxy.cfg systemctl reload haproxy ``` See the HAProxy documentation for [ACLs](https://www.haproxy.com/documentation/haproxy-configuration-tutorials/proxying-essentials/custom-rules/acls/) and [http-request deny](https://www.haproxy.com/documentation/haproxy-configuration-tutorials/security/traffic-policing/). ## Verify the rule Test from a system that reaches the same proxy or WAF path as real users. The following probes do not require Nextcloud credentials: ```console # Must be 403 for both policies. curl -sS -o /dev/null -w '%{http_code}\n' \ -A 'Mozilla/5.0 (Linux) mirall/34.0.1 (Nextcloud, linux)' \ https://cloud.example.com/status.php # Must not be blocked by the minimum-version policy. It is still 403 when # the block-all policy is active. curl -sS -o /dev/null -w '%{http_code}\n' \ -A 'Mozilla/5.0 (Linux) mirall/34.0.2 (Nextcloud, linux)' \ https://cloud.example.com/status.php # Must not be blocked by either desktop rule. curl -sS -o /dev/null -w '%{http_code}\n' \ -A 'Mozilla/5.0 (compatible; policy-check)' \ https://cloud.example.com/status.php ``` Also verify these operational details: 1. The rule covers all Nextcloud paths and HTTP methods, including WebDAV methods such as `PROPFIND`, `PUT`, and `DELETE`. 2. The origin server cannot be reached through another hostname or IP address that bypasses the proxy or WAF. 3. Proxy layers preserve the original `User-Agent` header until the component enforcing the rule has evaluated it. 4. Access and WAF logs record blocked requests, the matched policy, and the returned status. 5. A rollback consists of disabling the match rule and reloading the configuration; it does not require changing Nextcloud itself. # Troubleshooting The following two general issues can result in failed synchronization: - The server setup is incorrect. - The client contains a bug. When reporting bugs, it is helpful if you first determine what part of the system is causing the issue. ## Identifying Basic Functionality Problems Performing a general Nextcloud Server test The first step in troubleshooting synchronization issues is to verify that you can log on to the Nextcloud web application. To verify connectivity to the Nextcloud server try logging in via your Web browser. If you are not prompted for your username and password, or if a red warning box appears on the page, your server setup requires modification. Please verify that your server installation is working correctly. Ensure the WebDAV API is working If all desktop clients fail to connect to the Nextcloud Server, but access using the Web interface functions properly, the problem is often a misconfiguration of the WebDAV API. The Nextcloud Client uses the built-in WebDAV access of the server content. Verify that you can log on to Nextcloud's WebDAV server. To verify connectivity with the Nextcloud WebDAV server: - Open a browser window and enter the address to the Nextcloud WebDAV server. For example, if your Nextcloud instance is installed at `http://yourserver.com/nextcloud`, your WebDAV server address is `http://yourserver.com/nextcloud/remote.php/dav`. If you are prompted for your username and password but, after providing the correct credentials, authentication fails, please ensure that your authentication backend is configured properly. Use a WebDAV command line tool to test A more sophisticated test method for troubleshooting synchronization issues is to use a WebDAV command line client and log into the Nextcloud WebDAV server. One such command line client -- called `cadaver` -- is available for Linux distributions. You can use this application to further verify that the WebDAV server is running properly using PROPFIND calls. As an example, after installing the `cadaver` app, you can issue the `propget` command to obtain various properties pertaining to the current directory and also verify WebDAV server connection. ## "CSync unknown error" If you see this error message stop your client, delete the `.sync_xxxxxxx.db` file, and then restart your client. There is a hidden `.sync_xxxxxxx.db` file inside the folder of every account configured on your client. > **提示** > > Please note that this will also erase some of your settings about which files to download. See for more discussion of this issue. ## "Connection closed" message when syncing files This message can be caused by using chunks that are too big or time-outs that are set too liberally. You can configure the chunking behavior of the client in the config file. For example, change these settings: | | | | |----|----|----| | `chunkSize` | `10000000` (10 MB) | Specifies the chunk size of uploaded files in bytes. The client will dynamically adjust this size within the maximum and minimum bounds (see below). | | `minChunkSize` | `1000000` (1 MB) | Specifies the minimum chunk size of uploaded files in bytes. | | `maxChunkSize` | `50000000` (1000 MB) | Specifies the maximum chunk size of uploaded files in bytes. | | `targetChunkUploadDuration` | `6000` (1 minute) | Target duration in milliseconds for chunk uploads. The client adjusts the chunk size until each chunk upload takes approximately this long. Set to 0 to disable dynamic chunk sizing. | Setting `maxChunkSize` to 50000000, for example, will decrease the individual chunk to about 50 mb. This causes additional overhead but might be required in some situations, for example behind CloudFlare which has been seen limiting upload chunks to 100mb. In other situations, limiting `targetChunkUploadDuration` can help to avoid time-outs. ## Connection issues with the macOS client on "insecure" connections When using macOS devices to connect to a Nextcloud server that uses a what maybe be classified as an insecure connection (i.e. connecting to a server with a self-signed certificate, or a certificate with what Apple may consider an insufficiently secure cipher), the macOS client may not connect to the server. This is because macOS requires a valid certificate to establish a connection. To resolve this issue, you must ensure the server is signed with a certificate that is accepted by Apple's App Transport Security requirements. More information on the requirements can be found in Apple's documentation pages. ## Isolating other issues Other issues can affect synchronization of your Nextcloud files: - If you find that the results of the synchronizations are unreliable, please ensure that the folder to which you are synchronizing is not shared with other synchronization applications. - Synchronizing the same directory with Nextcloud and other synchronization software such as Unison, rsync, Microsoft Windows Offline Folders, or other cloud services such as Dropbox or Microsoft SkyDrive is not supported and should not be attempted. In the worst case, it is possible that synchronizing folders or files using Nextcloud and other synchronization software or services can result in data loss. - If you find that only specific files are not synchronized, the synchronization protocol might be having an effect. Some files are automatically ignored because they are system files, other files might be ignored because their filename contains characters that are not supported on certain file systems. For more information about ignored files, see ignored-files. - If you are operating your own server, and use the local storage backend (the default), make sure that Nextcloud has exclusive access to the directory. > **注意** > > The data directory on the server is exclusive to Nextcloud and must not be modified manually. - If you are using a different file backend on the server, you can try to exclude a bug in the backend by reverting to the built-in backend. - If you are experiencing slow upload/download speed or similar performance issues be aware that those could be caused by on-access virus scanning solutions, either on the server (like the files_antivirus app) or the client. ## Log Files Effectively debugging software requires as much relevant information as can be obtained. To assist the Nextcloud support personnel, please try to provide as many relevant logs as possible. Log output can help with tracking down problems and, if you report a bug, log output can help to resolve an issue more quickly. > > **注意** > > > > Log files contain sensitive information. You may wish to redact sensitive details or to only share limited excerpts. ### Obtaining the Client Log File ### Create Debug Archive Since the 3.1.0 release we made it easier for users to provide debug information: debug logging is enabled by default with expiration time set to 24 hours and under the "General" settings, you can click on "Create Debug Archive ..." to pick the location of where the desktop client will export the logs and the database to a zip file. ![Create debug archive](https://docs.cocobook.com/uploads/images/gallery/2026-10/create-debug-archive.png) ### Keyboard shortcut Another way to obtain the client log file: 1. Open the Nextcloud Desktop Client. 2. Press `F12` or `Ctrl`+`L` on your keyboard. The Log Output window opens. ![Log output](https://docs.cocobook.com/uploads/images/gallery/2026-10/log-output-window.png) 3. Click the 'Save' button. The Save Log File window opens. ![Save logfile](https://docs.cocobook.com/uploads/images/gallery/2026-10/save-log-file.png) 4. Navigate to a location on your system where you want to save your log file. 5. Name the log file and click the 'Save' button. > The log file is saved in the location specified. ### Command line Alternatively, you can launch the Nextcloud Log Output window using the `--logwindow` command. After issuing this command, the Log Output window opens to show the current log. You can then follow the same procedures mentioned above to save the log to a file. > > **提示** > > > > You can also open a log window for an already running session, by restarting the client using the following command: > > > > - Windows: `C:\Program Files\Nextcloud\nextcloud.exe --logwindow` > > - macOS: `/Applications/nextcloud.app/Contents/MacOS/nextcloud --logwindow` > > - Linux: `nextcloud --logwindow` ### Config file The Nextcloud client enables you to save log files directly to a predefined file or directory. This is a useful option for troubleshooting sporadic issues as it enables you to log large amounts of data and bypass the limited buffer settings associated with the log window. To enable logging to a directory, stop the client and add the following to the General section in the configuration file: [General] logDebug=true logExpire= logDir= Independent of platform you must use slash (/) as a path separator: > > **提示** > > > > \* Correct: C:/Temp \* Not correct: C:Temp As an example, to keep log data for two days in a directory called temp: [General] logDebug=true logExpire=48 logDir=C:/Temp Once you restart the client, you will find the log file in the `` defined in `logDir`. > > **提示** > > > > You will find the configuration file in the following locations: > > > > - Microsoft Windows systems: `%APPDATA%\Nextcloud\nextcloud.cfg` > > - macOS systems: `$HOME/Library/Preferences/Nextcloud/nextcloud.cfg` > > - Linux distributions: `$HOME/.config/Nextcloud/nextcloud.cfg` Alternatively, you can start the client in the command line with parameters: 1. To save to a file, start the client using the `--logfile ` command, where `` is the filename to which you want to save the file. 2. To save to a directory, start the client using the `--logdir ` command, where `` is an existing directory. When using the `--logdir` command, each sync run creates a new file. To limit the amount of data that accumulates over time, you can specify the `--logexpire ` command. When combined with the `--logdir` command, the client automatically erases saved log data in the directory that is older than the specified number of hours. As an example, to define a test where you keep log data for two days, you can issue the following command: `` ` nextcloud --logdir /tmp/nextcloud_logs --logexpire 48 ``\` ### Nextcloud server Log File The Nextcloud server also maintains an Nextcloud specific log file. This log file must be enabled through the Nextcloud Administration page. On that page, you can adjust the log level. We recommend that when setting the log file level that you set it to a verbose level like `Debug` or `Info`. You can view the server log file using the web interface or you can open it directly from the file system in the Nextcloud server data directory. See [Logging](/link/932) in the admin manual for details on configuring log levels and log file locations. ### Webserver Log Files It can be helpful to view your webserver's error log file to isolate any Nextcloud-related problems. For Apache on Linux, the error logs are typically located in the `/var/log/apache2` directory. Some helpful files include the following: - `error_log` -- Maintains errors associated with PHP code. - `access_log` -- Typically records all requests handled by the server; very useful as a debugging tool because the log line contains information specific to each request and its result. You can find more information about Apache logging at `http://httpd.apache.org/docs/current/logs.html`. ## Core Dumps On macOS and Linux systems, and in the unlikely event the client software crashes, the client is able to write a core dump file. Obtaining a core dump file can assist Nextcloud Customer Support tremendously in the debugging process. To enable the writing of core dump files, you must define the `OWNCLOUD_CORE_DUMP` environment variable on the system. For example: `` ` OWNCLOUD_CORE_DUMP=1 nextcloud ``\` This command starts the client with core dumping enabled and saves the files in the current working directory. > **提示** > > Core dump files can be fairly large. Before enabling core dumps on your system, ensure that you have enough disk space to accommodate these files. Also, due to their size, we strongly recommend that you properly compress any core dump files prior to sending them to Nextcloud Customer Support. ## Citrix Workspace known issues These are known issues when running the desktop client in a Citrix workspace: - The Windows user's Roaming profile needs to be persisted between sessions. The failure on doing so will result in result in users having to set up their account again in every new session. - The user's synchronization folder also needs to be persisted between sessions. The client will throw errors because it can not find the sync folder once the users logs in a new session. - Every time the user logs in a Citrix environment, it creates a session with the desktop client and in that session the client will sync the user's files, that can quickly lead to the storage running out of space.