2013-10-15 10:11:39 +02:00
SSOwat
======
2020-06-16 17:48:56 +02:00
A simple LDAP SSO for NGINX, written in Lua.
2013-10-15 10:11:39 +02:00
2017-01-28 06:23:51 +01:00
< a href = "https://translate.yunohost.org/engage/yunohost/?utm_source=widget" >
< img src = "https://translate.yunohost.org/widgets/yunohost/-/287x66-white.png" alt = "Translation status" / >
< / a >
2017-04-03 01:35:16 +02:00
Issues
------
2020-06-16 17:48:56 +02:00
- [Please report issues to the YunoHost bugtracker ](https://github.com/YunoHost/issues ).
2017-04-03 01:35:16 +02:00
2013-10-15 10:16:42 +02:00
Requirements
------------
2020-06-16 17:48:56 +02:00
- `nginx-extras` from Debian wheezy-backports
- `lua-json`
- `lua-ldap`
- `lua-filesystem`
- `lua-socket`
- `lua-rex-pcre`
2013-10-16 12:00:08 +02:00
2013-10-16 20:47:37 +02:00
**OR**
2013-10-16 12:00:08 +02:00
2020-06-16 17:48:56 +02:00
- "OpenResty" flavored NGINX: https://openresty.org/
- `lua-ldap`
- `lua-filesystem`
- `lua-socket`
- `lua-rex-pcre`
2013-10-15 10:16:42 +02:00
2013-10-16 20:47:37 +02:00
Installation
------------
2013-10-16 20:50:02 +02:00
* Fetch the repository
2013-10-16 20:50:36 +02:00
2013-10-16 20:47:37 +02:00
```bash
2019-09-27 12:09:07 +02:00
git clone https://github.com/YunoHost/SSOwat /etc/ssowat
2013-10-16 20:50:02 +02:00
```
2013-10-16 20:50:36 +02:00
2020-06-16 17:48:56 +02:00
NGINX configuration
2014-04-17 16:07:52 +02:00
-------------------
2013-10-16 20:47:37 +02:00
2020-06-16 17:48:56 +02:00
* Add SSOwat's NGINX configuration (`http{}` scope)
2013-10-16 20:50:36 +02:00
2013-10-16 20:47:37 +02:00
```bash
nano /etc/nginx/conf.d/ssowat.conf
```
2013-10-15 10:11:39 +02:00
2013-10-15 10:13:34 +02:00
```nginx
2013-10-26 15:29:51 +02:00
lua_shared_dict cache 10m;
2013-10-16 20:47:37 +02:00
init_by_lua_file /etc/ssowat/init.lua;
access_by_lua_file /etc/ssowat/access.lua;
2013-10-15 10:11:39 +02:00
2013-10-15 10:13:34 +02:00
```
2013-10-16 20:47:37 +02:00
2014-04-17 16:07:52 +02:00
You can also put the `access_by_lua_file` directive in a `server{}` scope if you want to protect only a vhost.
SSOwat configuration
--------------------
```
2016-05-07 23:57:17 +02:00
mv /etc/ssowat/conf.json.example /etc/ssowat/conf.json
2014-04-17 16:07:52 +02:00
nano /etc/ssowat/conf.json
```
If you use YunoHost, you may want to edit the `/etc/ssowat/conf.json.persistent` file, since the `/etc/ssowat/conf.json` will often be overwritten.
2014-04-17 16:24:48 +02:00
## Available parameters
2020-06-16 17:48:56 +02:00
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.
2014-04-17 16:24:48 +02:00
2020-12-30 14:34:31 +01:00
---------------
### portal_domain
2014-04-17 16:24:48 +02:00
2020-06-16 17:48:56 +02:00
Domain of the authentication portal. It has to be a domain, IP addresses will not work with SSOwat (**Required**).
2014-04-17 16:24:48 +02:00
2020-12-30 14:34:31 +01:00
---------------
### portal_path
2014-04-17 16:24:48 +02:00
2017-10-02 20:04:46 +02:00
URI of the authentication portal (**default**: `/ssowat/` ). This path **must** end with “`/`”.
2014-04-17 16:24:48 +02:00
2020-12-30 14:34:31 +01:00
---------------
### portal_port
2014-04-17 16:24:48 +02:00
2020-06-16 17:48:56 +02:00
Web port of the authentication portal (**default**: `443` for `https` , `80` for `http` ).
2014-04-17 16:24:48 +02:00
2020-12-30 14:34:31 +01:00
---------------
### portal_scheme
2014-04-17 16:24:48 +02:00
2020-06-16 17:48:56 +02:00
Whether authentication should use secure connection or not (**default**: `https` ).
2014-04-17 16:24:48 +02:00
2020-12-30 14:34:31 +01:00
---------------
### domains
2014-04-17 16:24:48 +02:00
2020-06-16 17:48:56 +02:00
List of handled domains (**default**: similar to `portal_domain` ).
2014-04-17 16:24:48 +02:00
2020-12-30 14:34:31 +01:00
---------------
### ldap_host
2014-04-17 16:24:48 +02:00
2020-06-16 17:48:56 +02:00
LDAP server hostname (**default**: `localhost` ).
2014-04-17 16:24:48 +02:00
2020-12-30 14:34:31 +01:00
---------------
### ldap_group
2014-04-17 16:24:48 +02:00
2020-06-16 17:48:56 +02:00
LDAP group to search in (**default**: `ou=users,dc=yunohost,dc=org` ).
2014-04-17 16:24:48 +02:00
2020-12-30 14:34:31 +01:00
---------------
### ldap_identifier
2014-04-17 16:24:48 +02:00
2020-06-16 17:48:56 +02:00
LDAP user identifier (**default**: `uid` ).
2014-04-17 16:24:48 +02:00
2020-12-30 14:34:31 +01:00
---------------
### ldap_attributes
2014-04-17 16:24:48 +02:00
2020-06-16 17:48:56 +02:00
User's attributes to fetch from LDAP (**default**: `["uid", "givenname", "sn", "cn", "homedirectory", "mail", "maildrop"]` ).
2014-04-17 16:24:48 +02:00
2020-12-30 14:34:31 +01:00
---------------
### ldap_enforce_crypt
2017-09-16 19:22:47 +02:00
2020-06-16 17:48:56 +02:00
Let SSOwat re-encrypt weakly-encrypted LDAP passwords into the safer sha-512 (crypt) (**default**: `true` ).
2017-09-16 19:22:47 +02:00
2020-12-30 14:34:31 +01:00
---------------
### allow_mail_authentication
2014-04-17 16:24:48 +02:00
2020-06-16 17:48:56 +02:00
Whether users can authenticate with their mail address (**default**: `true` ).
2014-04-17 16:24:48 +02:00
2020-12-30 14:34:31 +01:00
---------------
### login_arg
2014-04-17 16:24:48 +02:00
2020-06-16 17:48:56 +02:00
URI argument to use for cross-domain authentication (**default**: `sso_login` ).
2014-04-17 16:24:48 +02:00
2020-12-30 14:34:31 +01:00
---------------
### additional_headers
2014-04-17 16:24:48 +02:00
2020-06-16 17:48:56 +02:00
Array of additionnal HTTP headers to set once user is authenticated (**default**: `{ "Remote-User": "uid" }` ).
2014-04-17 16:24:48 +02:00
2020-12-30 14:34:31 +01:00
---------------
### session_timeout
2014-04-17 16:24:48 +02:00
2020-06-16 17:48:56 +02:00
The session expiracy time limit in seconds, since the last connection (**default**: `86400` / one day).
2014-04-17 16:24:48 +02:00
2020-12-30 14:34:31 +01:00
---------------
### session_max_timeout
2014-04-17 16:24:48 +02:00
2020-06-16 17:48:56 +02:00
The session expiracy time limit in seconds (**default**: `604800` / one week).
2014-04-17 16:24:48 +02:00
2020-12-30 14:34:31 +01:00
---------------
2014-04-17 16:24:48 +02:00
2020-12-30 14:34:31 +01:00
### redirected_urls
2014-04-17 16:24:48 +02:00
2020-12-30 14:34:31 +01:00
Array of URLs and/or URIs to redirect and their redirect URI/URL (**example**: `{ "/": "example.org/subpath" }` ).
2014-04-17 16:24:48 +02:00
2020-12-30 14:34:31 +01:00
---------------
2014-04-17 16:24:48 +02:00
2020-12-30 14:34:31 +01:00
### redirected_regex
2014-04-17 16:24:48 +02:00
2020-12-30 14:34:31 +01:00
Array of regular expressions to be matched against URLs **and** URIs and their redirect URI/URL (**example**: `{ "example.org/megusta$": "example.org/subpath" }` ).
2014-04-17 16:24:48 +02:00
2020-12-30 14:34:31 +01:00
---------------
2014-04-17 16:24:48 +02:00
2020-12-30 14:34:31 +01:00
### default_language
2014-04-17 16:24:48 +02:00
2020-12-30 14:34:31 +01:00
Language code used by default in views (**default**: `en` ).
2014-04-17 16:24:48 +02:00
2020-12-30 14:34:31 +01:00
---------------
### 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": []
}
```
2014-04-17 16:24:48 +02:00
2020-12-30 14:34:31 +01:00
#### auth_header
2014-04-17 16:24:48 +02:00
2020-12-30 14:34:31 +01:00
Does the SSO add an authentication header that allows certain apps to connect automatically? (**True by default**)
2014-04-17 16:24:48 +02:00
2020-12-30 14:34:31 +01:00
#### label
2014-04-17 16:24:48 +02:00
2020-12-30 14:34:31 +01:00
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)**)
2014-04-17 16:24:48 +02:00
2020-12-30 14:34:31 +01:00
#### public
2014-04-17 16:24:48 +02:00
2020-12-30 14:34:31 +01:00
Can a person who is not connected to the SSO have access to this authorization?
2014-04-17 16:24:48 +02:00
2020-12-30 14:34:31 +01:00
#### show_tile
2014-04-17 16:24:48 +02:00
2020-12-30 14:34:31 +01:00
Display or not the tile in the user portal.
2014-04-17 16:07:52 +02:00
2020-12-30 14:34:31 +01:00
#### uris
2014-05-12 18:11:49 +02:00
2020-12-30 14:34:31 +01:00
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` .