How to Set Up LDAP Authentication in Nextcloud: Complete Guide

Nextcloud LDAP integration lets your team sign in with their existing Active Directory or LDAP credentials instead of maintaining separate Nextcloud passwords. This guide walks you through the configuration in Nextcloud's web admin panel, testing your setup, and fixing the most common failures. Budget 30 minutes for configuration if you already have network access to your LDAP server.

Do You Need LDAP Integration?

LDAP (Lightweight Directory Access Protocol) is the protocol Active Directory and most corporate LDAP servers use to manage user accounts, groups, and credentials. Nextcloud can query your LDAP server directly and create user accounts on-the-fly when someone logs in for the first time.

Use LDAP integration if your team uses Active Directory (on-premise or via LDAP bridge), OpenLDAP, FreeIPA, or any LDAP-compatible directory. You do not need it if you have only a handful of users and can manage Nextcloud accounts directly. But if you manage 20+ users across departments, LDAP integration saves significant administrative overhead. Users log in once; their account syncs to Nextcloud automatically. When someone leaves your company, you disable their AD account and they immediately lose Nextcloud access without manual intervention.

The tradeoff is operational: your Nextcloud instance must reach your LDAP server over the network on port 389 (or 636 for LDAPS, the encrypted version). If that connection fails, users cannot log in. For most companies, LDAPS (port 636) is the right choice because it encrypts the password and all data in transit. We will cover LDAPS setup below.

Nextcloud has 37.3K GitHub stars and is mature and stable for this use case. Version 35 (the current stable release) ships with solid LDAP support via its "LDAP User and Group Backend" app. Most configuration is done through the web admin panel with zero code required. If you want the infrastructure managed for you, Opsily's managed Nextcloud hosting handles the LDAP setup and network connectivity so you never deal with connection failures.

Prerequisites: Check These Four Things First

Before you enable LDAP integration, confirm these are in place:

1. PHP LDAP module installed. Nextcloud queries LDAP via PHP's ldap extension. If it is not installed, the LDAP app will not work. On Ubuntu/Debian, run: sudo apt install php-ldap. On CentOS/RHEL, run: sudo yum install php-ldap. Then restart your web server (Apache or Nginx). Confirm the module loaded with: php -m | grep ldap. If it does not appear in the list, the installation failed and you must troubleshoot before proceeding.

2. Nextcloud server can reach your LDAP server on port 389 (or 636 for LDAPS). This is not always obvious, especially if Nextcloud runs in a VPC, data center, or behind a VPN. Your LDAP server must be reachable from the network location where Nextcloud is deployed. If your Nextcloud is on Opsily's managed Nextcloud platform, confirm with your hosting provider that outbound connections to your LDAP server on ports 389 or 636 are allowed. Many firewalls block these by default. Test connectivity before configuring: from the Nextcloud server, run: nc -zv your.ldap.server.com 389. If you get "Connection refused" or a timeout, stop and fix networking first. Do not proceed until the test succeeds.

3. LDAP service account credentials. You need a read-only account in your LDAP or AD directory. This account does not need admin rights; it only needs permission to search users and groups. In Active Directory, create a user account (e.g., "svc-nextcloud") and set a strong password. Write down the full distinguished name (DN): for example, cn=svc-nextcloud,cn=Users,dc=example,dc=com. You will paste this into Nextcloud's configuration. Do not use an admin account for this; a read-only service account is safer and sufficient.

4. Base DN known. The base DN is the starting point for user and group searches in your LDAP tree. In Active Directory, this is typically cn=Users,dc=example,dc=com or ou=Users,dc=example,dc=com. In OpenLDAP, it might be ou=people,dc=example,dc=com. Ask your LDAP admin or look in your LDAP browser tool (e.g., LDAP Admin for Windows, or Apache Directory Studio cross-platform). You need this value before starting configuration.

Also, if you are using LDAPS (recommended), export your LDAP server's SSL certificate and confirm it is valid and trusted by your Nextcloud server. If the certificate is self-signed, you may need to import the CA certificate into Nextcloud's PHP trust store, which varies by operating system and hosting provider.

Step 1: Enable the LDAP User and Group Backend App

