Intégration SSO/LDAP

Un aspect puissant de YunoHost est que les applications sont destinées à être intégrées à la pile SSO/LDAP, de sorte que les utilisateurs connectés sur le portail utilisateur de YunoHost puissent être directement connectés à chaque application sans avoir à créer un compte dans chacune d'elles ni à avoir à recréer un compte. -connectez-vous à chaque application à chaque fois.

Il convient de souligner qu’il y a ici deux aspects différents :

• l'intégration LDAP, ce qui signifie que les comptes d'utilisateurs de l'application sont directement mappés aux comptes d'utilisateurs YunoHost
• l'intégration SSO, ce qui signifie qu'un utilisateur connecté sur le portail utilisateur YunoHost est également automatiquement connecté sur l'application.

Parfois, l'intégration LDAP est possible, mais pas l'intégration SSO (même si l'inverse serait vraiment étrange car l'intégration LDAP est quelque peu requise pour que le SSO fonctionne)

Le système SSO est géré par SSOwat et gère également le système de « permissions » qui définit si un utilisateur (ou un visiteur anonyme) peut ou non accéder à l'application.

LDAP integration

LDAP est un standard de facto lorsqu'il s'agit de partager une base de données de comptes d'utilisateurs commune entre plusieurs applications, d'où son utilisation dans le contexte de YunoHost.

Cependant, chaque application implémente la prise en charge LDAP à sa manière (ou non) et doit être dotée de paramètres pour communiquer réellement avec la base de données LDAP de YunoHost, généralement via son fichier de configuration. Il est conseillé de rechercher des exemples concrets d'applications les mettant en œuvre (telles que Nextcloud, Wekan...), mais vous devrez généralement fournir :

• LDAP host: localhost / 127.0.0.1
• LDAP port: 389
• Base DN : dc=yunohost,dc=org
• User DN : ou=users,dc=yunohost,dc=org
• Search filter: (&(|(objectclass=posixAccount))(uid=%uid)(permission=cn=__APP__.main,ou=permission,dc=yunohost,dc=org)) (this makes sure that only people with the appropriate YunoHost/SSowat permission can access the app)
• Username attribute: uid
• Display name attribute: displayname
• Email attribute: mail

TO-DO/FIX-ME: plus d'explications ? Que manque-t-il?

SSO integration

This documentation apply to YunoHost>=12. On YunoHost <12 the header was a bit different but the idea was the same.

Internally, SSOwat will on-the-fly inject theses different headers:

Name	Description	Protected over header injection from clients (a client try with a request to override the header and be logged in with a different user)	Header name for app which provide HTTP server and nginx transfert the request	How to get with php App
The username	the username of the authenticated user	Yes	YNH_USER	with getallheaders()["Ynh-User"] or $_SERVER["HTTP_YNH_USER"]
User email	the email of the authenticated user. Could be usefull for some app wich require an email for the username. Can be also used by some apps which populate all user infomration from the HTTP header instead of LDAP.	Yes	YNH_USER_EMAIL	with getallheaders()["Ynh-User-Email"] or $_SERVER["HTTP_YNH_USER_EMAIL"]
User full name	The full name of the user. The full name of the user. Which is mostly used by some apps which populate all user infomration from the HTTP header instead of LDAP.	Yes	YNH_USER_FULLNAME	with getallheaders()["Ynh-User-Fullname"] or $_SERVER["HTTP_YNH_USER_FULLNAME"]
The HTTP Basic Auth Headers	Like Authorization: Basic <base64credentials>. If used we should be sure that the app check the credential (user and password) before to validate the authentication. It's mainly used by apps which need the credential to authenticate to a internal service. By example most of webmail need the credential to pass the correct credential to the mail server.	No. A client can send a header and will be passed to the application. It's why the application must check the credential to be sure that the passed passord are correct.	Authorization	with getallheaders()["Authorization"] or $_SERVER["HTTP_AUTHORIZATION"]

Usage

For many application, like django, you will need configure the YNH_USER header, as the header to trust, to authenticate the user. For php apps it will be most of case the header Ynh-User.

And for some app which need the auth basic header, you generally don't need to set the header name as the Authorization header name is normalized.

Specific case

App wich reuse the auth basic header to authenticate to an internal service

Currently you don't need any specific setup on YunoHost side. Since YunoHost provide the header needed, the application should be able to use it correclty. Depending of the application, some configuration could be needed.

Application wich provide an API

Some app, like Nextcloud or SOGo provide an service like Caldav, Cardav or Webdav, the client will need to send the basic authentication and the nginx must transmit this authentication header to the serivice which will validate the authentication. Currently to make it working correctly you need to set a following app settings this way:

ynh_app_setting_set --key=protect_against_basic_auth_spoofing --value=false

This will say to YunoHost that for this app we can safely transmit auth basic header from the client to the application.

If you need to change this behavior after the application installation, you can set the option with:

sudo yunohost app setting <my_app> protect_against_basic_auth_spoofing -v false

Then you must regenerate the SSOwat configuration with:

sudo yunohost app ssowatconf

And, finally, you need to reload NGINX configuration with:

sudo systemctl reload nginx.service

Configuring SSOwat permissions for the app

Les autorisations SSOwat sont configurées à l'aide de la ressource « autorisation » dans le fichier manifest.toml de votre application.

Le cas échéant, vous pouvez créer des autorisations « secondaires » pour votre application, par exemple pour autoriser uniquement un groupe spécifique de personnes à accéder à l'interface utilisateur d'administration de l'application. Par exemple :

[resources.permissions]

# This configures the main permission, i.e. general access to `https://domain.tld/$app/`
# Initial access is defined using the `init_main_permission` install question.
main.url = "/"

# This configures an additional "admin" permission regarding access to `https://domain.tld/$app/admin`
admin.url = "/admin"
admin.show_tile = false    # This means that this permission won't correspond to a tile in YunoHost's user portal
admin.allowed = "admins"   # Initialize the access for the "admins" group ... You can also use an install question called `init_admin_permission` to let the server admin choose this.

Consultez la page sur les ressources de l'application pour la description complète du comportement et des propriétés.

Déconnexion de l'application ou déconnexion de YunoHost

Un problème connu est que parfois, la déconnexion des applications YunoHost ne déconnectera pas les utilisateurs de chaque application. C'est par exemple le cas de Nextcloud, car il utilise ses propres cookies d'authentification qui ne sont pas effacés lorsque les gens se déconnectent de YunoHost. Ce n’est pas anodin à corriger.

De même, la déconnexion de l'application ne déconnecte pas nécessairement entièrement les personnes de YunoHost (ce qui est plus acceptable que de cliquer sur Se déconnecter et... de ne pas être déconnecté du tout car vous êtes toujours connecté sur le SSO, donc connecté sur l'application). Certaines applications YunoHost intègrent des correctifs personnalisés de sorte que le processus de déconnexion de l'application redirige automatiquement vers https://domain.tld/yunohost/sso/?action=logout qui les déconnecte.