Installing Yunohost Apps with Automatic LDAP Single Sign-On

Desired Outcome

Install a Yunohost-supported application—such as Nextcloud or Gitea—so that it authenticates against the server's central LDAP directory. Users created in the Yunohost admin panel should log in to the app without separate credentials, and the app should respect Yunohost user/group permissions automatically.

Prerequisites

• A Yunohost server running v4.x or v11.x (Debian 11/12 base) with root or sudo access via SSH or the web admin interface.
• A domain configured with valid DNS records pointing to the server (A/AAAA for the host, plus any subdomains you plan to use).
• The target app must be listed in the official catalog. Verify availability with:

yunohost app list --official | grep -i nextcloud

Run this on the Yunohost server as root or a user with sudo. The command returns the exact app_id (e.g., nextcloud) required for installation.

Installation Procedure

Command-Line Install

As root on the Yunohost server:

yunohost app install nextcloud

The installer prompts for:

• Domain — choose from domains already configured in Yunohost (e.g., cloud.example.com).
• Path — typically / for a dedicated subdomain, or a subpath like /nextcloud if sharing a domain.
• Admin user — an existing Yunohost user who will become the app's initial administrator.

After confirming, the installer runs unattended and performs the following automatically:

1. Creates a dedicated LDAP service account for the app (e.g., cn=nextcloud,ou=apps,dc=yunohost,dc=org).
2. Configures the app's native LDAP plugin with the service account credentials and search base.
3. Generates an nginx vhost protected by SSOwat (Yunohost's SSO reverse proxy), inserting an auth_ldap block that points to the local LDAP socket.
4. Provisions a database (PostgreSQL for Nextcloud, MySQL for Gitea) and runs the app's setup hooks.
5. Registers the app in the user portal (SSOwat) so it appears on the user's dashboard after login.

Web Admin Alternative

In the Yunohost web admin (https://your-domain/yunohost/admin), navigate to Applications → Install, search for the app, and fill the same domain/path/admin fields. The backend actions are identical.

Expected Checks After Installation

1. Verify App Registration

yunohost app list --installed | grep nextcloud

Output should show nextcloud with status installed and the chosen domain/path.

2. Confirm LDAP Service Account Exists

ldapsearch -x -H ldapi:/// -b "ou=apps,dc=yunohost,dc=org" cn=nextcloud

Run as root. You should see an entry with cn=nextcloud, objectClass: ynhService, and a userPassword attribute (hashed).

3. Inspect nginx SSOwat Configuration

grep -A 5 "auth_ldap" /etc/nginx/conf.d/cloud.example.com.d/nextcloud.conf

Expected block (paths vary by domain/app):

auth_ldap "Yunohost SSO";
auth_ldap_servers ldap_server;
auth_ldap_binddn "cn=nextcloud,ou=apps,dc=yunohost,dc=org";
auth_ldap_binddn_passwd "";
auth_ldap_url ldapi:///ou=users,dc=yunohost,dc=org?uid?sub?(objectClass=inetOrgPerson);

4. Check App-Level LDAP Config (Nextcloud Example)

grep -A 10 "'ldap'" /var/www/nextcloud/config/config.php

Look for an auto-generated section resembling:

'ldap' =>
  array (
    'host' => 'localhost',
    'port' => 389,
    'base' => 'ou=users,dc=yunohost,dc=org',
    'userFilter' => '(objectClass=inetOrgPerson)',
    'loginFilter' => '(&(objectClass=inetOrgPerson)(uid=%uid))',
    'binddn' => 'cn=nextcloud,ou=apps,dc=yunohost,dc=org',
    'bindpw' => '',
  ),

5. Test the SSO Flow

curl -I -L https://cloud.example.com/

Expected sequence:

1. 302 Found redirect to https://cloud.example.com/yunohost/sso/?r=/
2. After providing a valid session cookie (from a browser login), 200 OK with the Nextcloud dashboard.

In a browser, log in to the Yunohost user portal (https://your-domain/yunohost/sso/) with a standard Yunohost user, then visit the app URL. You should land directly in the app without a second login prompt.

Recovery Options

Failed or Unwanted Installation

Remove the app and all associated artifacts (LDAP entries, nginx config, database, files):

yunohost app remove nextcloud --purge

Run as root. The --purge flag ensures cleanup of the LDAP service account, database, and nginx snippets. After fixing any DNS or port conflicts, re-run the install command.

Upgrading an App

yunohost app upgrade nextcloud

This re-runs the app's upgrade hooks, which may update the LDAP plugin configuration or database schema. Check /var/log/yunohost/nextcloud.log for success.

Backup and Restore

yunohost backup create --apps nextcloud --name pre-upgrade-$(date +%F)

Backups include app data, database dumps, and LDAP state. Restore with yunohost backup restore .

Limitations and Cautions

Official Catalog Only

Only apps from the official catalog (yunohost app list --official) guarantee the automatic LDAP/SSOwat integration described here. Community apps (listed via --community) often require manual SSO configuration and are not covered by this guide.

Changing Domain or Path After Install

Do not edit nginx or app configs directly. Use the dedicated command:

yunohost app change-url nextcloud --domain cloud2.example.com --path /cloud

This updates the nginx vhost, the LDAP service account's registered URLs, and the SSOwat portal entry in one transaction.

LDAP Schema Stability

Yunohost uses standard posixAccount and inetOrgPerson object classes. Custom LDAP attributes you add manually are not preserved across Yunohost version upgrades. Rely on the standard attributes for any app integration.

Public Endpoints (Webhooks, Federation)

SSOwat protects the entire app path by default. Apps that need public endpoints (e.g., Nextcloud federation, Gitea webhooks) require explicit unprotected regex rules. Edit the app's nginx snippet:

nano /etc/nginx/conf.d/cloud.example.com.d/nextcloud.conf

Add a location block before the main SSOwat-protected block:

location ~ ^/nextcloud/(ocs|apps/activity/api/v2/heartbeat) {
    auth_ldap off;
    allow all;
    # proxy_pass or other directives as needed
}

Reload nginx: systemctl reload nginx. Test the public endpoint with curl -I https://cloud.example.com/nextcloud/ocs/v2.php/apps/files_sharing/api/v1/shares — it should return 200 or 401 (app-level auth) without redirecting to SSOwat.

Verification Checklist

Check	Command	Success Indicator
App listed as installed	yunohost app list --installed	App appears with correct domain/path
LDAP service account exists	ldapsearch -x -H ldapi:/// -b "ou=apps,dc=yunohost,dc=org" cn=nextcloud	Entry returned with ynhService objectClass
nginx uses LDAP auth	grep auth_ldap /etc/nginx/conf.d/.d/nextcloud.conf	auth_ldap block present
App config references LDAP	grep -A 10 "'ldap'" /var/www/nextcloud/config/config.php	Auto-generated LDAP array with correct binddn
SSO redirect works	curl -I -L https:///	302 to /yunohost/sso/, then 200 after login

Version Assumptions

This guide assumes Yunohost 4.x or 11.x on Debian 11 (Bullseye) or 12 (Bookworm). The LDAP base DN (dc=yunohost,dc=org) and service account location (ou=apps) are defaults; verify with yunohost domain list and ldapsearch -x -H ldapi:/// -b "dc=yunohost,dc=org" if your installation uses a custom suffix.