diff --git a/docs/admin/SSO.md b/docs/admin/SSO.md new file mode 100644 index 0000000..e1353ed --- /dev/null +++ b/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! + diff --git a/docs/admin/settings.md b/docs/admin/settings.md new file mode 100644 index 0000000..ca845f8 --- /dev/null +++ b/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.

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.

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.

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 | diff --git a/docs/start/config.md b/docs/start/config.md index 65d669d..f7a1c5b 100644 --- a/docs/start/config.md +++ b/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 diff --git a/mkdocs.yml b/mkdocs.yml index 0ead960..cfbaa71 100644 --- a/mkdocs.yml +++ b/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