diff --git a/docs/configuration/optional-settings.md b/docs/configuration/optional-settings.md index cbe01728c..5b4fd1d14 100644 --- a/docs/configuration/optional-settings.md +++ b/docs/configuration/optional-settings.md @@ -291,6 +291,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]() 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 bdd83723d..ed3974312 100644 --- a/netbox/netbox/settings.py +++ b/netbox/netbox/settings.py @@ -93,6 +93,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) @@ -258,7 +264,7 @@ INSTALLED_APPS = [ ] # Middleware -MIDDLEWARE = ( +MIDDLEWARE = [ 'debug_toolbar.middleware.DebugToolbarMiddleware', 'django_prometheus.middleware.PrometheusBeforeMiddleware', 'corsheaders.middleware.CorsMiddleware', @@ -274,7 +280,9 @@ MIDDLEWARE = ( 'utilities.middleware.APIVersionMiddleware', 'extras.middleware.ObjectChangeMiddleware', 'django_prometheus.middleware.PrometheusAfterMiddleware', -) +] +if REMOTE_AUTH_ENABLED: + MIDDLEWARE.append('utilities.middleware.RemoteUserMiddleware') ROOT_URLCONF = 'netbox.urls' @@ -297,10 +305,12 @@ TEMPLATES = [ }, ] -# Authentication +# Set up authentication backends AUTHENTICATION_BACKENDS = [ 'utilities.auth_backends.ViewExemptModelBackend', ] +if REMOTE_AUTH_ENABLED: + AUTHENTICATION_BACKENDS.insert(0, REMOTE_AUTH_BACKEND) # Internationalization LANGUAGE_CODE = 'en-us' diff --git a/netbox/utilities/auth_backends.py b/netbox/utilities/auth_backends.py index 54541b0b5..52c3454f1 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 bool(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 564771821..a4fd1a254 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 @@ -30,6 +31,14 @@ 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 + header = settings.REMOTE_AUTH_HEADER + + class APIVersionMiddleware(object): """ If the request is for an API endpoint, include the API version as a response header.