{"title":"使用 REMOTE_USER 进行身份验证","version":"3.1","locale":"zh-hans","docname":"howto/auth-remote-user","url":"/zh-hans/3.1/howto/auth-remote-user/","canonical":"https://djangodocs.dev/zh-hans/3.1/howto/auth-remote-user/","summary":"本文档描述如何在 Django 应用中使用外部身份验证资源（在 web 服务器上设置 REMOTE_USER 环境变量的地方）。这种类型的身份验证方法一般用在使用了单点登录方案的内部网站上，比如 IIS 和 Windows 一体化验证或者 Apache 和 mod_authnz_ldap , CAS , Cosign ,…","html":"<h1>使用 <code class=\"docutils literal notranslate\"><span class=\"pre\">REMOTE_USER</span></code> 进行身份验证<a class=\"heading-anchor\" href=\"#authentication-using-remote-user\"><span class=\"visually-hidden\">Link to this heading</span><span aria-hidden=\"true\">#</span></a></h1>\n<p>本文档描述如何在 Django 应用中使用外部身份验证资源（在 web 服务器上设置 <code class=\"docutils literal notranslate\"><span class=\"pre\">REMOTE_USER</span></code> 环境变量的地方）。这种类型的身份验证方法一般用在使用了单点登录方案的内部网站上，比如 IIS 和 Windows 一体化验证或者 Apache 和 <a class=\"reference external\" href=\"https://httpd.apache.org/docs/2.2/mod/mod_authnz_ldap.html\">mod_authnz_ldap</a>, <a class=\"reference external\" href=\"https://www.apereo.org/projects/cas\">CAS</a>, <a class=\"reference external\" href=\"http://weblogin.org\">Cosign</a>, <a class=\"reference external\" href=\"https://www.stanford.edu/services/webauth/\">WebAuth</a>, <a class=\"reference external\" href=\"https://sourceforge.net/projects/mod-auth-sspi\">mod_auth_sspi</a> 等等。</p>\n<p>当 Web 服务器负责鉴权时，通常会设置 <code class=\"docutils literal notranslate\"><span class=\"pre\">REMOTE_USER</span></code> 环境变量，这是为了在底层应用中使用。在 Django 中， <code class=\"docutils literal notranslate\"><span class=\"pre\">REMOTE_USER</span></code> 是作为 <a class=\"reference internal\" href=\"/zh-hans/3.1/ref/request-response/#django.http.HttpRequest.META\" title=\"django.http.HttpRequest.META\"><code class=\"xref py py-attr docutils literal notranslate\"><span class=\"pre\">request.META</span></code></a> 的参数来使用的。如果想在 Django 中使用 <code class=\"docutils literal notranslate\"><span class=\"pre\">REMOTE_USER</span></code>,  可以通过配置 <code class=\"docutils literal notranslate\"><span class=\"pre\">RemoteUserMiddleware</span></code> 中间件， <code class=\"docutils literal notranslate\"><span class=\"pre\">PersistentRemoteUserMiddleware</span></code> 中间件，或者继承在 <a class=\"reference internal\" href=\"/zh-hans/3.1/topics/auth/#module-django.contrib.auth\" title=\"django.contrib.auth: Django's authentication framework.\"><code class=\"xref py py-mod docutils literal notranslate\"><span class=\"pre\">django.contrib.auth</span></code></a> 中的 <a class=\"reference internal\" href=\"/zh-hans/3.1/ref/contrib/auth/#django.contrib.auth.backends.RemoteUserBackend\" title=\"django.contrib.auth.backends.RemoteUserBackend\"><code class=\"xref py py-class docutils literal notranslate\"><span class=\"pre\">RemoteUserBackend</span></code></a> 来实现。</p>\n<section id=\"configuration\">\n<h2>配置<a class=\"heading-anchor\" href=\"#configuration\"><span class=\"visually-hidden\">Link to this heading</span><span aria-hidden=\"true\">#</span></a></h2>\n<p>首先，你需要向配置文件的 <a class=\"reference internal\" href=\"/zh-hans/3.1/ref/settings/#std-setting-MIDDLEWARE\"><code class=\"xref std std-setting docutils literal notranslate\"><span class=\"pre\">MIDDLEWARE</span></code></a> 键中，在 <a class=\"reference internal\" href=\"/zh-hans/3.1/ref/middleware/#django.contrib.auth.middleware.AuthenticationMiddleware\" title=\"django.contrib.auth.middleware.AuthenticationMiddleware\"><code class=\"xref py py-class docutils literal notranslate\"><span class=\"pre\">django.contrib.auth.middleware.AuthenticationMiddleware</span></code></a> 的 <strong>后面</strong> 添加 <a class=\"reference internal\" href=\"/zh-hans/3.1/ref/middleware/#django.contrib.auth.middleware.RemoteUserMiddleware\" title=\"django.contrib.auth.middleware.RemoteUserMiddleware\"><code class=\"xref py py-class docutils literal notranslate\"><span class=\"pre\">django.contrib.auth.middleware.RemoteUserMiddleware</span></code></a></p>\n<div class=\"code-block\" data-language=\"default\"><div class=\"code-block-toolbar\"><span class=\"code-block-language\">Code</span><button type=\"button\" class=\"copy-button\" data-copy hidden><span class=\"copy-button-label\">Copy</span></button></div><pre role=\"group\" tabindex=\"0\" aria-label=\"Code code\"><code><span class=\"n\">MIDDLEWARE</span> <span class=\"o\">=</span> <span class=\"p\">[</span>\n    <span class=\"s1\">&#39;...&#39;</span><span class=\"p\">,</span>\n    <span class=\"s1\">&#39;django.contrib.auth.middleware.AuthenticationMiddleware&#39;</span><span class=\"p\">,</span>\n    <span class=\"s1\">&#39;django.contrib.auth.middleware.RemoteUserMiddleware&#39;</span><span class=\"p\">,</span>\n    <span class=\"s1\">&#39;...&#39;</span><span class=\"p\">,</span>\n<span class=\"p\">]</span>\n</code></pre></div>\n<p>然后，你需要将设置中的 <a class=\"reference internal\" href=\"/zh-hans/3.1/ref/settings/#std-setting-AUTHENTICATION_BACKENDS\"><code class=\"xref std std-setting docutils literal notranslate\"><span class=\"pre\">AUTHENTICATION_BACKENDS</span></code></a> setting:: 键值由 <a class=\"reference internal\" href=\"/zh-hans/3.1/ref/contrib/auth/#django.contrib.auth.backends.ModelBackend\" title=\"django.contrib.auth.backends.ModelBackend\"><code class=\"xref py py-class docutils literal notranslate\"><span class=\"pre\">ModelBackend</span></code></a> 替换为 <a class=\"reference internal\" href=\"/zh-hans/3.1/ref/contrib/auth/#django.contrib.auth.backends.RemoteUserBackend\" title=\"django.contrib.auth.backends.RemoteUserBackend\"><code class=\"xref py py-class docutils literal notranslate\"><span class=\"pre\">RemoteUserBackend</span></code></a>:</p>\n<div class=\"code-block\" data-language=\"default\"><div class=\"code-block-toolbar\"><span class=\"code-block-language\">Code</span><button type=\"button\" class=\"copy-button\" data-copy hidden><span class=\"copy-button-label\">Copy</span></button></div><pre role=\"group\" tabindex=\"0\" aria-label=\"Code code\"><code><span class=\"n\">AUTHENTICATION_BACKENDS</span> <span class=\"o\">=</span> <span class=\"p\">[</span>\n    <span class=\"s1\">&#39;django.contrib.auth.backends.RemoteUserBackend&#39;</span><span class=\"p\">,</span>\n<span class=\"p\">]</span>\n</code></pre></div>\n<p>通过此项设置， <code class=\"docutils literal notranslate\"><span class=\"pre\">RemoteUserMiddleware</span></code> 可以检测 <code class=\"docutils literal notranslate\"><span class=\"pre\">request.META['REMOTE_USER']</span></code> 中的用户名，而且可以认证和自动登录用户使用的 <a class=\"reference internal\" href=\"/zh-hans/3.1/ref/contrib/auth/#django.contrib.auth.backends.RemoteUserBackend\" title=\"django.contrib.auth.backends.RemoteUserBackend\"><code class=\"xref py py-class docutils literal notranslate\"><span class=\"pre\">RemoteUserBackend</span></code></a>。</p>\n<p>要注意这项设置将导致无法使用默认的 <code class=\"docutils literal notranslate\"><span class=\"pre\">ModelBackend</span></code> 验证。也就是说如果 <code class=\"docutils literal notranslate\"><span class=\"pre\">REMOTE_USER</span></code> 的值没有指定则该用户将无法登录，即使通过 Django 的管理后台。要解决这些问题，把 <code class=\"docutils literal notranslate\"><span class=\"pre\">'django.contrib.auth.backends.ModelBackend'</span></code> 加入 <code class=\"docutils literal notranslate\"><span class=\"pre\">AUTHENTICATION_BACKENDS</span></code> 列表中，则当 <code class=\"docutils literal notranslate\"><span class=\"pre\">REMOTE_USER</span></code> 未指定时，就会回退使用 <code class=\"docutils literal notranslate\"><span class=\"pre\">ModelBackend</span></code>。</p>\n<p>Django 的用户管理系统，比如 <code class=\"docutils literal notranslate\"><span class=\"pre\">contrib.admin</span></code> 中的视图函数及 <a class=\"reference internal\" href=\"/zh-hans/3.1/ref/django-admin/#django-admin-createsuperuser\"><code class=\"xref std std-djadmin docutils literal notranslate\"><span class=\"pre\">createsuperuser</span></code></a> 的管理命令，都没有与远程用户集成。这些接口只工作在数据库中存储的用户上，无论 <code class=\"docutils literal notranslate\"><span class=\"pre\">AUTHENTICATION_BACKENDS</span></code> 为何值。</p>\n<aside class=\"admonition admonition-note\" role=\"note\">\n<p class=\"admonition-title\">Note</p>\n<p>因为 <code class=\"docutils literal notranslate\"><span class=\"pre\">RemoteUserBackend</span></code> 继承自 <code class=\"docutils literal notranslate\"><span class=\"pre\">ModelBackend</span></code>, 您仍将拥有在  <code class=\"docutils literal notranslate\"><span class=\"pre\">ModelBackend</span></code> 中实现的所有相同的权限检查。</p>\n<p>具有 <a class=\"reference internal\" href=\"/zh-hans/3.1/ref/contrib/auth/#django.contrib.auth.models.User.is_active\" title=\"django.contrib.auth.models.User.is_active\"><code class=\"xref py py-attr docutils literal notranslate\"><span class=\"pre\">is_active=False</span></code></a> 的用户将被禁止验证。你可以使用 <a class=\"reference internal\" href=\"/zh-hans/3.1/ref/contrib/auth/#django.contrib.auth.backends.AllowAllUsersRemoteUserBackend\" title=\"django.contrib.auth.backends.AllowAllUsersRemoteUserBackend\"><code class=\"xref py py-class docutils literal notranslate\"><span class=\"pre\">AllowAllUsersRemoteUserBackend</span></code></a> 来允许验证。</p>\n</aside>\n<p>如果你的验证机制使用一个自定义的 HTTP header 而不是 <code class=\"docutils literal notranslate\"><span class=\"pre\">REMOTE_USER</span></code>，你可以构建一个 <code class=\"docutils literal notranslate\"><span class=\"pre\">RemoteUserMiddleWare</span></code> 的子类然后把 <code class=\"docutils literal notranslate\"><span class=\"pre\">header</span></code> 属性设成你希望的 <code class=\"docutils literal notranslate\"><span class=\"pre\">request.META</span></code> 键值。例如:</p>\n<div class=\"code-block\" data-language=\"default\"><div class=\"code-block-toolbar\"><span class=\"code-block-language\">Code</span><button type=\"button\" class=\"copy-button\" data-copy hidden><span class=\"copy-button-label\">Copy</span></button></div><pre role=\"group\" tabindex=\"0\" aria-label=\"Code code\"><code><span class=\"kn\">from</span><span class=\"w\"> </span><span class=\"nn\">django.contrib.auth.middleware</span><span class=\"w\"> </span><span class=\"kn\">import</span> <span class=\"n\">RemoteUserMiddleware</span>\n\n<span class=\"k\">class</span><span class=\"w\"> </span><span class=\"nc\">CustomHeaderMiddleware</span><span class=\"p\">(</span><span class=\"n\">RemoteUserMiddleware</span><span class=\"p\">):</span>\n    <span class=\"n\">header</span> <span class=\"o\">=</span> <span class=\"s1\">&#39;HTTP_AUTHUSER&#39;</span>\n</code></pre></div>\n<aside class=\"admonition admonition-warning\" role=\"note\">\n<p class=\"admonition-title\">Warning</p>\n<p>使用具有自定义HTTP头部的 <code class=\"docutils literal notranslate\"><span class=\"pre\">RemoteUserMiddleware</span></code> 子类时需要特别小心。你要确保你的前端服务器基于验证检查结果正确设置或去除了该头部，禁止任何终端用户提交一个仿冒的头部值。因为HTTP头部 <code class=\"docutils literal notranslate\"><span class=\"pre\">X-Auth-User</span></code> 与（比方说） <code class=\"docutils literal notranslate\"><span class=\"pre\">X-Auth_User</span></code> 都会标准化为 <code class=\"docutils literal notranslate\"><span class=\"pre\">request.META</span></code> 的 <code class=\"docutils literal notranslate\"><span class=\"pre\">HTTP_X_AUTH_USER</span></code> 键，你必须确保你的服务器不允许头部使用下划线来替代横杠。</p>\n<p>这个警告不适用于 <code class=\"docutils literal notranslate\"><span class=\"pre\">RemoteUserMiddlewar</span></code>，它的默认配置为 <code class=\"docutils literal notranslate\"><span class=\"pre\">header</span> <span class=\"pre\">='REMOTE_USER'</span></code>, 因为在 <code class=\"docutils literal notranslate\"><span class=\"pre\">request.META</span></code> 中不存在以 <code class=\"docutils literal notranslate\"><span class=\"pre\">HTTP_</span></code> 开始的键可以只由WSGI服务器设置, 而不能直接来自HTTP请求头部.</p>\n</aside>\n<p>如果你需要更多控制, 你可以通过继承 <a class=\"reference internal\" href=\"/zh-hans/3.1/ref/contrib/auth/#django.contrib.auth.backends.RemoteUserBackend\" title=\"django.contrib.auth.backends.RemoteUserBackend\"><code class=\"xref py py-class docutils literal notranslate\"><span class=\"pre\">RemoteUserBackend</span></code></a>  并且覆盖其一个或多个属性和方法来创建你自己的验证后端.</p>\n</section>\n<section id=\"using-remote-user-on-login-pages-only\">\n<span id=\"persistent-remote-user-middleware-howto\"></span><h2>仅在登录界面使用 <code class=\"docutils literal notranslate\"><span class=\"pre\">REMOTE_USER</span></code><a class=\"heading-anchor\" href=\"#using-remote-user-on-login-pages-only\"><span class=\"visually-hidden\">Link to this heading</span><span aria-hidden=\"true\">#</span></a></h2>\n<p><code class=\"docutils literal notranslate\"><span class=\"pre\">RemoteUserMiddleware</span></code> 这个认证中间件 ，它假设HTTP请求的头部 <code class=\"docutils literal notranslate\"><span class=\"pre\">REMOTE_USER</span></code> 在所有认证请求中都存在。这个假设在当通过 <code class=\"docutils literal notranslate\"><span class=\"pre\">htpasswd</span></code> 或者相似的认证机制来做Basic HTTP的认证时才是可行的，但是使用Negotiate (GSSAPI/Kerberos) 或者其它资源密集型的认证方法时就说不过去了，前端HTTP server的认证通常用在仅仅一个或不太多的登录URLs，而且在认证成功后，应用还要自己去维护这个session。</p>\n<p><a class=\"reference internal\" href=\"/zh-hans/3.1/ref/middleware/#django.contrib.auth.middleware.PersistentRemoteUserMiddleware\" title=\"django.contrib.auth.middleware.PersistentRemoteUserMiddleware\"><code class=\"xref py py-class docutils literal notranslate\"><span class=\"pre\">PersistentRemoteUserMiddleware</span></code></a> 就针对这个使用场景提供了支持。除非用户显式地退出登录，它将一直保留已认证的会话。这个中间件可以代替上文中的 <a class=\"reference internal\" href=\"/zh-hans/3.1/ref/middleware/#django.contrib.auth.middleware.RemoteUserMiddleware\" title=\"django.contrib.auth.middleware.RemoteUserMiddleware\"><code class=\"xref py py-class docutils literal notranslate\"><span class=\"pre\">RemoteUserMiddleware</span></code></a>。</p>\n</section>","rootId":"authentication-using-remote-user","toc":[{"title":"配置","anchor":"configuration","children":[]},{"title":"仅在登录界面使用 REMOTE_USER","anchor":"using-remote-user-on-login-pages-only","children":[]}],"breadcrumbs":[{"docname":"howto/index","title":"操作指南","url":"/zh-hans/3.1/howto/"}],"prev":{"docname":"howto/index","title":"操作指南","url":"/zh-hans/3.1/howto/"},"next":{"docname":"howto/custom-management-commands","title":"编写自定义 django-admin 命令","url":"/zh-hans/3.1/howto/custom-management-commands/"},"formats":{"html":"/zh-hans/3.1/howto/auth-remote-user/","markdown":"/zh-hans/3.1/howto/auth-remote-user.md","json":"/zh-hans/3.1/howto/auth-remote-user.json"},"source":"https://github.com/django/django/blob/stable/3.1.x/docs/howto/auth-remote-user.txt","official":"https://docs.djangoproject.com/zh-hans/3.1/howto/auth-remote-user/","inVersions":["6.1","6.0","5.2","5.1","5.0","4.2","4.1","4.0","3.2","3.1","3.0","2.2","2.1","2.0"],"inLocales":["en","zh-hans","fr","ja","id","pt-br","ko","es","el","pl"]}