How Yunohost Centralizes App Access With Manifests and SSOwat

Running several self-hosted apps usually means several logins, separate user stores, and manual reverse proxy rules. Yunohost treats that as a packaging problem, not an app-by-app problem. Apps declare how they want to be installed and how they should be accessed, and Yunohost enforces access centrally through a reverse proxy without changing app code.

The contract between Yunohost and an app

Yunohost builds on Debian and automates domain, user, SSL certificate and app lifecycle tasks via a unified CLI and web admin. The official app catalog relies on a manifest file per app. The manifest declares metadata, dependencies, install/upgrade/remove scripts, backup hooks and SSO integration points.

The manifest makes deployment repeatable. Instead of hand-editing Nginx and creating local users, the installer reads the manifest and provisions the app in a predictable location under /etc/yunohost/apps/<app>. Inspecting the manifest shows what the packager promised about permissions and SSO.

On the server shell as root or via sudo, check the release and core components first:

yunohost --version
yunohost tools diagnosis

Expected checks are a version string and a diagnosis summary for core components. Risk is minimal for read-only commands. For a specific app, view its manifest:

cat /etc/yunohost/apps/<app>/manifest.yml

Look for sections that declare permissions, SSO settings and scripts. The file is declarative, not executable, so reading it is safe.

SSOwat as a centralized gatekeeper

SSOwat is Yunohost's reverse proxy that sits in front of apps. It enforces single sign-on, maps HTTP requests to Yunohost user sessions, and applies per-app permission rules without modifying app code.

Because the proxy handles authentication, apps can remain largely unaware of Yunohost users. The proxy injects session context and blocks requests that do not match the permission set declared in the manifest. This avoids credential sprawl and keeps auth policy in one place.

Permissions are managed centrally as Yunohost users and groups. A typical app exposes three roles: public visibility, authenticated access, and admin. The web admin Apps > Permissions section shows and edits per-app user and group assignments. Changes here affect access immediately via SSOwat.

Worked example: verify the integration for one app

Pick an installed app name, for example <app>. In the web admin, open Apps, select the app, then Permissions. Note which groups are allowed for main and admin access.

On the server, inspect the manifest to confirm what was declared:

cat /etc/yunohost/apps/<app>/manifest.yml

Compare the declared permission names with what appears in the web admin. Mismatches can indicate a partial SSO integration or a third-party package that opted out of hooks.

Backups are system-wide. A backup bundles configuration, users and app data with metadata for selective restore and migration:

yunohost backup create
yunohost backup list

Run these as root or via sudo. Risk is disk usage and I/O load during creation. The list command lets you verify archive metadata without restoring.

Trade-offs and limitations

Centralization adds operational coupling. Changes to Yunohost core can affect all installed apps. Manifest schema and SSO integration details are version-sensitive and have evolved across major releases, so assumptions apply to recent stable lines.

Not all third-party apps fully support SSO or permission hooks. Apps may opt out or implement partial integration, leading to inconsistent access control. When an app does not integrate, you may still need separate credentials for that app.

Verification is practical. Run yunohost --version and yunohost tools diagnosis to confirm the release. Inspect /etc/yunohost/apps/<app>/manifest.yml for declared permissions and SSO settings. Use the web admin Permissions view to confirm assignments. Create a test backup and list archives to verify metadata handling.