Merge pull request #167 from matmair/sso

SSO docs

docs/admin/SSO.md

@@ -0,0 +1,25 @@
+---
+title: InvenTree Single Sign On
+---
+
+## Single Sign On
+
+InvenTree provides the possibility to use 3rd party services to authenticate users. This functionality makes use of [django-allauth](https://django-allauth.readthedocs.io/en/latest/) and supports a wide array of OpenID and OAuth [provider](https://django-allauth.readthedocs.io/en/latest/providers.html).
+
+### Configuration
+
+To use SSO you have to:
+1. Enable the needed providers in the [config file](../start/config.md#Single-Sign-on).
+1. Add the required client configurations in the `SocialApp` app in the [admin interface](../admin/admin.md).
+1. Enable SSO for the users in the [dynamic settings](../admin/settings.md).
+
+### Security Consideration
+
+You should use SSL for your website if you want to use this feature. Also set your callback-endpoints to `https://` addresses to reduce the risk of leaking user's tokens.
+
+Tokens for authenticating the users to the providers they registered with are saved in the database.  
+So ensure your database is protected and not open to the internet.  
+Make sure all users with admin privileges have sufficient passwords - they can read out your client configurations with providers and all auth-tokens from users.
+
+Never share your installs secret key!
+

docs/admin/settings.md

@@ -0,0 +1,27 @@
+---
+title: InvenTree Admin Settings
+---
+
+## Admin Settings
+
+InvenTree ships with a lot of dynamic settings. While [config file settings](../start/config.md) require access to the webserver on which InvenTree is hosted these can be changed by all admins of the server.
+
+### User Settings
+
+Change how InvenTree appears to the individual user and configure login and user data.
+
+### Global Settings
+
+#### Login Settings
+
+Change how logins, password-forgot, signups are handled.
+
+| Settings Name | Type | Description | Default |
+| --- | --- | --- | --- |
+| Enable registration | True/False | Enable self-registration for users on the login-pages | False |
+| Enable SSO | True/False | Enable SSO on the login-pages | False |
+| Enable password forgot | True/False | Enable password forgot function on the login-pages.<br><br>This will let users reset their passwords on their own. For this feature to work you need to configure E-mail | True |
+| E-Mail required | True/False | Require user to supply e-mail on signup.<br><br>Without a way (e-mail) to contact the user notifications and security features might not work! | False |
+| Mail twice | True/False | On signup ask users twice for their mail | False |
+| Password twice | True/False | On signup ask users twice for their password | True |
+| Auto-fill SSO users | True/False | Automatically fill out user-details from SSO account-data.<br><br>If this feature is enabled the user is only asked for their username, first- and surname if those values can not be gathered from their SSO profile. This might lead to unwanted usernames bleading over. | True |

docs/start/config.md

@@ -122,11 +122,32 @@ By default, uploaded media files are stored in the local directory `/home/invent
 
 Alternatively this location can be specified with the `INVENTREE_MEDIA_ROOT` environment variable.
 
-## Other Options
+## Authentication
+
+### Single Sign on
+
+SSO backends for all wanted providers need to be added to the config file as a list under the key `social_backends`. The correct backend-name can be found in django-allauths [configuration documentation](https://django-allauth.readthedocs.io/en/latest/installation.html#django).
+
+If the selected providers need additional settings they must be added as dicts under the key `social_providers`. The correct settings can be found in the django-allauths [provider documentation](https://django-allauth.readthedocs.io/en/latest/providers.html).
+
+!!! note "You are not done"
+    SSO still needs credentials for all providers and has to be enabled in the [settings](../admin/settings.md)!
+
+
+### Login Options
+
+The login-experience can be altered with the following settings:
+
+| Environment Variable | Settings File | Description | Default |
+| --- | --- | --- | --- |
+| INVENTREE_LOGIN_CONFIRM_DAYS | login_confirm_days | Duration for which confirmation links are valid | 3 |
+| INVENTREE_LOGIN_ATTEMPTS | login_attempts | Count of allowed login attempts before blocking user | 5 |
 
 ### Authentication Backends
 
-Custom authentication backends can be used by specifying them here
+Custom authentication backends can be used by specifying them here. These can for example be used to add [LDAP / AD login](https://django-auth-ldap.readthedocs.io/en/latest/) to InvenTree
+
+## Other Options
 
 ### Middleware
 

mkdocs.yml

@@ -96,7 +96,9 @@ nav:
     - Context Variables: report/context_variables.md
   - Admin:
     - Admin Interface: admin/admin.md
+    - Settings: admin/settings.md
     - User Permissions: admin/permissions.md
+    - Single Sign on: admin/SSO.md
     - Export Data: admin/export.md
     - Import Data: admin/import.md
     - Python Shell: admin/shell.md