Yunohost LDAP‑backed SSO Architecture: Requirements, Minimal Design, and Operational Checks

Problem: Need for Centralized Authentication Across Multiple Web Apps

When hosting several applications on a single Yunohost server, each app should not maintain its own user database. Administrators require a single source of truth for credentials, password policies, and user lifecycle management, while keeping apps isolated from direct LDAP access.

Takeaway: A Minimal LDAP‑Backed SSO Design Meets These Needs

The smallest suitable architecture uses the Debian‑packed OpenLDAP server running locally, accessed only through Yunohost’s SSO portal (SSOWat). Apps trust SSOWat as a proxy and receive a signed session token or a REMOTE_USER header after a successful LDAP bind.

Requirements

• Centralized user authentication for all hosted web apps.
• Support for LDAP bind operations (simple authentication).
• Ability to enforce password policies via LDAP overlays.
• User provisioning and de‑provisioning through the Yunohost admin portal.

Smallest Suitable Design

Components

1. OpenLDAP server – installed as the slapd daemon, listening on localhost:389 (LDAP) and localhost:636 (LDAPS). Base DN typically dc=yunohost,dc=org.
2. SSO portal (SSOWat) – a Python‑based service that terminates TLS from the browser, receives clear‑text credentials, performs an LDAP bind, and on success issues a signed session token or sets REMOTE_USER for the downstream app.
3. Web applications – configured in their manifest to use the SSO portal; they never query LDAP directly.

Data Flow

Browser → TLS → SSOWat (receives user:pass) → LDAP bind (localhost) → SSOWat validates → SSOWat returns session token / REMOTE_USER → App

Trust and Data Boundaries

• LDAP server stores credential hashes and is bound to 127.0.0.1 only; no external network exposure.
• SSOWat is the sole entity that sees clear‑text passwords, and only over the TLS‑encrypted HTTP channel from the browser.
• Apps receive an opaque token or header; they never see passwords or perform LDAP queries.

Operational Checks

Service Status

Verify that the LDAP daemon is active:

# Run as root or with sudo
systemctl status slapd

Expected output includes active (running).

TLS Certificate for SSOWat

Check the certificate used by the SSO portal (typically managed by Yunohost’s nginx):

sudo yunohost tools ssowat diagnose

Look for lines indicating a valid certificate and no warnings about self‑signed or expired certs.

Log Auditing

Successful authentication appears in /var/log/yunohost/ssowat.log:

sudo grep "successful authentication" /var/log/yunohost/ssowat.log

Failed binds are logged with LDAP bind failed.

LDAP Data Backup

Yunohost’s backup mechanism includes the LDAP directories; you can confirm inclusion:

sudo yunohost backup list
# Then inspect a backup archive for /etc/ldap/slapd.d and /var/lib/ldap

Failure Modes

• LDAP downtime – all SSO‑protected apps reject login; users see authentication errors.
• TLS misconfiguration – browsers show certificate warnings; if the admin forces HTTP fallback, credentials travel in clear text.
• Corrupted LDAP database – may cause bind loops or repeated authentication prompts.
• Excessive bind attempts – if the ppolicy overlay is enabled, accounts may be temporarily locked after a threshold.

Conditions That Would Change the Design

• External Identity Provider – adopting a SAML or OIDC IdP (e.g., Keycloak) would replace the local LDAP with a federation layer; SSOWat would act as a relay to the IdP.
• Multi‑host scaling – a single local LDAP becomes a bottleneck; a replicated LDAP cluster or an external LDAP service would be required.
• Container‑based app isolation – moving apps into separate containers might shift authentication to a sidecar proxy (e.g., OAuth2‑proxy) rather than the monolithic SSOWat.

Practical Verification Steps

1. Deploy a fresh Yunohost stable instance.
2. In the admin UI, go to Users > LDAP and confirm the server reports listening on localhost:389 and localhost:636.
3. Create a test user (e.g., testuser) via the UI.
4. From the host, verify the entry:

# Replace dc=yunohost,dc=org with your actual base DN if different
ldapsearch -x -LLL -H ldapi:/// -b 'dc=yunohost,dc=org' '(uid=testuser)' dn

Then test a simple bind (you will be prompted for the password):

ldapsearch -x -H ldap://localhost -D 'uid=testuser,dc=yunohost,dc=org' -W -b 'dc=yunohost,dc=org' '(objectClass=*)' 1.1

A successful bind returns an entry without error.

1. Log in to an SSO‑protected app (e.g., Roundcube) at https:///yunohost/sso/ using the test user’s credentials.
2. After login, check /var/log/yunohost/ssowat.log for a line containing successful authentication for that user.
3. Confirm that no LDAP bind failed messages appear for the same timestamp.

Limitations and How to Check Them

• Local LDAP only – the design assumes the LDAP server stays on the same host. To verify, ensure netstat -tlnp | grep slapd shows only 127.0.0.1 listeners.
• App manifest compliance – if an app tries to query LDAP directly, it will break the trust boundary. You can audit by searching for ldapsearch or ldap_bind in the app’s source; any such call indicates a violation.
• Backup/restore hostname change – restoring to a different domain requires updating the LDAP base DN and SSOWat trust settings. After a restore, run sudo yunohost tools ssowat diagnose and verify the displayed base DN matches the new domain.

---

By following the requirements, minimal design, trust boundaries, and verification steps outlined above, administrators can operate a reliable LDAP‑backed SSO in Yunohost and recognize when architectural changes become necessary.