diff --git a/.env.template b/.env.template index a69619c3b..1b5c11e9b 100644 --- a/.env.template +++ b/.env.template @@ -48,8 +48,12 @@ SHOPPING_MIN_AUTOSYNC_INTERVAL=5 GUNICORN_MEDIA=0 # allow authentication via reverse proxy (e.g. authelia), leave of if you dont know what you are doing -# docs: https://github.com/vabene1111/recipes/tree/develop/docs/docker/nginx-proxy%20with%20proxy%20authentication +# see docs for more information https://vabene1111.github.io/recipes/features/authentication/ # when unset: 0 (false) REVERSE_PROXY_AUTH=0 +# allows you to setup o auth providers +# see docs for more information https://vabene1111.github.io/recipes/features/authentication/ +# SOCIAL_PROVIDERS = allauth.socialaccount.providers.github, allauth.socialaccount.providers.nextcloud, + diff --git a/docs/features/authentication.md b/docs/features/authentication.md new file mode 100644 index 000000000..8ca94937a --- /dev/null +++ b/docs/features/authentication.md @@ -0,0 +1,108 @@ +Besides the normal django username and password authentication this application supports multiple +methods of central account management and authentication. + +## Allauth +[Django Allauth](https://django-allauth.readthedocs.io/en/latest/index.html) is an awesome project that +allows you to use a [huge number](https://django-allauth.readthedocs.io/en/latest/providers.html) of different +authentication providers. + +They basically explain everything in their documentation, but the following is a short overview on how to get started. + +!!! warning "Public Providers" + If you choose Google, Github or any other publicly available service as your authentication provider anyone + with an account on that site can create an account on your installation. + A new account does not have any permission but it is still **not recommended** to give public access to + your installation. + +Choose a provider from the [list](https://django-allauth.readthedocs.io/en/latest/providers.html) and install it using the environment variable `SOCIAL_PROVIDERS` as shown +in the example below. + +```ini +SOCIAL_PROVIDERS = allauth.socialaccount.providers.github, allauth.socialaccount.providers.nextcloud, +``` + +After that, use your superuser account to configure your authentication backend. +Open the admin page and do the following + +1. Select `Sites` and create a new site with the URL of your installation. +2. Create a new `Social Application` with the required information as stated in the provider documentation of allauth. +3. Make sure to add your site to the list of available sites + +Now the provider is configured and you should be able to sign up and sign in using the provider. + +## Reverse Proxy Authentication +!!! Info "Community Contributed Tutorial" + This tutorial was provided by a community member. Since I do not use reverse proxy authentication, I cannot provide any + assistance should you choose to use this authentication method. + +In order use proxy authentication you will need to: + +1. Set `REVERSE_PROXY_AUTH=1` in the `.env` file +2. Update your nginx configuration file + +Using any of the examples above will automatically generate a configuration file inside a docker volume. +Use `docker volume inspect recipes_nginx` to find out where your volume is stored. + +!!! warning "Configuration File Volume" + The nginx config volume is generated when the container is first run. You can change the volume to a bind mount in the + warning `docker-compose.yml`, but then you will need to manually create it. See section `Volumes vs Bind Mounts` below + for more information. + +The following example shows a configuration for Authelia: + +``` +server { + listen 80; + server_name localhost; + + client_max_body_size 16M; + + # serve static files + location /static/ { + alias /static/; + } + # serve media files + location /media/ { + alias /media/; + } + + # Authelia endpoint for authentication requests + include /config/nginx/auth.conf; + + # pass requests for dynamic content to gunicorn + location / { + proxy_set_header Host $host; + proxy_pass http://web_recipes:8080; + + # Ensure Authelia is specifically required for this endpoint + # This line is important as it will return a 401 error if the user doesn't have access + include /config/nginx/authelia.conf; + + auth_request_set $user $upstream_http_remote_user; + proxy_set_header REMOTE-USER $user; + } + + # Required to allow user to logout of authentication from within Recipes + # Ensure the below is changed to actual the authentication url + location /accounts/logout/ { + return 301 http:///logout + } +} +``` + +Please refer to the appropriate documentation on how to setup the reverse proxy, authentication, and networks. + +Ensure users have been configured for Authelia, and that the endpoint recipes is pointed to is protected but +available. + +There is a good guide to the other additional files that need to be added to your nginx set up at +the [Authelia Docs](https://docs.authelia.com/deployment/supported-proxies/nginx.html). + +Remember to add the appropriate environment variables to `.env` file (example for nginx proxy): + +``` +VIRTUAL_HOST= +LETSENCRYPT_HOST= +LETSENCRYPT_EMAIL= +PROXY_HEADER= +``` diff --git a/docs/install/docker.md b/docs/install/docker.md index ba6421b00..7b96d2234 100644 --- a/docs/install/docker.md +++ b/docs/install/docker.md @@ -290,84 +290,6 @@ to the host system and from there into the nginx container. This is not really a clean solution, but I could not find any better alternative that provided the same amount of usability. If you know of any better way, feel free to open an issue. -### Using Proxy Authentication - -!!! Info "Community Contributed Tutorial" - This tutorial was provided by a community member. Since I do not use reverse proxy authentication, I cannot provide any - assistance should you choose to use this authentication method. - -In order use proxy authentication you will need to: - -1. Set `REVERSE_PROXY_AUTH=1` in the `.env` file -2. Update your nginx configuration file - -Using any of the examples above will automatically generate a configuration file inside a docker volume. -Use `docker volume inspect recipes_nginx` to find out where your volume is stored. - -!!! warning "Configuration File Volume" - The nginx config volume is generated when the container is first run. You can change the volume to a bind mount in the - warning `docker-compose.yml`, but then you will need to manually create it. See section `Volumes vs Bind Mounts` below - for more information. - -The following example shows a configuration for Authelia: - -``` -server { - listen 80; - server_name localhost; - - client_max_body_size 16M; - - # serve static files - location /static/ { - alias /static/; - } - # serve media files - location /media/ { - alias /media/; - } - - # Authelia endpoint for authentication requests - include /config/nginx/auth.conf; - - # pass requests for dynamic content to gunicorn - location / { - proxy_set_header Host $host; - proxy_pass http://web_recipes:8080; - - # Ensure Authelia is specifically required for this endpoint - # This line is important as it will return a 401 error if the user doesn't have access - include /config/nginx/authelia.conf; - - auth_request_set $user $upstream_http_remote_user; - proxy_set_header REMOTE-USER $user; - } - - # Required to allow user to logout of authentication from within Recipes - # Ensure the below is changed to actual the authentication url - location /accounts/logout/ { - return 301 http:///logout - } -} -``` - -Please refer to the appropriate documentation on how to setup the reverse proxy, authentication, and networks. - -Ensure users have been configured for Authelia, and that the endpoint recipes is pointed to is protected but -available. - -There is a good guide to the other additional files that need to be added to your nginx set up at -the [Authelia Docs](https://docs.authelia.com/deployment/supported-proxies/nginx.html). - -Remember to add the appropriate environment variables to `.env` file (example for nginx proxy): - -``` -VIRTUAL_HOST= -LETSENCRYPT_HOST= -LETSENCRYPT_EMAIL= -PROXY_HEADER= -``` - ### Volumes vs Bind Mounts Since I personally prefer to have my data where my `docker-compose.yml` resides, bind mounts are used in the example diff --git a/mkdocs.yml b/mkdocs.yml index 8ac44c0fc..d491d4c08 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -31,6 +31,7 @@ nav: - Features: - Tempalating: features/templating.md - Shopping: features/shopping.md + - Authentication: features/authentication.md - Storages and Sync: features/external_recipes.md - System: - Updating: system/updating.md diff --git a/recipes/settings.py b/recipes/settings.py index 121ccddb4..80ab28d17 100644 --- a/recipes/settings.py +++ b/recipes/settings.py @@ -9,6 +9,7 @@ https://docs.djangoproject.com/en/2.0/topics/settings/ For the full list of settings and their values, see https://docs.djangoproject.com/en/2.0/ref/settings/ """ +import ast import os import random import string @@ -82,10 +83,14 @@ INSTALLED_APPS = [ 'allauth', 'allauth.account', 'allauth.socialaccount', - 'allauth.socialaccount.providers.github', 'cookbook.apps.CookbookConfig', ] +SOCIAL_PROVIDERS = os.getenv('SOCIAL_PROVIDERS').split(',') if os.getenv('SOCIAL_PROVIDERS') else [] +INSTALLED_APPS = INSTALLED_APPS + SOCIAL_PROVIDERS + +SOCIALACCOUNT_PROVIDERS = ast.literal_eval(os.getenv('SOCIALACCOUNT_PROVIDERS') if os.getenv('SOCIALACCOUNT_PROVIDERS') else '{}') + MIDDLEWARE = [ 'django.middleware.security.SecurityMiddleware', 'whitenoise.middleware.WhiteNoiseMiddleware', @@ -109,9 +114,6 @@ SITE_ID = int(os.getenv('ALLAUTH_SITE_ID', 1)) ACCOUNT_ADAPTER = 'cookbook.helper.AllAuthCustomAdapter' -# disable account creation using allauth -ACCOUNT_ALLOW_SIGNUPS = bool(int(os.getenv('ACCOUNT_ALLOW_SIGNUPS', False))) - if REVERSE_PROXY_AUTH: MIDDLEWARE.append('recipes.middleware.CustomRemoteUser') AUTHENTICATION_BACKENDS.append('django.contrib.auth.backends.RemoteUserBackend')