Nextcloud SSO: SAML, OIDC, and LDAP Setup

Nextcloud single sign-on lets your users log in with their corporate identity provider instead of managing Nextcloud passwords separately. Three methods work: SAML, OpenID Connect (OIDC), and LDAP. This guide covers setup for each, with examples using Keycloak, Authentik, and Microsoft Entra ID, plus the common admin-lockout mistakes most people make. If you would rather not handle infrastructure yourself, Opsily offers managed Nextcloud hosting with SSO pre-configured.

Understanding Nextcloud SSO: SAML, OIDC, and LDAP

Single sign-on means your users authenticate through an external identity provider instead of Nextcloud's local user database. Three protocols handle this:

SAML 2.0 is the oldest and most established. It's XML-based and works well in enterprise environments. You install the "SSO & SAML" app and point it at a SAML identity provider. Keycloak and Authentik both support SAML. The tradeoff: SAML is verbose and the setup UI in Nextcloud requires manually copying metadata between systems.

OpenID Connect (OIDC) is newer and simpler. It's built on OAuth 2.0 and works via redirects and JSON. You install the "user_oidc" app and point it at an OIDC provider. The advantage: better attribute mapping. You can pull email, name, and groups from the provider. The tradeoff: group provisioning (auto-syncing groups from your IdP to Nextcloud) is not yet supported in user_oidc, so you manage groups manually in Nextcloud. Keycloak, Authentik, Entra ID, and Google all support OIDC.

LDAP is directory-based and works via connection pooling. You use Nextcloud's built-in LDAP module (no extra app). This is your choice if you have an existing LDAP server and want directory sync to happen automatically. Active Directory, FreeIPA, and Samba all speak LDAP. The tradeoff: LDAP is synchronous, not real-time. If you change a user's group in LDAP, Nextcloud syncs it on next login, not immediately.

For most setups, OIDC with user_oidc is the fastest path. It avoids the XML ceremony of SAML and gives you better attribute control than LDAP. We will cover all three here, with detailed examples.

Prerequisites and Safety Checks

Before you enable SSO, lock in five things or you will lock yourself out.

First: HTTPS is mandatory. Nextcloud will refuse to process OIDC/SAML callbacks over HTTP. If you are testing locally without HTTPS, use a reverse proxy with a self-signed cert, or skip SSO for now. This is not negotiable.

Second: Create an admin account in your identity provider. Right now, before you touch Nextcloud. This is your escape hatch. If SSO breaks, you log in as this admin user locally.

Third: Enable "Allow multiple user-backends" in Nextcloud. Go to Settings > User management > Authentication. Check "Allow multiple user-backends". This means Nextcloud keeps the local user table alive alongside SSO. Without it, you become dependent on your IdP being up. If it goes down, no one logs in, not even admins. With multiple backends enabled, you can always fall back to local login using the ?direct=1 query parameter.

Fourth: Test your identity provider first. If you are using Keycloak or Authentik, bring it up, create a test user, and log in manually to make sure it works. Do not debug Keycloak setup AND Nextcloud setup at the same time.

Fifth: Understand redirect URIs. Your identity provider sends users back to Nextcloud after login via a "redirect URI". Nextcloud expects this to be https://your-domain/index.php/apps/user_saml/acs for SAML or https://your-domain/index.php/apps/user_oidc/code for OIDC. If it does not match exactly (including protocol, domain, path, and trailing slash), SSO fails. We will cover this in each provider section.

Method 1: SAML SSO Setup with the SSO & SAML App

SAML is synchronous and metadata-driven. Your Nextcloud acts as a "service provider" (the application), and your identity provider acts as the "identity provider" (the system of record). They exchange XML metadata to establish trust.

Step 1: Install the SSO & SAML app.

Log in as admin. Go to Apps > Disabled. Search for "SAML". Click "SSO & SAML authentication". Install it. You will see a new entry under Settings > Administration > "SSO & SAML authentication".

Step 2: Get Nextcloud's metadata.

Go to Settings > Administration > SSO & SAML authentication. Scroll to the bottom. You will see a link to your "Service provider metadata". Copy this URL: https://your-domain/index.php/apps/user_saml/metadata. This is what you paste into your identity provider. Keep this window open.

Step 3: Configure your identity provider.

This varies by provider. You need to extract three pieces of information from your IdP:

Single Sign-On URL (SSO Service URL): The endpoint where Nextcloud POSTs authentication requests.
Single Logout URL (SLO Service URL): The endpoint for logout (optional but recommended).
X.509 Certificate: The public cert your IdP uses to sign assertions. Copy this as a PEM file.