Log in to Nextcloud as an admin user. Click "Administration Settings" (top right menu) and go to "Apps". Search for "ldap" in the search box and click the "LDAP User and Group Backend" app. Click the "Enable" button.

After enabling, return to Administration Settings. You will see a new section: "LDAP/AD Integration" in the left sidebar under the System section. Click it.

You will see a gray "Delete Configuration" button but no form yet because no LDAP connection is configured. This is normal. Nextcloud is ready for configuration but waiting for you to define a server connection first. The interface will populate with input fields once you start entering server details.

Step 2: Configure the LDAP Server Connection

On the LDAP/AD Integration page, you will see the "Server" tab, which is active by default. Nextcloud displays form fields for:

Host (required): Enter your LDAP server's hostname or IP address. Example: ldap.example.com or 192.168.1.100. Do not include ldap:// or ldaps:// prefix; Nextcloud will add the protocol based on your encryption choice (see Port below). Use a fully qualified domain name if possible, especially if you are using LDAPS and certificate validation.

Port (required): Enter 389 for unencrypted LDAP or 636 for LDAPS (encrypted). Strongly recommend 636 if your LDAP server supports it. Using port 389 sends passwords in plain text over the network, which is unacceptable on untrusted or internet-facing connections. If port 636 is blocked by your firewall, use a VPN to tunnel the connection rather than falling back to 389.

User DN (required): Paste the distinguished name of your read-only service account. Example: cn=svc-nextcloud,cn=Users,dc=example,dc=com or cn=svc-nextcloud,ou=System Accounts,dc=example,dc=com. This is the account Nextcloud will use to search for users and groups. Make sure you have the full DN, not just the username.

Password (required): Paste the password for the User DN account. This password is stored in Nextcloud's database and used whenever Nextcloud queries LDAP. Keep this password strong and rotate it periodically.

Base DN (required): This is the starting point for searches in your LDAP tree. Example: dc=example,dc=com or cn=Users,dc=example,dc=com. If you are unsure, ask your LDAP admin or test with your LDAP browser tool. Entering a base DN that is too narrow (e.g., ou=finance,dc=example,dc=com) will limit Nextcloud to searching only that branch, which means users in other branches cannot log in.

At the bottom of the form, you will see an "Edit LDAP Query" link. Leave this alone unless you have advanced LDAP filter requirements. The defaults work well for most Active Directory and OpenLDAP setups.

Once you fill these fields, Nextcloud automatically tests the connection. If the test fails, you will see an error message: "Failed to bind to LDAP server" or "Cannot resolve host". Check:

• Host and port are correct and match your LDAP server config.
• User DN and password are correct.
• Network connectivity to the LDAP server is working (test with nc -zv from your Nextcloud server as described in Prerequisites).
• If using LDAPS, the SSL certificate is valid, not expired, and trusted by Nextcloud.
• Firewall rules allow outbound connections from your Nextcloud server to the LDAP server on the specified port.

Step 3: Set Login Attributes

Click the "Login Attributes" tab. This is where you tell Nextcloud which LDAP attribute to use as the username when someone logs in.

Nextcloud lists several options:

• sAMAccountName (Active Directory users): The Windows username. Example: jsmith. This is the most common choice for AD environments because it is the name people use to log into Windows.
• userPrincipalName (Active Directory): The full UPN. Example: jsmith@example.com. Some teams prefer this because it matches email and reduces confusion.
• uid (OpenLDAP users): The unique identifier in OpenLDAP. Example: jsmith.
• mail: The email address. This works if email is unique and always populated in LDAP.

Only one attribute should be checked. If you have Active Directory, check sAMAccountName unless your team logs in with email addresses, in which case use userPrincipalName. If you have OpenLDAP, check uid. The attribute you choose becomes the Nextcloud username. So if you choose sAMAccountName and your AD user is "jsmith", the Nextcloud username will be jsmith. If you change this later, existing users will not be auto-migrated; you will have to manually reassign files or recreate accounts. So choose carefully.

Nextcloud also has an option to "update user profile from LDAP" (further down on this tab). If checked, fields like displayName, mail, and phone number are synced from LDAP on every login. This keeps Nextcloud user profiles current when your LDAP directory is updated. Recommended: keep this checked so you do not have to manually update user profiles.

