Merge pull request #4299 from netbox-community/2328-external-authentication

Closes #2328: External user authentication

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/

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'

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',
 ]
 

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']))

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 "
+                    "<app>.<action>_<model>. (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

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.