diff --git a/docs/api-guide/authentication.md b/docs/api-guide/authentication.md index 84e58bf4b..d24c40109 100644 --- a/docs/api-guide/authentication.md +++ b/docs/api-guide/authentication.md @@ -84,7 +84,7 @@ When an unauthenticated request is denied permission there are two different err * [HTTP 401 Unauthorized][http401] * [HTTP 403 Permission Denied][http403] -HTTP 401 responses must always include a `WWW-Authenticate` header, that instructs the client how to authenticate. HTTP 403 responses do not include the `WWW-Authenticate` header. +HTTP 401 responses must always include a `WWW-Authenticate` header, that instructs the client how to authenticate. The `www_authenticate_behavior` setting controls how the header is generated: if set to `'first'` (the default), then only the text for the first scheme in the list will be used; if set to `'all'`, then a comma-separated list of the text for all the schemes will be used (see [MDN WWW-Authenticate](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/WWW-Authenticate) for more details). HTTP 403 responses do not include the `WWW-Authenticate` header. The kind of response that will be used depends on the authentication scheme. Although multiple authentication schemes may be in use, only one scheme may be used to determine the type of response. **The first authentication class set on the view is used when determining the type of response**. diff --git a/docs/api-guide/settings.md b/docs/api-guide/settings.md index 7bee3166d..1aeec428b 100644 --- a/docs/api-guide/settings.md +++ b/docs/api-guide/settings.md @@ -189,6 +189,13 @@ The class that should be used to initialize `request.auth` for unauthenticated r Default: `None` +#### WWW_AUTHENTICATE_BEHAVIOR + +Determines whether a single or multiple challenges are presented in the `WWW-Authenticate` header. + +This should be set to `'first'` (the default value) or `'all'`. When set to `'first'`, the `WWW-Authenticate` header will be set to an appropriate challenge for the first authentication scheme in the list. +When set to `'all'`, a comma-separated list of the challenge for all specified authentication schemes will be used instead (following the [syntax specification](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/WWW-Authenticate)). + --- ## Test settings diff --git a/rest_framework/apps.py b/rest_framework/apps.py index f6013eb7e..9298c4bf5 100644 --- a/rest_framework/apps.py +++ b/rest_framework/apps.py @@ -8,3 +8,4 @@ class RestFrameworkConfig(AppConfig): def ready(self): # Add System checks from .checks import pagination_system_check # NOQA + from .checks import www_authenticate_behavior_setting_check # NOQA diff --git a/rest_framework/checks.py b/rest_framework/checks.py index d5d77bc59..d6a6d7d90 100644 --- a/rest_framework/checks.py +++ b/rest_framework/checks.py @@ -1,4 +1,4 @@ -from django.core.checks import Tags, Warning, register +from django.core.checks import Error, Tags, Warning, register @register(Tags.compatibility) @@ -19,3 +19,22 @@ def pagination_system_check(app_configs, **kwargs): ) ) return errors + + +@register(Tags.compatibility) +def www_authenticate_behavior_setting_check(app_configs, **kwargs): + errors = [] + # WWW_AUTHENTICATE_BEHAVIOR setting must be 'first' or 'all' + from rest_framework.settings import api_settings + setting = api_settings.WWW_AUTHENTICATE_BEHAVIOR + if setting not in ['first', 'all']: + errors.append( + Error( + "The rest_framework setting WWW_AUTHENTICATE_BEHAVIOR must be either " + f"'first' or 'all' (it is currently set to '{setting}').", + hint="Set WWW_AUTHENTICATE_BEHAVIOR to either 'first' or 'all', " + "or leave it unset (the default value is 'first').", + id="rest_framework.E001", + ) + ) + return errors diff --git a/rest_framework/settings.py b/rest_framework/settings.py index b0d7bacec..2a05e6879 100644 --- a/rest_framework/settings.py +++ b/rest_framework/settings.py @@ -78,6 +78,7 @@ DEFAULTS = { # Authentication 'UNAUTHENTICATED_USER': 'django.contrib.auth.models.AnonymousUser', 'UNAUTHENTICATED_TOKEN': None, + 'WWW_AUTHENTICATE_BEHAVIOR': 'first', # View configuration 'VIEW_NAME_FUNCTION': 'rest_framework.views.get_view_name', diff --git a/rest_framework/views.py b/rest_framework/views.py index 327ebe903..ea0fc25ef 100644 --- a/rest_framework/views.py +++ b/rest_framework/views.py @@ -108,6 +108,7 @@ class APIView(View): renderer_classes = api_settings.DEFAULT_RENDERER_CLASSES parser_classes = api_settings.DEFAULT_PARSER_CLASSES authentication_classes = api_settings.DEFAULT_AUTHENTICATION_CLASSES + www_authenticate_behavior = api_settings.WWW_AUTHENTICATE_BEHAVIOR throttle_classes = api_settings.DEFAULT_THROTTLE_CLASSES permission_classes = api_settings.DEFAULT_PERMISSION_CLASSES content_negotiation_class = api_settings.DEFAULT_CONTENT_NEGOTIATION_CLASS @@ -192,8 +193,13 @@ class APIView(View): header to use for 401 responses, if any. """ authenticators = self.get_authenticators() + www_authenticate_behavior = self.www_authenticate_behavior if authenticators: - return authenticators[0].authenticate_header(request) + if www_authenticate_behavior == 'first': + return authenticators[0].authenticate_header(request) + elif www_authenticate_behavior == 'all': + challenges = (a.authenticate_header(request) for a in authenticators) + return ', '.join((c for c in challenges if c is not None)) def get_parser_context(self, http_request): """