Step 4: Configure User and Group Mapping

Click the "Users" tab. This is where you define which LDAP users Nextcloud will import.

You will see:

• User Object Classes (required): The LDAP object class that identifies a user. For Active Directory, this is "user". For OpenLDAP, it is typically "inetOrgPerson" or "posixAccount". Enter the correct value for your directory type. If you enter the wrong object class, Nextcloud will find zero users and logins will fail.
• LDAP User Filter: An LDAP filter that narrows down which users to import. The default is usually (&(|(uid={login})(mail={login}))(objectclass=inetorgperson)). This is complex syntax, but it means "match users by uid or email address where object class equals inetorgperson". For Active Directory, Nextcloud usually auto-sets a reasonable default; leave it unless you have a specific need (e.g., importing only users in certain departments or excluding test accounts).

If you want to import groups, click the "Groups" tab:

• Group Object Classes: For AD, usually "group". For OpenLDAP, "groupOfNames" or "groupOfUniqueNames".
• Group Member Filter: Defines how group membership is determined. Defaults are reasonable for most setups.

For most small-to-medium deployments, the default filters work fine. Do not adjust them unless you understand LDAP filter syntax or have a specific business need. Incorrect filters are a common cause of login failures.

Once you save these settings, Nextcloud begins querying your LDAP server in the background. The first login from an LDAP user triggers account creation in Nextcloud. Subsequent logins check LDAP again and update profile fields if "update user profile from LDAP" is enabled.

Step 5: Test Your Configuration Before Rolling Out

You now have a working LDAP integration. Test it thoroughly before rolling out to your entire team:

1. Log out of the admin account.
2. On the Nextcloud login page, enter an LDAP username (e.g., jsmith) and the password that user has in Active Directory or LDAP.
3. If login succeeds, you are done. The user account has been created in Nextcloud automatically.
4. If login fails, see the Troubleshooting section below.

For deeper testing, use Nextcloud's OCC (command-line) tools. These are powerful for debugging and exist in the official docs but are often missed in setup guides. From the Nextcloud server, run:

sudo -u www-data php occ ldap:test-config s01

Replace s01 with your LDAP connection name (the default is s01). This tests whether Nextcloud can connect and bind to your LDAP server. If it fails, you will see a detailed error message. This is more reliable than the web interface test because it shows the raw LDAP response.

Also try:

sudo -u www-data php occ ldap:test-user-settings s01 jsmith

This tests whether Nextcloud can find the user "jsmith" in LDAP and applies your filter logic. It returns the user's attributes as Nextcloud sees them (username, email, display name, etc.). This is invaluable for debugging why a user is not being imported or why a login fails.

Troubleshooting Common Issues

Connection fails with "Cannot resolve host": The LDAP server hostname is not reachable or does not exist in DNS. Check: hostname spelling is correct, your Nextcloud server can reach the LDAP server (test with: ping ldap.example.com or nc -zv ldap.example.com 389), and if Nextcloud is on managed hosting, confirm outbound connections to your LDAP server are allowed by the hosting provider's firewall.

LDAPS connection fails with "certificate verify failed": The SSL certificate on your LDAP server is invalid, expired, or self-signed and Nextcloud does not trust it. Options: import the LDAP server's CA certificate into Nextcloud's PHP environment (this varies by OS; consult your hosting provider or system admin), use unencrypted LDAP (port 389) only if you are on a trusted internal network or VPN (not recommended for security), or ask your LDAP admin to use a certificate signed by a publicly trusted Certificate Authority.

Login fails but test connection succeeds: Your connection to LDAP works, but user login fails. Usually the filter logic or login attribute is wrong. Run: sudo -u www-data php occ ldap:test-user-settings s01 <username>. If it returns "user not found", the LDAP filter is rejecting the user. Check: User Object Classes match your directory's actual object class ("user" for AD, "inetOrgPerson" for OpenLDAP), the Login Attribute (sAMAccountName vs uid) actually exists on the user's LDAP record, and the Base DN includes the user's location in the directory tree.

