From dfd1072b158814fdac8021484883bc4f567c9bd3 Mon Sep 17 00:00:00 2001 From: Kay0u Date: Wed, 30 Dec 2020 14:34:31 +0100 Subject: [PATCH] Update the sso doc with the new permissions system --- README.md | 164 +++++++++++++++++++++++++++++++++------------- conf.json.example | 2 +- 2 files changed, 121 insertions(+), 45 deletions(-) diff --git a/README.md b/README.md index c180a89..21c3647 100644 --- a/README.md +++ b/README.md @@ -74,102 +74,178 @@ If you use YunoHost, you may want to edit the `/etc/ssowat/conf.json.persistent` Only the `portal_domain` SSOwat configuration parameters is required, but it is recommended to know the others to fully understand what you can do with it. -#### portal_domain +--------------- + +### portal_domain Domain of the authentication portal. It has to be a domain, IP addresses will not work with SSOwat (**Required**). -#### portal_path +--------------- + +### portal_path URI of the authentication portal (**default**: `/ssowat/`). This path **must** end with “`/`”. -#### portal_port +--------------- + +### portal_port Web port of the authentication portal (**default**: `443` for `https`, `80` for `http`). -#### portal_scheme +--------------- + +### portal_scheme Whether authentication should use secure connection or not (**default**: `https`). -#### domains +--------------- + +### domains List of handled domains (**default**: similar to `portal_domain`). -#### ldap_host +--------------- + +### ldap_host LDAP server hostname (**default**: `localhost`). -#### ldap_group +--------------- + +### ldap_group LDAP group to search in (**default**: `ou=users,dc=yunohost,dc=org`). -#### ldap_identifier +--------------- + +### ldap_identifier LDAP user identifier (**default**: `uid`). -#### ldap_attributes +--------------- + +### ldap_attributes User's attributes to fetch from LDAP (**default**: `["uid", "givenname", "sn", "cn", "homedirectory", "mail", "maildrop"]`). -#### ldap_enforce_crypt +--------------- + +### ldap_enforce_crypt Let SSOwat re-encrypt weakly-encrypted LDAP passwords into the safer sha-512 (crypt) (**default**: `true`). -#### allow_mail_authentication +--------------- + +### allow_mail_authentication Whether users can authenticate with their mail address (**default**: `true`). -#### login_arg +--------------- + +### login_arg URI argument to use for cross-domain authentication (**default**: `sso_login`). -#### additional_headers +--------------- + +### additional_headers Array of additionnal HTTP headers to set once user is authenticated (**default**: `{ "Remote-User": "uid" }`). -#### session_timeout +--------------- + +### session_timeout The session expiracy time limit in seconds, since the last connection (**default**: `86400` / one day). -#### session_max_timeout +--------------- + +### session_max_timeout The session expiracy time limit in seconds (**default**: `604800` / one week). -#### protected_urls +--------------- -List of priorily protected URLs and/or URIs (**by default, every URL is protected**). - -#### protected_regex - -List of regular expressions to be matched against URLs **and** URIs to protect them. - -#### skipped_urls - -List of URLs and/or URIs that will not be affected by SSOwat. This must be a JSON array, and SSOwat automatically adds itself to it. - -#### skipped_regex - -List of regular expressions to be matched against URLs **and** URIs to ignore them. - -#### unprotected_urls - -List of URLs and/or URIs that will not be affected by SSOwat **unless a user is authenticated**. - -#### unprotected_regex - -List of regular expressions to be matched against URLs **and** URIs to ignore them **unless a user is authenticated**. - -#### redirected_urls +### redirected_urls Array of URLs and/or URIs to redirect and their redirect URI/URL (**example**: `{ "/": "example.org/subpath" }`). -#### redirected_regex +--------------- + +### redirected_regex Array of regular expressions to be matched against URLs **and** URIs and their redirect URI/URL (**example**: `{ "example.org/megusta$": "example.org/subpath" }`). -#### users +--------------- -2-level array containing usernames and their allowed URLs along with an app name (**example**: `{ "kload": { "kload.fr/myapp/": "My App" } }`). - -#### default_language +### default_language Language code used by default in views (**default**: `en`). + +--------------- + +### permissions + +The list of permissions depicted as follows: + +```json +"myapp.main": { + "auth_header": true, + "label": "MyApp", + "public": true, + "show_tile": true, + "uris": [ + "example.tld/myapp" + ], + "users": [ + "JaneDoe", + "JohnDoe" + ] +}, +"myapp.admin": { + "auth_header": true, + "label": "MyApp (admin)", + "public": false, + "show_tile": false, + "uris": [ + "example.tld/myapp/admin" + ], + "users": [ + "JaneDoe" + ] +}, +"myapp.api": { + "auth_header": false, + "label": "MyApp (api)", + "public": true, + "show_tile": false, + "uris": [ + "re:domain%.tld/%.well%-known/.*" + ], + "users": [] +} +``` + +#### auth_header + +Does the SSO add an authentication header that allows certain apps to connect automatically? (**True by default**) + +#### label + +A user-friendly name displayed in the portal and in the administration panel to manage permission. (**By convention it is of the form: Name of the app (specificity of this permission)**) + +#### public + +Can a person who is not connected to the SSO have access to this authorization? + +#### show_tile + +Display or not the tile in the user portal. + +#### uris + +A list of url attatched to this permission, a regex url start with `re:`. + +#### users + +A list of users which is allowed to access to this permission. If `public`. diff --git a/conf.json.example b/conf.json.example index 01f710c..aceaea9 100644 --- a/conf.json.example +++ b/conf.json.example @@ -26,7 +26,7 @@ }, "myapp.admin": { "auth_header": true, - "label": "MyApp (api)", + "label": "MyApp (admin)", "public": false, "show_tile": false, "uris": [