diff --git a/docs/configuration/optional-settings.md b/docs/configuration/optional-settings.md index efc096e19..4015badf4 100644 --- a/docs/configuration/optional-settings.md +++ b/docs/configuration/optional-settings.md @@ -307,6 +307,54 @@ When determining the primary IP address for a device, IPv6 is preferred over IPv --- +## REMOTE_AUTH_ENABLED + +Default: `False` + +NetBox can be configured to support remote user authentication by inferring user authentication from an HTTP header set by the HTTP reverse proxy (e.g. nginx or Apache). Set this to `True` to enable this functionality. (Local authenitcation will still take effect as a fallback.) + +--- + +## REMOTE_AUTH_BACKEND + +Default: `'utilities.auth_backends.RemoteUserBackend'` + +Python path to the custom [Django authentication backend](https://docs.djangoproject.com/en/stable/topics/auth/customizing/) to use for external user authentication, if not using NetBox's built-in backend. (Requires `REMOTE_AUTH_ENABLED`.) + +--- + +## REMOTE_AUTH_HEADER + +Default: `'HTTP_REMOTE_USER'` + +When remote user authentication is in use, this is the name of the HTTP header which informs NetBox of the currently authenticated user. (Requires `REMOTE_AUTH_ENABLED`.) + +--- + +## REMOTE_AUTH_AUTO_CREATE_USER + +Default: `True` + +If true, NetBox will automatically create local accounts for users authenticated via a remote service. (Requires `REMOTE_AUTH_ENABLED`.) + +--- + +## REMOTE_AUTH_DEFAULT_GROUPS + +Default: `[]` (Empty list) + +The list of groups to assign a new user account when created using remote authentication. (Requires `REMOTE_AUTH_ENABLED`.) + +--- + +## REMOTE_AUTH_DEFAULT_PERMISSIONS + +Default: `[]` (Empty list) + +The list of permissions to assign a new user account when created using remote authentication. (Requires `REMOTE_AUTH_ENABLED`.) + +--- + ## REPORTS_ROOT Default: $BASE_DIR/netbox/reports/ diff --git a/netbox/netbox/configuration.example.py b/netbox/netbox/configuration.example.py index 7002def9b..1aada7c2d 100644 --- a/netbox/netbox/configuration.example.py +++ b/netbox/netbox/configuration.example.py @@ -179,6 +179,14 @@ PAGINATE_COUNT = 50 # prefer IPv4 instead. PREFER_IPV4 = False +# Remote authentication support +REMOTE_AUTH_ENABLED = False +REMOTE_AUTH_BACKEND = 'utilities.auth_backends.RemoteUserBackend' +REMOTE_AUTH_HEADER = 'HTTP_REMOTE_USER' +REMOTE_AUTH_AUTO_CREATE_USER = True +REMOTE_AUTH_DEFAULT_GROUPS = [] +REMOTE_AUTH_DEFAULT_PERMISSIONS = [] + # The file path where custom reports will be stored. A trailing slash is not needed. Note that the default value of # this setting is derived from the installed location. # REPORTS_ROOT = '/opt/netbox/netbox/reports' diff --git a/netbox/netbox/settings.py b/netbox/netbox/settings.py index 6611b5a60..3c24b061a 100644 --- a/netbox/netbox/settings.py +++ b/netbox/netbox/settings.py @@ -94,6 +94,12 @@ NAPALM_TIMEOUT = getattr(configuration, 'NAPALM_TIMEOUT', 30) NAPALM_USERNAME = getattr(configuration, 'NAPALM_USERNAME', '') PAGINATE_COUNT = getattr(configuration, 'PAGINATE_COUNT', 50) PREFER_IPV4 = getattr(configuration, 'PREFER_IPV4', False) +REMOTE_AUTH_AUTO_CREATE_USER = getattr(configuration, 'REMOTE_AUTH_AUTO_CREATE_USER', False) +REMOTE_AUTH_BACKEND = getattr(configuration, 'REMOTE_AUTH_BACKEND', 'utilities.auth_backends.RemoteUserBackend') +REMOTE_AUTH_DEFAULT_GROUPS = getattr(configuration, 'REMOTE_AUTH_DEFAULT_GROUPS', []) +REMOTE_AUTH_DEFAULT_PERMISSIONS = getattr(configuration, 'REMOTE_AUTH_DEFAULT_PERMISSIONS', []) +REMOTE_AUTH_ENABLED = getattr(configuration, 'REMOTE_AUTH_ENABLED', False) +REMOTE_AUTH_HEADER = getattr(configuration, 'REMOTE_AUTH_HEADER', 'HTTP_REMOTE_USER') REPORTS_ROOT = getattr(configuration, 'REPORTS_ROOT', os.path.join(BASE_DIR, 'reports')).rstrip('/') SCRIPTS_ROOT = getattr(configuration, 'SCRIPTS_ROOT', os.path.join(BASE_DIR, 'scripts')).rstrip('/') SESSION_FILE_PATH = getattr(configuration, 'SESSION_FILE_PATH', None) @@ -259,7 +265,7 @@ INSTALLED_APPS = [ ] # Middleware -MIDDLEWARE = ( +MIDDLEWARE = [ 'debug_toolbar.middleware.DebugToolbarMiddleware', 'django_prometheus.middleware.PrometheusBeforeMiddleware', 'corsheaders.middleware.CorsMiddleware', @@ -271,11 +277,12 @@ MIDDLEWARE = ( 'django.middleware.clickjacking.XFrameOptionsMiddleware', 'django.middleware.security.SecurityMiddleware', 'utilities.middleware.ExceptionHandlingMiddleware', + 'utilities.middleware.RemoteUserMiddleware', 'utilities.middleware.LoginRequiredMiddleware', 'utilities.middleware.APIVersionMiddleware', 'extras.middleware.ObjectChangeMiddleware', 'django_prometheus.middleware.PrometheusAfterMiddleware', -) +] ROOT_URLCONF = 'netbox.urls' @@ -298,8 +305,9 @@ TEMPLATES = [ }, ] -# Authentication +# Set up authentication backends AUTHENTICATION_BACKENDS = [ + REMOTE_AUTH_BACKEND, 'utilities.auth_backends.ViewExemptModelBackend', ] diff --git a/netbox/netbox/tests/test_authentication.py b/netbox/netbox/tests/test_authentication.py new file mode 100644 index 000000000..42cddb082 --- /dev/null +++ b/netbox/netbox/tests/test_authentication.py @@ -0,0 +1,159 @@ +from django.conf import settings +from django.contrib.auth.models import Group, User +from django.test import Client, TestCase +from django.test.utils import override_settings +from django.urls import reverse + + +class ExternalAuthenticationTestCase(TestCase): + + @classmethod + def setUpTestData(cls): + cls.user = User.objects.create(username='remoteuser1') + + def setUp(self): + self.client = Client() + + @override_settings( + LOGIN_REQUIRED=True + ) + def test_remote_auth_disabled(self): + """ + Test enabling remote authentication with the default configuration. + """ + headers = { + 'HTTP_REMOTE_USER': 'remoteuser1', + } + + self.assertFalse(settings.REMOTE_AUTH_ENABLED) + self.assertEqual(settings.REMOTE_AUTH_HEADER, 'HTTP_REMOTE_USER') + + # Client should not be authenticated + response = self.client.get(reverse('home'), follow=True, **headers) + self.assertNotIn('_auth_user_id', self.client.session) + + @override_settings( + REMOTE_AUTH_ENABLED=True, + LOGIN_REQUIRED=True + ) + def test_remote_auth_enabled(self): + """ + Test enabling remote authentication with the default configuration. + """ + headers = { + 'HTTP_REMOTE_USER': 'remoteuser1', + } + + self.assertTrue(settings.REMOTE_AUTH_ENABLED) + self.assertEqual(settings.REMOTE_AUTH_HEADER, 'HTTP_REMOTE_USER') + + response = self.client.get(reverse('home'), follow=True, **headers) + self.assertEqual(response.status_code, 200) + self.assertEqual(int(self.client.session.get('_auth_user_id')), self.user.pk, msg='Authentication failed') + + @override_settings( + REMOTE_AUTH_ENABLED=True, + REMOTE_AUTH_HEADER='HTTP_FOO', + LOGIN_REQUIRED=True + ) + def test_remote_auth_custom_header(self): + """ + Test enabling remote authentication with a custom HTTP header. + """ + headers = { + 'HTTP_FOO': 'remoteuser1', + } + + self.assertTrue(settings.REMOTE_AUTH_ENABLED) + self.assertEqual(settings.REMOTE_AUTH_HEADER, 'HTTP_FOO') + + response = self.client.get(reverse('home'), follow=True, **headers) + self.assertEqual(response.status_code, 200) + self.assertEqual(int(self.client.session.get('_auth_user_id')), self.user.pk, msg='Authentication failed') + + @override_settings( + REMOTE_AUTH_ENABLED=True, + REMOTE_AUTH_AUTO_CREATE_USER=True, + LOGIN_REQUIRED=True + ) + def test_remote_auth_auto_create(self): + """ + Test enabling remote authentication with automatic user creation disabled. + """ + headers = { + 'HTTP_REMOTE_USER': 'remoteuser2', + } + + self.assertTrue(settings.REMOTE_AUTH_ENABLED) + self.assertTrue(settings.REMOTE_AUTH_AUTO_CREATE_USER) + self.assertEqual(settings.REMOTE_AUTH_HEADER, 'HTTP_REMOTE_USER') + + response = self.client.get(reverse('home'), follow=True, **headers) + self.assertEqual(response.status_code, 200) + + # Local user should have been automatically created + new_user = User.objects.get(username='remoteuser2') + self.assertEqual(int(self.client.session.get('_auth_user_id')), new_user.pk, msg='Authentication failed') + + @override_settings( + REMOTE_AUTH_ENABLED=True, + REMOTE_AUTH_AUTO_CREATE_USER=True, + REMOTE_AUTH_DEFAULT_GROUPS=['Group 1', 'Group 2'], + LOGIN_REQUIRED=True + ) + def test_remote_auth_default_groups(self): + """ + Test enabling remote authentication with the default configuration. + """ + headers = { + 'HTTP_REMOTE_USER': 'remoteuser2', + } + + self.assertTrue(settings.REMOTE_AUTH_ENABLED) + self.assertTrue(settings.REMOTE_AUTH_AUTO_CREATE_USER) + self.assertEqual(settings.REMOTE_AUTH_HEADER, 'HTTP_REMOTE_USER') + self.assertEqual(settings.REMOTE_AUTH_DEFAULT_GROUPS, ['Group 1', 'Group 2']) + + # Create required groups + groups = ( + Group(name='Group 1'), + Group(name='Group 2'), + Group(name='Group 3'), + ) + Group.objects.bulk_create(groups) + + response = self.client.get(reverse('home'), follow=True, **headers) + self.assertEqual(response.status_code, 200) + + new_user = User.objects.get(username='remoteuser2') + self.assertEqual(int(self.client.session.get('_auth_user_id')), new_user.pk, msg='Authentication failed') + self.assertListEqual( + [groups[0], groups[1]], + list(new_user.groups.all()) + ) + + @override_settings( + REMOTE_AUTH_ENABLED=True, + REMOTE_AUTH_AUTO_CREATE_USER=True, + REMOTE_AUTH_DEFAULT_PERMISSIONS=['dcim.add_site', 'dcim.change_site'], + LOGIN_REQUIRED=True + ) + def test_remote_auth_default_permissions(self): + """ + Test enabling remote authentication with the default configuration. + """ + headers = { + 'HTTP_REMOTE_USER': 'remoteuser2', + } + + self.assertTrue(settings.REMOTE_AUTH_ENABLED) + self.assertTrue(settings.REMOTE_AUTH_AUTO_CREATE_USER) + self.assertEqual(settings.REMOTE_AUTH_HEADER, 'HTTP_REMOTE_USER') + self.assertEqual(settings.REMOTE_AUTH_DEFAULT_PERMISSIONS, ['dcim.add_site', 'dcim.change_site']) + + response = self.client.get(reverse('home'), follow=True, **headers) + self.assertEqual(response.status_code, 200) + + new_user = User.objects.get(username='remoteuser2') + self.assertEqual(int(self.client.session.get('_auth_user_id')), new_user.pk, msg='Authentication failed') + self.assertTrue(new_user.has_perms(['dcim.add_site', 'dcim.change_site'])) diff --git a/netbox/utilities/auth_backends.py b/netbox/utilities/auth_backends.py index 54541b0b5..6e968a241 100644 --- a/netbox/utilities/auth_backends.py +++ b/netbox/utilities/auth_backends.py @@ -1,5 +1,8 @@ +import logging + from django.conf import settings -from django.contrib.auth.backends import ModelBackend +from django.contrib.auth.backends import ModelBackend, RemoteUserBackend as RemoteUserBackend_ +from django.contrib.auth.models import Group, Permission class ViewExemptModelBackend(ModelBackend): @@ -26,3 +29,45 @@ class ViewExemptModelBackend(ModelBackend): pass return super().has_perm(user_obj, perm, obj) + + +class RemoteUserBackend(ViewExemptModelBackend, RemoteUserBackend_): + """ + Custom implementation of Django's RemoteUserBackend which provides configuration hooks for basic customization. + """ + @property + def create_unknown_user(self): + return settings.REMOTE_AUTH_AUTO_CREATE_USER + + def configure_user(self, request, user): + logger = logging.getLogger('netbox.authentication.RemoteUserBackend') + + # Assign default groups to the user + group_list = [] + for name in settings.REMOTE_AUTH_DEFAULT_GROUPS: + try: + group_list.append(Group.objects.get(name=name)) + except Group.DoesNotExist: + logging.error("Could not assign group {name} to remotely-authenticated user {user}: Group not found") + if group_list: + user.groups.add(*group_list) + logger.debug(f"Assigned groups to remotely-authenticated user {user}: {group_list}") + + # Assign default permissions to the user + permissions_list = [] + for permission_name in settings.REMOTE_AUTH_DEFAULT_PERMISSIONS: + try: + app_label, codename = permission_name.split('.') + permissions_list.append( + Permission.objects.get(content_type__app_label=app_label, codename=codename) + ) + except (ValueError, Permission.DoesNotExist): + logging.error( + "Invalid permission name: '{permission_name}'. Permissions must be in the form " + "._. (Example: dcim.add_site)" + ) + if permissions_list: + user.user_permissions.add(*permissions_list) + logger.debug(f"Assigned permissions to remotely-authenticated user {user}: {permissions_list}") + + return user diff --git a/netbox/utilities/middleware.py b/netbox/utilities/middleware.py index 6cbf4ed17..d86be752b 100644 --- a/netbox/utilities/middleware.py +++ b/netbox/utilities/middleware.py @@ -1,6 +1,7 @@ from urllib import parse from django.conf import settings +from django.contrib.auth.middleware import RemoteUserMiddleware as RemoteUserMiddleware_ from django.db import ProgrammingError from django.http import Http404, HttpResponseRedirect from django.urls import reverse @@ -31,6 +32,25 @@ class LoginRequiredMiddleware(object): return self.get_response(request) +class RemoteUserMiddleware(RemoteUserMiddleware_): + """ + Custom implementation of Django's RemoteUserMiddleware which allows for a user-configurable HTTP header name. + """ + force_logout_if_no_header = False + + @property + def header(self): + return settings.REMOTE_AUTH_HEADER + + def process_request(self, request): + + # Bypass middleware if remote authentication is not enabled + if not settings.REMOTE_AUTH_ENABLED: + return + + return super().process_request(request) + + class APIVersionMiddleware(object): """ If the request is for an API endpoint, include the API version as a response header.