Login succeeds but email is not synced: If you checked "update user profile from LDAP", Nextcloud looks for a mail attribute. If the LDAP user has no mail attribute set in the directory, Nextcloud cannot sync it and the user will have no email in Nextcloud. Check the LDAP record manually (using LDAP Admin or ldapsearch tool) to confirm the mail attribute exists and is populated. If it does not exist, either populate it in LDAP or disable email sync.

LDAP connection times out during login: Your LDAP server is slow or the network is congested. Nextcloud waits for LDAP responses during login, so a slow directory makes logins slow for all users. Options: add more RAM or CPU to your LDAP server (if you manage it), use a closer LDAP replica (if available in your infrastructure), or if using managed Nextcloud hosting, ask your provider about LDAP optimization or dedicated networking.

Users cannot log in after I change the login attribute: Changing the login attribute (e.g., from sAMAccountName to userPrincipalName) does not rename existing Nextcloud accounts. If you had a user "jsmith" and change to UPN-based login, new logins will use "jsmith@example.com", creating a duplicate account. Fix this by reverting to the original login attribute or manually merging user accounts (advanced; requires database access or Nextcloud support). Avoid changing the login attribute after the first user login.

Frequently Asked Questions

What happens if my LDAP server goes down? Users cannot log in to Nextcloud. However, if they were previously logged in and have session cookies, they stay logged in until the session expires. But new logins and session refreshes will fail. Nextcloud has a fallback: the OCC command ldap:set-config s01 ldapConfigurationActive 0 disables LDAP temporarily, allowing you to log in as admin via local credentials. But regular users still will not be able to log in. As a precaution, keep at least one admin account (not LDAP-managed) in Nextcloud for emergencies. Alternatively, use managed Nextcloud hosting where the provider monitors LDAP availability and alerts you to problems.

Can I use the same LDAP configuration with multiple Nextcloud instances? Yes, each instance can connect to the same LDAP server independently. The LDAP server does not care how many Nextcloud instances query it. However, user accounts are stored separately in each Nextcloud database, so changes in one instance do not affect the other. If you have multiple Nextcloud deployments, you will need to configure LDAP in each one.

Is LDAPS required? No, but it is strongly recommended. LDAPS (port 636) encrypts the entire connection, including passwords. Unencrypted LDAP (port 389) sends credentials in the clear where they can be intercepted. If your LDAP server is on the internet or untrusted networks, use LDAPS. If it is on a private VPN or internal network, unencrypted LDAP is acceptable but LDAPS is still safer.

How often does Nextcloud check LDAP? Nextcloud queries LDAP only during login and password changes. It does not continuously sync in the background. If you add a user to LDAP, they cannot log in until Nextcloud sees them during login. There is no automatic "pull" sync; Nextcloud is reactive and queries LDAP on demand.

What if I have both LDAP users and local Nextcloud users? Allowed. LDAP users log in with LDAP credentials; local users log in with Nextcloud passwords. However, mixing them makes administration harder because you have to manage two identity systems. Best practice: choose one system (all LDAP or all local) and stick with it.

How do I disable LDAP without removing user accounts? Run: sudo -u www-data php occ ldap:set-config s01 ldapConfigurationActive 0. This disables the LDAP connection but keeps user accounts in Nextcloud. Users revert to local password login. To re-enable: sudo -u www-data php occ ldap:set-config s01 ldapConfigurationActive 1.

Which LDAP attributes are required? Only the login attribute (sAMAccountName, uid, or userPrincipalName) is required. The optional attributes like mail and displayName are synced only if the user's LDAP record has them populated. If a user's email is blank in LDAP, Nextcloud will not set an email for that user. This is not a failure; it is expected behavior.

The Bottom Line

Nextcloud LDAP integration is straightforward if you have the prerequisites: network connectivity to your LDAP server, a service account, and the PHP LDAP module installed. Configure the Server tab with your hostname, port, and credentials; set Login Attributes to match your directory type; and test with an LDAP user login and OCC commands. The real burden is operational: your Nextcloud must reach your LDAP server on port 389 or 636 over the network, and if that connection breaks, users cannot log in.

If you want LDAP reliability without managing the infrastructure yourself, consider Nextcloud managed hosting where the provider handles the LDAP integration and network setup for you.