Step 4: Configure Nextcloud SAML settings.

Back in Settings > Administration > SSO & SAML authentication, fill in:

Identity Provider metadata URL: If your IdP provides a metadata endpoint, paste it here. Nextcloud will fetch the SSO URL and certificate automatically. This is the easiest path.
OR manually enter SSO Service URL: https://idp.example.com/sso
Identity Provider X.509 Certificate: Paste the public cert in PEM format.
Identifier Format: Leave as "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified" unless your IdP requires something else.
Attribute Mapping: Map the SAML assertion fields to Nextcloud fields. Most commonly: email to email address, username or uid to Nextcloud user ID, displayname to full name.

Step 5: Create a test user in your identity provider and log out.

Create a new SAML user (not admin). Log out of Nextcloud (/logout). You should see a login screen with an "SSO" button or auto-redirect to your IdP. Log in as the test user.

If it works, you will land in Nextcloud with the test account created automatically. If it fails, check the Nextcloud error log (data/nextcloud.log) for assertion validation errors.

Step 6: Lock down direct login (optional but recommended).

By default, Nextcloud still shows a "Login with username and password" form alongside the SAML SSO button. This can be a security risk if you want to force SSO. Go back to Settings > Administration > SSO & SAML authentication and check "Disable direct login" under "Security settings". Now only SSO login is available.

Method 2: OpenID Connect Setup with the user_oidc App

OIDC is asynchronous and redirect-based. It is simpler than SAML because it reuses OAuth 2.0 flows.

Step 1: Install the user_oidc app.

Log in as admin. Go to Apps > Disabled. Search for "OIDC" or "OpenID Connect". Install "OpenID Connect user backend" (user_oidc).

Step 2: Get your OIDC provider credentials.

You need:

Client ID: A public identifier for Nextcloud.
Client Secret: A private key. Keep this secret.
Discovery Endpoint: Usually https://idp.example.com/.well-known/openid-configuration. This tells Nextcloud where to find all the OIDC endpoints.

You will create these in your identity provider's admin console.

Step 3: Configure Nextcloud OIDC.

Go to Settings > Administration > OpenID Connect. Click "Add Provider".

Fill in:

Provider name: A friendly label (e.g., "Keycloak").
Client ID: Copy from your IdP.
Client Secret: Copy from your IdP. Be careful not to paste whitespace.
Discovery endpoint: Your IdP's .well-known/openid-configuration URL. Nextcloud will fetch all other endpoints from here.
Redirect URI: Nextcloud fills this in automatically as https://your-domain/index.php/apps/user_oidc/code. Verify this matches what you registered in your IdP.

Step 4: Configure attribute mapping.

Below the discovery endpoint, you will see "User ID mapping field". This is critical. Choose one of:

"Sub" (unique subject identifier): The default. OIDC calls this sub. It's a unique ID that never changes, even if the user's email does. Safe choice.
"Email": If you want Nextcloud usernames to be email addresses. Risk: if the user's email changes in the IdP, Nextcloud creates a new account instead of updating the old one.
"Preferred username": Uses the OIDC claim preferred_username (usually the login username in the IdP). Good if your IdP uses short usernames.

Most guides recommend "Sub" because it avoids account duplication. But if you have existing local users named after email addresses, switching to "Sub" will create duplicate accounts. Plan this carefully before your first login.

Continue with:

