From 047f7c3619a30a24f6c9736f80491decc7d19b8e Mon Sep 17 00:00:00 2001 From: shamoon <4887959+shamoon@users.noreply.github.com> Date: Mon, 24 Feb 2025 09:23:20 -0800 Subject: [PATCH] Enhancement: support default groups for regular and social account signup (#9039) --- docs/configuration.md | 31 +++++++++- src/paperless/adapter.py | 38 ++++++++++-- src/paperless/apps.py | 6 ++ src/paperless/settings.py | 3 + src/paperless/signals.py | 18 ++++++ src/paperless/tests/test_adapter.py | 36 ++++++++++++ src/paperless/tests/test_signals.py | 91 +++++++++++++++++++++++++++++ 7 files changed, 216 insertions(+), 7 deletions(-) diff --git a/docs/configuration.md b/docs/configuration.md index 441d46105..391b97d13 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -557,6 +557,20 @@ This is for use with self-signed certificates against local IMAP servers. Settings this value has security implications for the security of your email. Understand what it does and be sure you need to before setting. +### Authentication & SSO {#authentication} + +#### [`PAPERLESS_ACCOUNT_ALLOW_SIGNUPS=`](#PAPERLESS_ACCOUNT_ALLOW_SIGNUPS) {#PAPERLESS_ACCOUNT_ALLOW_SIGNUPS} + +: Allow users to signup for a new Paperless-ngx account. + + Defaults to False + +#### [`PAPERLESS_ACCOUNT_DEFAULT_GROUPS=`](#PAPERLESS_ACCOUNT_DEFAULT_GROUPS) {#PAPERLESS_ACCOUNT_DEFAULT_GROUPS} + +: A list of group names that users will be added to when they sign up for a new account. Groups listed here must already exist. + + Defaults to None + #### [`PAPERLESS_SOCIALACCOUNT_PROVIDERS=`](#PAPERLESS_SOCIALACCOUNT_PROVIDERS) {#PAPERLESS_SOCIALACCOUNT_PROVIDERS} : This variable is used to setup login and signup via social account providers which are compatible with django-allauth. @@ -580,12 +594,25 @@ system. See the corresponding Defaults to True -#### [`PAPERLESS_ACCOUNT_ALLOW_SIGNUPS=`](#PAPERLESS_ACCOUNT_ALLOW_SIGNUPS) {#PAPERLESS_ACCOUNT_ALLOW_SIGNUPS} +#### [`PAPERLESS_SOCIAL_ACCOUNT_SYNC_GROUPS=`](#PAPERLESS_SOCIAL_ACCOUNT_SYNC_GROUPS) {#PAPERLESS_SOCIAL_ACCOUNT_SYNC_GROUPS} -: Allow users to signup for a new Paperless-ngx account. +: Sync groups from the third party authentication system (e.g. OIDC) to Paperless-ngx. When enabled, users will be added or removed from groups based on their group membership in the third party authentication system. Groups must already exist in Paperless-ngx and have the same name as in the third party authentication system. Groups are updated upon logging in via the third party authentication system, see the corresponding [django-allauth documentation](https://docs.allauth.org/en/dev/socialaccount/signals.html). + +: In order to pass groups from the authentication system you will need to update your [PAPERLESS_SOCIALACCOUNT_PROVIDERS](#PAPERLESS_SOCIALACCOUNT_PROVIDERS) setting by adding a top-level "SCOPES" setting which includes "groups", e.g.: + + ```json + {"openid_connect":{"SCOPE": ["openid","profile","email","groups"]... + ``` Defaults to False +#### [`PAPERLESS_SOCIAL_ACCOUNT_DEFAULT_GROUPS=`](#PAPERLESS_SOCIAL_ACCOUNT_DEFAULT_GROUPS) {#PAPERLESS_SOCIAL_ACCOUNT_DEFAULT_GROUPS} + +: A list of group names that users who signup via social accounts will be added to upon signup. Groups listed here must already exist. +If both the [PAPERLESS_ACCOUNT_DEFAULT_GROUPS](#PAPERLESS_ACCOUNT_DEFAULT_GROUPS) setting and this setting are used, the user will be added to both sets of groups. + + Defaults to None + #### [`PAPERLESS_ACCOUNT_DEFAULT_HTTP_PROTOCOL=`](#PAPERLESS_ACCOUNT_DEFAULT_HTTP_PROTOCOL) {#PAPERLESS_ACCOUNT_DEFAULT_HTTP_PROTOCOL} : The protocol used when generating URLs, e.g. login callback URLs. See the corresponding diff --git a/src/paperless/adapter.py b/src/paperless/adapter.py index add2bf45d..e29acb2ff 100644 --- a/src/paperless/adapter.py +++ b/src/paperless/adapter.py @@ -1,12 +1,17 @@ +import logging from urllib.parse import quote from allauth.account.adapter import DefaultAccountAdapter from allauth.core import context from allauth.socialaccount.adapter import DefaultSocialAccountAdapter from django.conf import settings +from django.contrib.auth.models import Group +from django.contrib.auth.models import User from django.forms import ValidationError from django.urls import reverse +logger = logging.getLogger("paperless.auth") + class CustomAccountAdapter(DefaultAccountAdapter): def is_open_for_signup(self, request): @@ -61,6 +66,20 @@ class CustomAccountAdapter(DefaultAccountAdapter): path = path.replace("UID-KEY", quote(key)) return settings.PAPERLESS_URL + path + def save_user(self, request, user, form, commit=True): # noqa: FBT002 + """ + Save the user instance. Default groups are assigned to the user, if + specified in the settings. + """ + user: User = super().save_user(request, user, form, commit) + group_names: list[str] = settings.ACCOUNT_DEFAULT_GROUPS + if len(group_names) > 0: + groups = Group.objects.filter(name__in=group_names) + logger.debug(f"Adding default groups to user `{user}`: {group_names}") + user.groups.add(*groups) + user.save() + return user + class CustomSocialAccountAdapter(DefaultSocialAccountAdapter): def is_open_for_signup(self, request, sociallogin): @@ -80,10 +99,19 @@ class CustomSocialAccountAdapter(DefaultSocialAccountAdapter): url = reverse("base") return url - def populate_user(self, request, sociallogin, data): + def save_user(self, request, sociallogin, form=None): """ - Populate the user with data from the social account. Stub is kept in case - global default permissions are implemented in the future. + Save the user instance. Default groups are assigned to the user, if + specified in the settings. """ - # TODO: If default global permissions are implemented, should also be here - return super().populate_user(request, sociallogin, data) # pragma: no cover + # save_user also calls account_adapter save_user which would set ACCOUNT_DEFAULT_GROUPS + user: User = super().save_user(request, sociallogin, form) + group_names: list[str] = settings.SOCIAL_ACCOUNT_DEFAULT_GROUPS + if len(group_names) > 0: + groups = Group.objects.filter(name__in=group_names) + logger.debug( + f"Adding default social groups to user `{user}`: {group_names}", + ) + user.groups.add(*groups) + user.save() + return user diff --git a/src/paperless/apps.py b/src/paperless/apps.py index b4147a2e3..819d8d5ff 100644 --- a/src/paperless/apps.py +++ b/src/paperless/apps.py @@ -2,6 +2,7 @@ from django.apps import AppConfig from django.utils.translation import gettext_lazy as _ from paperless.signals import handle_failed_login +from paperless.signals import handle_social_account_updated class PaperlessConfig(AppConfig): @@ -13,4 +14,9 @@ class PaperlessConfig(AppConfig): from django.contrib.auth.signals import user_login_failed user_login_failed.connect(handle_failed_login) + + from allauth.socialaccount.signals import social_account_updated + + social_account_updated.connect(handle_social_account_updated) + AppConfig.ready(self) diff --git a/src/paperless/settings.py b/src/paperless/settings.py index 8072f694e..0c8c71ab9 100644 --- a/src/paperless/settings.py +++ b/src/paperless/settings.py @@ -480,6 +480,7 @@ ACCOUNT_DEFAULT_HTTP_PROTOCOL = os.getenv( ACCOUNT_ADAPTER = "paperless.adapter.CustomAccountAdapter" ACCOUNT_ALLOW_SIGNUPS = __get_boolean("PAPERLESS_ACCOUNT_ALLOW_SIGNUPS") +ACCOUNT_DEFAULT_GROUPS = __get_list("PAPERLESS_ACCOUNT_DEFAULT_GROUPS") SOCIALACCOUNT_ADAPTER = "paperless.adapter.CustomSocialAccountAdapter" SOCIALACCOUNT_ALLOW_SIGNUPS = __get_boolean( @@ -490,6 +491,8 @@ SOCIALACCOUNT_AUTO_SIGNUP = __get_boolean("PAPERLESS_SOCIAL_AUTO_SIGNUP") SOCIALACCOUNT_PROVIDERS = json.loads( os.getenv("PAPERLESS_SOCIALACCOUNT_PROVIDERS", "{}"), ) +SOCIAL_ACCOUNT_DEFAULT_GROUPS = __get_list("PAPERLESS_SOCIAL_ACCOUNT_DEFAULT_GROUPS") +SOCIAL_ACCOUNT_SYNC_GROUPS = __get_boolean("PAPERLESS_SOCIAL_ACCOUNT_SYNC_GROUPS") MFA_TOTP_ISSUER = "Paperless-ngx" diff --git a/src/paperless/signals.py b/src/paperless/signals.py index fa0298685..a173ccc2e 100644 --- a/src/paperless/signals.py +++ b/src/paperless/signals.py @@ -30,3 +30,21 @@ def handle_failed_login(sender, credentials, request, **kwargs): log_output += f" from private IP `{client_ip}`." logger.info(log_output) + + +def handle_social_account_updated(sender, request, sociallogin, **kwargs): + """ + Handle the social account update signal. + """ + from django.contrib.auth.models import Group + + social_account_groups = sociallogin.account.extra_data.get( + "groups", + [], + ) # None if not found + if settings.SOCIAL_ACCOUNT_SYNC_GROUPS and social_account_groups is not None: + groups = Group.objects.filter(name__in=social_account_groups) + logger.debug( + f"Syncing groups for user `{sociallogin.user}`: {social_account_groups}", + ) + sociallogin.user.groups.set(groups, clear=True) diff --git a/src/paperless/tests/test_adapter.py b/src/paperless/tests/test_adapter.py index 5659a279a..be4ad3d90 100644 --- a/src/paperless/tests/test_adapter.py +++ b/src/paperless/tests/test_adapter.py @@ -4,6 +4,8 @@ from allauth.account.adapter import get_adapter from allauth.core import context from allauth.socialaccount.adapter import get_adapter as get_social_adapter from django.conf import settings +from django.contrib.auth.models import Group +from django.contrib.auth.models import User from django.forms import ValidationError from django.http import HttpRequest from django.test import TestCase @@ -81,6 +83,24 @@ class TestCustomAccountAdapter(TestCase): expected_url, ) + @override_settings(ACCOUNT_DEFAULT_GROUPS=["group1", "group2"]) + def test_save_user_adds_groups(self): + Group.objects.create(name="group1") + user = User.objects.create_user("testuser") + adapter = get_adapter() + form = mock.Mock( + cleaned_data={ + "username": "testuser", + "email": "user@example.com", + }, + ) + + user = adapter.save_user(HttpRequest(), user, form, commit=True) + + self.assertEqual(user.groups.count(), 1) + self.assertTrue(user.groups.filter(name="group1").exists()) + self.assertFalse(user.groups.filter(name="group2").exists()) + class TestCustomSocialAccountAdapter(TestCase): def test_is_open_for_signup(self): @@ -105,3 +125,19 @@ class TestCustomSocialAccountAdapter(TestCase): adapter.get_connect_redirect_url(request, socialaccount), expected_url, ) + + @override_settings(SOCIAL_ACCOUNT_DEFAULT_GROUPS=["group1", "group2"]) + def test_save_user_adds_groups(self): + Group.objects.create(name="group1") + adapter = get_social_adapter() + request = HttpRequest() + user = User.objects.create_user("testuser") + sociallogin = mock.Mock( + user=user, + ) + + user = adapter.save_user(request, sociallogin, None) + + self.assertEqual(user.groups.count(), 1) + self.assertTrue(user.groups.filter(name="group1").exists()) + self.assertFalse(user.groups.filter(name="group2").exists()) diff --git a/src/paperless/tests/test_signals.py b/src/paperless/tests/test_signals.py index dc425d667..0948ca575 100644 --- a/src/paperless/tests/test_signals.py +++ b/src/paperless/tests/test_signals.py @@ -1,7 +1,13 @@ +from unittest.mock import Mock + +from django.contrib.auth.models import Group +from django.contrib.auth.models import User from django.http import HttpRequest from django.test import TestCase +from django.test import override_settings from paperless.signals import handle_failed_login +from paperless.signals import handle_social_account_updated class TestFailedLoginLogging(TestCase): @@ -99,3 +105,88 @@ class TestFailedLoginLogging(TestCase): "INFO:paperless.auth:Login failed for user `john lennon` from private IP `10.0.0.1`.", ], ) + + +class TestSyncSocialLoginGroups(TestCase): + @override_settings(SOCIAL_ACCOUNT_SYNC_GROUPS=True) + def test_sync_enabled(self): + """ + GIVEN: + - Enabled group syncing, a user, and a social login + WHEN: + - The social login is updated via signal after login + THEN: + - The user's groups are updated to match the social login's groups + """ + group = Group.objects.create(name="group1") + user = User.objects.create_user(username="testuser") + sociallogin = Mock( + user=user, + account=Mock( + extra_data={ + "groups": ["group1"], + }, + ), + ) + handle_social_account_updated( + sender=None, + request=HttpRequest(), + sociallogin=sociallogin, + ) + self.assertEqual(list(user.groups.all()), [group]) + + @override_settings(SOCIAL_ACCOUNT_SYNC_GROUPS=False) + def test_sync_disabled(self): + """ + GIVEN: + - Disabled group syncing, a user, and a social login + WHEN: + - The social login is updated via signal after login + THEN: + - The user's groups are not updated + """ + Group.objects.create(name="group1") + user = User.objects.create_user(username="testuser") + sociallogin = Mock( + user=user, + account=Mock( + extra_data={ + "groups": ["group1"], + }, + ), + ) + handle_social_account_updated( + sender=None, + request=HttpRequest(), + sociallogin=sociallogin, + ) + self.assertEqual(list(user.groups.all()), []) + + @override_settings(SOCIAL_ACCOUNT_SYNC_GROUPS=True) + def test_no_groups(self): + """ + GIVEN: + - Enabled group syncing, a user, and a social login with no groups + WHEN: + - The social login is updated via signal after login + THEN: + - The user's groups are cleared to match the social login's groups + """ + group = Group.objects.create(name="group1") + user = User.objects.create_user(username="testuser") + user.groups.add(group) + user.save() + sociallogin = Mock( + user=user, + account=Mock( + extra_data={ + "groups": [], + }, + ), + ) + handle_social_account_updated( + sender=None, + request=HttpRequest(), + sociallogin=sociallogin, + ) + self.assertEqual(list(user.groups.all()), [])