<commit_before>====================================
Authentication using ``REMOTE_USER``
====================================

.. currentmodule:: django.contrib.backends

This document describes how to make use of external authentication sources
(where the Web server sets the ``REMOTE_USER`` environment variable) in your
Django applications.  This type of authentication solution is typically seen on
intranet sites, with single sign-on solutions such as IIS and Integrated
Windows Authentication or Apache and `mod_authnz_ldap`_, `CAS`_, `Cosign`_,
`WebAuth`_, `mod_auth_sspi`_, etc.

.. _mod_authnz_ldap: http://httpd.apache.org/docs/2.2/mod/mod_authnz_ldap.html
.. _CAS: http://www.jasig.org/cas
.. _Cosign: http://weblogin.org
.. _WebAuth: http://www.stanford.edu/services/webauth/
.. _mod_auth_sspi: http://sourceforge.net/projects/mod-auth-sspi

When the Web server takes care of authentication it typically sets the
``REMOTE_USER`` environment variable for use in the underlying application.  In
Django, ``REMOTE_USER`` is made available in the :attr:`request.META
<django.http.HttpRequest.META>` attribute.  Django can be configured to make
use of the ``REMOTE_USER`` value using the ``RemoteUserMiddleware`` and
``RemoteUserBackend`` classes found in :mod:`django.contrib.auth`.

Configuration
=============

First, you must add the
:class:`django.contrib.auth.middleware.RemoteUserMiddleware` to the
:setting:`MIDDLEWARE_CLASSES` setting **after** the
:class:`django.contrib.auth.middleware.AuthenticationMiddleware`::

    MIDDLEWARE_CLASSES = (
        ...
        'django.contrib.auth.middleware.AuthenticationMiddleware',
        'django.contrib.auth.middleware.RemoteUserMiddleware',
        ...
        )

Next, you must replace the :class:`~django.contrib.auth.backends.ModelBackend`
with ``RemoteUserBackend`` in the :setting:`AUTHENTICATION_BACKENDS` setting::

    AUTHENTICATION_BACKENDS = (
        'django.contrib.auth.backends.RemoteUserBackend',
    )

With this setup, ``RemoteUserMiddleware`` will detect the username in
``request.META['REMOTE_USER']`` and will authenticate and auto-login that user
using the ``RemoteUserBackend``.

.. note::
   Since the ``RemoteUserBackend`` inherits from ``ModelBackend``, you will
   still have all of the same permissions checking that is implemented in
   ``ModelBackend``.

If your authentication mechanism uses a custom HTTP header and not
``REMOTE_USER``, you can subclass ``RemoteUserMiddleware`` and set the
``header`` attribute to the desired ``request.META`` key.  For example::

    from django.contrib.auth.middleware import RemoteUserMiddleware

    class CustomHeaderMiddleware(RemoteUserMiddleware):
        header = 'HTTP_AUTHUSER'


``RemoteUserBackend``
=====================

.. class:: django.contrib.backends.RemoteUserBackend

If you need more control, you can create your own authentication backend
that inherits from ``RemoteUserBackend`` and overrides certain parts:

Attributes
~~~~~~~~~~
<commit_msg>Fixed #14551 -- corrected a type in the remote user auth documentation.  Thanks to mag for the report and fix.<commit_after>====================================
Authentication using ``REMOTE_USER``
====================================

.. currentmodule:: django.contrib.auth.backends

This document describes how to make use of external authentication sources
(where the Web server sets the ``REMOTE_USER`` environment variable) in your
Django applications.  This type of authentication solution is typically seen on
intranet sites, with single sign-on solutions such as IIS and Integrated
Windows Authentication or Apache and `mod_authnz_ldap`_, `CAS`_, `Cosign`_,
`WebAuth`_, `mod_auth_sspi`_, etc.

.. _mod_authnz_ldap: http://httpd.apache.org/docs/2.2/mod/mod_authnz_ldap.html
.. _CAS: http://www.jasig.org/cas
.. _Cosign: http://weblogin.org
.. _WebAuth: http://www.stanford.edu/services/webauth/
.. _mod_auth_sspi: http://sourceforge.net/projects/mod-auth-sspi

When the Web server takes care of authentication it typically sets the
``REMOTE_USER`` environment variable for use in the underlying application.  In
Django, ``REMOTE_USER`` is made available in the :attr:`request.META
<django.http.HttpRequest.META>` attribute.  Django can be configured to make
use of the ``REMOTE_USER`` value using the ``RemoteUserMiddleware`` and
``RemoteUserBackend`` classes found in :mod:`django.contrib.auth`.

Configuration
=============

First, you must add the
:class:`django.contrib.auth.middleware.RemoteUserMiddleware` to the
:setting:`MIDDLEWARE_CLASSES` setting **after** the
:class:`django.contrib.auth.middleware.AuthenticationMiddleware`::

    MIDDLEWARE_CLASSES = (
        ...
        'django.contrib.auth.middleware.AuthenticationMiddleware',
        'django.contrib.auth.middleware.RemoteUserMiddleware',
        ...
        )

Next, you must replace the :class:`~django.contrib.auth.backends.ModelBackend`
with ``RemoteUserBackend`` in the :setting:`AUTHENTICATION_BACKENDS` setting::

    AUTHENTICATION_BACKENDS = (
        'django.contrib.auth.backends.RemoteUserBackend',
    )

With this setup, ``RemoteUserMiddleware`` will detect the username in
``request.META['REMOTE_USER']`` and will authenticate and auto-login that user
using the ``RemoteUserBackend``.

.. note::
   Since the ``RemoteUserBackend`` inherits from ``ModelBackend``, you will
   still have all of the same permissions checking that is implemented in
   ``ModelBackend``.

If your authentication mechanism uses a custom HTTP header and not
``REMOTE_USER``, you can subclass ``RemoteUserMiddleware`` and set the
``header`` attribute to the desired ``request.META`` key.  For example::

    from django.contrib.auth.middleware import RemoteUserMiddleware

    class CustomHeaderMiddleware(RemoteUserMiddleware):
        header = 'HTTP_AUTHUSER'


``RemoteUserBackend``
=====================

.. class:: django.contrib.auth.backends.RemoteUserBackend

If you need more control, you can create your own authentication backend
that inherits from ``RemoteUserBackend`` and overrides certain parts:

Attributes
~~~~~~~~~~

{'fraction_non_alphanumeric': 0.13601312551271533, 'fraction_numerical': 0.0014766201804757998, 'mean_word_length': 5.065671641791044, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 0, 'lorem ipsum': 0, 'www.': 4, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7367663', 'n_tokens_mistral': 1719, 'n_tokens_neox': 1681, 'n_words': 530}