Mail claim: Usually email (the OIDC claim that holds the user's email).
Display name claim: Usually name (the OIDC claim for full name).
Group claim: If your IdP sends group membership in an OIDC claim, enter the claim name here (e.g., groups). Nextcloud will read it and display groups in the user profile. Note: auto-syncing groups to Nextcloud is not yet supported, so this is informational only.

Step 5: Test login.

Log out. You should see "Sign in with <Provider Name>" button. Click it. You will be redirected to your IdP. Log in as a test user. You will land in Nextcloud. Check the user name and email: they should match the IdP.

If login fails, check the Nextcloud error log for "state parameter mismatch" (expired session), "redirect_uri mismatch" (URL does not match IdP config), or "invalid client" (Client ID or Secret wrong).

Keycloak Example: Step-by-Step OIDC Setup

Keycloak is an open-source identity provider. We will set it up to work with Nextcloud's user_oidc app.

Prerequisites: Keycloak 26 or later, running on HTTPS.

Step 1: Create a realm and client in Keycloak.

Create a new realm (Administration > Realms > Create Realm). Name it "Nextcloud". Click "Create".

Inside the Nextcloud realm, go to Clients > Create client.

Client type: OpenID Connect
Client ID: nextcloud (or any identifier you want; use this in Nextcloud config)
Name: Nextcloud

Step 2: Configure the client.

Go to the "Nextcloud" client. Under "Access settings":

Root URL: https://your-nextcloud-domain
Valid Redirect URIs: https://your-nextcloud-domain/index.php/apps/user_oidc/code
Valid post logout redirect URIs: https://your-nextcloud-domain (optional, for logout)
Web Origins: https://your-nextcloud-domain

Save.

Step 3: Get the client secret.

Go to the Credentials tab. Copy the "Client secret" value. You will paste this into Nextcloud.

Step 4: Get the discovery endpoint.

Keycloak's OIDC discovery endpoint is https://keycloak.example.com/realms/Nextcloud/.well-known/openid-configuration. You will paste this into Nextcloud's OIDC config.

Step 5: Create a test user in Keycloak.

Go to Users > Create user. Set "Username" to a test value (e.g., "testuser"). Set "Email" if you want. Under "Credentials" > "Set password", set a temporary password. Check "Temporary" so the user is forced to change it on first login.

Step 6: Go to Nextcloud and add the Keycloak provider.

Go to Settings > Administration > OpenID Connect. Click "Add Provider".

Provider name: Keycloak
Client ID: nextcloud (what you set in Keycloak step 1)
Client Secret: (paste from Keycloak step 3)
Discovery endpoint: https://keycloak.example.com/realms/Nextcloud/.well-known/openid-configuration
User ID mapping field: Sub (recommended)
Mail claim: email
Display name claim: name

Click "Save".

Step 7: Test.

Log out of Nextcloud. You should see "Sign in with Keycloak" button. Click it. You will land in Keycloak login. Log in as the test user you created. You will be redirected back to Nextcloud, and the test user account will be created automatically.

If you get "redirect_uri_mismatch" error, double-check that the Redirect URI in Keycloak matches exactly (including the /index.php/ path and trailing slash).

Authentik Example: OIDC with User Provisioning

Authentik is an open-source identity provider built on Django. It is more minimal than Keycloak and focuses on OIDC/SAML simplicity.

Prerequisites: Authentik running on HTTPS.

Step 1: Create an OIDC provider in Authentik.

Go to Applications > Providers > Create. Choose "OAuth2/OpenID Provider".

Name: Nextcloud
Redirect URIs: https://your-nextcloud-domain/index.php/apps/user_oidc/code (one per line if multiple)
Client type: Confidential (generates a client secret)
Subject mode: Hashed User ID (recommended to avoid exposing internal user IDs) OR Fixed username (if you want Nextcloud usernames to be Authentik usernames)
Signing key: Defaults to the instance signing key. Leave as-is unless you have key rotation needs.

Under "Scopes", check: openid, email, profile. These scopes tell Nextcloud what claims to request.

Click "Create" or "Save".

Step 2: Create an application linked to the provider.

Go to Applications > Applications > Create.

Name: Nextcloud
Provider: Nextcloud (the OIDC provider you just created)
Authorization flow: Default authorization flow
Backend: openid

Save. You will be redirected to a page showing your OIDC provider details.

Step 3: Get the client credentials.

In the Authentik UI, go back to Applications > Providers > Nextcloud. You will see:

Client ID: Copy this.
Client Secret: Copy this. Trim any trailing whitespace; Authentik has had bugs with client secret padding.

Step 4: Get the discovery endpoint.

Authentik's OIDC discovery endpoint is https://authentik.example.com/application/o/.well-known/openid-configuration.

Step 5: Configure Nextcloud OIDC.

Go to Nextcloud Settings > Administration > OpenID Connect. Click "Add Provider".

Provider name: Authentik
Client ID: (paste from Authentik step 3)
Client Secret: (paste from Authentik step 3, and trim whitespace)
Discovery endpoint: https://authentik.example.com/application/o/.well-known/openid-configuration
User ID mapping field: Sub (if you used "Hashed User ID" subject mode) or Preferred username (if you used "Fixed username")
Mail claim: email
Display name claim: name

Step 6: Test.

Log out of Nextcloud. Click "Sign in with Authentik". Log in with an Authentik user. You will be created in Nextcloud automatically.

If the login fails and Authentik shows an error like "Invalid client secret", the issue is usually trailing whitespace in the secret. Copy it again, paste it directly without re-typing.

Microsoft Entra ID / Azure AD Setup

Microsoft Entra ID (formerly Azure AD) is Microsoft's cloud identity service. It uses SAML by default, though OIDC support has improved.

IMPORTANT: This is an enterprise integration. If you hit errors like "AADSTS700016", that is an Azure-specific error code that needs Azure-side debugging. The Nextcloud side is straightforward.

Step 1: Register Nextcloud in Entra ID.

Name: Nextcloud
What are you looking to do?: Integrate any other application you do not find in the gallery

Go to the app you created. In the left menu, go to Single sign-on. Choose SAML.

Step 2: Configure SAML for Nextcloud.

In the "Set up Single Sign-On with SAML" section:

Identifier (Entity ID): https://your-nextcloud-domain
Reply URL (Assertion Consumer Service URL): https://your-nextcloud-domain/index.php/apps/user_saml/acs

Save.

Step 3: Download the certificate.

Scroll down to "SAML Signing Certificate". Download the Base64 certificate. Open it in a text editor. You will see -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----. Copy the entire block.

Step 4: Get the SAML endpoints.

In the "Set up Single Sign-On with SAML" section, you will see:

Login URL (Single Sign-On Service URL): Copy this.
Logout URL: Copy this (optional).

Step 5: Configure Nextcloud SAML.

Go to Nextcloud Settings > Administration > SSO & SAML authentication.

Fill in:

Identity Provider Single Sign-On Service URL: (paste Login URL from step 4)
Identity Provider Single Logout Service URL: (paste Logout URL from step 4, if available)
Identity Provider X.509 Certificate: (paste certificate from step 3)

Under "Attribute Mapping":

Map "email" to the SAML claim name Azure sends (usually email or http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress)
Map "username" to the claim that holds the username (usually name or the UPN)

Check the Entra ID application's "Attributes & Claims" section to see exact claim names.

Step 6: Test.

Log out of Nextcloud. Click "SSO" or "Login with Microsoft Entra ID" (depending on your branding). You will be sent to Microsoft login. Log in with an Entra ID user. You will be redirected to Nextcloud and the user will be created automatically.

Common errors:

AADSTS700016 ("Application with ID X not found"): Entra ID does not recognize Nextcloud. Go back to the app in Entra ID and double-check the Entity ID matches what you entered in Nextcloud.
Assertion validation failed: The certificate might be expired or the signature does not match. Download the latest certificate from Entra ID.

Troubleshooting and Common Mistakes

Redirect URI mismatch ("invalid parameter: redirect_uri" or "redirect_uri_mismatch")

Your identity provider sent the user back to a URI that does not match what you told it to expect.

Check:

The protocol (http vs. https). OIDC/SAML require HTTPS.
The domain. If Nextcloud is at nextcloud.example.com, the redirect URI must be https://nextcloud.example.com/..., not localhost or an IP address.
The full path. For SAML it is /index.php/apps/user_saml/acs. For OIDC it is /index.php/apps/user_oidc/code. Copy-paste these; do not improvise.
Trailing slash. Some providers care, some do not. If it fails, try adding or removing the trailing slash.

Test by logging into your identity provider, going to your account settings, and looking at "Connected applications" or "Authorized apps" to see what Redirect URI it recorded.

HTTPS requirement enforced

Nextcloud will not process OIDC/SAML callbacks over HTTP. If you are testing locally, use a reverse proxy with a self-signed certificate, or use the OIDC allow http or SAML allow http config options (not recommended for production). The safest path: test in a staging environment with real HTTPS.

Admin lockout ("I enabled SSO and now I cannot log in")

You enabled SSO and created no local admin account in the identity provider. You disabled direct login and there is no escape hatch.

Recovery:

SSH into your Nextcloud server.
Run: php occ user:list to see existing users.
Create a local admin user: php occ user:add --admin-user localadmin
Set a password: php occ user:resetpassword localadmin
Log in with this local account using the direct-login URL: https://your-domain/?direct=1

Or, if you have direct login disabled:

Go to your Nextcloud config file (config/config.php).
Find the line for the SAML/OIDC backend and comment it out: // 'user_backends' => ['user_saml', 'OC\User\Database']
Restart PHP. Local login will now work. Create your local admin account, then re-enable the backend.

Discovery endpoint unreachable

Nextcloud tries to fetch the .well-known/openid-configuration endpoint from your OIDC provider and gets a 404 or timeout.

Check:

The endpoint URL. For Keycloak it is /realms/<realm>/.well-known/openid-configuration. For Authentik it is /application/o/.well-known/openid-configuration. For Entra ID it is https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration.
Network connectivity. Can Nextcloud reach your IdP? Are there firewall rules blocking traffic?
Provider status. Is the provider running and healthy? Try accessing the URL manually in a browser.

Account naming and hash collisions

You selected "Email" as the User ID mapping field, and now a user's email changed in the IdP. Nextcloud creates a new account instead of updating the old one, leaving the old account orphaned.

Prevent this by using "Sub" (unique subject identifier) or "Preferred username" (if your IdP guarantees username stability). If you already have collisions, you must manually move files from the old account to the new one, then delete the old account.

Group provisioning not working

You filled in a "Group claim" field in user_oidc, and now you expect groups to auto-sync from the IdP to Nextcloud. This is not supported in user_oidc yet. The claim is read and displayed, but Nextcloud does not auto-create or auto-assign groups. You must manage Nextcloud groups manually (Settings > Administration > Groups > Add group).

If you need automatic group sync, use LDAP backend instead. LDAP has native group-mapping support.

Frequently Asked Questions

What is the difference between SAML and OIDC for Nextcloud SSO?

SAML is XML-based and older, designed for enterprise federation. OIDC is JSON-based and simpler, built on OAuth 2.0. OIDC has better attribute mapping and a faster setup flow. SAML is more rigid but works well in highly standardized enterprises. For new setups, OIDC is faster. For existing enterprise federations, SAML is often already in place.

How do I set up Keycloak with Nextcloud?

Install the user_oidc app in Nextcloud. In Keycloak, create a realm and OIDC client with the Redirect URI https://your-nextcloud-domain/index.php/apps/user_oidc/code. Get the Client ID, Client Secret, and discovery endpoint. In Nextcloud, go to Settings > Administration > OpenID Connect, click Add Provider, and paste the credentials. Test with a Keycloak user account.

Can I use Authentik for Nextcloud single sign-on?

Yes. Install user_oidc in Nextcloud. In Authentik, create an OIDC provider and application. Register the Redirect URI https://your-nextcloud-domain/index.php/apps/user_oidc/code. Get the Client ID and Client Secret (trim whitespace). Add the provider in Nextcloud at Settings > Administration > OpenID Connect and test.

How do I enable the user_oidc app in Nextcloud?

Log in as admin. Go to Apps > Disabled. Search for "OpenID Connect" or "OIDC". Click "OpenID Connect user backend" and install it. It will appear in Settings > Administration > OpenID Connect.

What is a redirect URI and why does it break Nextcloud SSO?

A redirect URI is the URL your identity provider sends users back to after login. If it does not match exactly what you registered in your IdP, SSO fails with a "redirect_uri_mismatch" error. For SAML it must be https://your-domain/index.php/apps/user_saml/acs. For OIDC it must be https://your-domain/index.php/apps/user_oidc/code. Check protocol, domain, path, and trailing slashes.

How do I avoid locking myself out when enabling Nextcloud SSO?

Before enabling SSO: (1) Create an admin account in your identity provider. (2) Enable "Allow multiple user-backends" in Nextcloud (Settings > User management > Authentication). (3) Log in as a test user first, not admin. (4) Keep a recovery password for a local admin account. If SSO breaks, use ?direct=1 to bypass it.

Does Nextcloud SSO support group provisioning and auto-sync?

SAML and OIDC can read group claims from your identity provider and display them in user profiles. Automatic group creation and assignment is not yet supported in user_oidc. LDAP backend has native group-mapping support if auto-sync is required. Otherwise, manage Nextcloud groups manually.

How do I map user attributes (email, name, groups) in Nextcloud SSO?

For OIDC: In user_oidc, set "Mail claim" to the OIDC claim name (usually email), "Display name claim" to name, and "Group claim" to the claim name if groups are sent. For SAML: In SSO & SAML authentication, fill in "Attribute Mapping" with the SAML assertion field names for each Nextcloud field. Ask your IdP admin for the exact claim names they send.

The Bottom Line

Nextcloud SSO is straightforward if you plan the redirect URI first and enable multiple backends to avoid lockout. OIDC with user_oidc is the fastest path for new setups. SAML works if your enterprise already uses it. Plan for group management upfront: it is not automatic in OIDC, only in LDAP. If you need managed infrastructure, Opsily's Nextcloud hosting can handle SSO configuration for you.

Nextcloud SSO Setup Guide: SAML, OIDC, and LDAP