---
title: "在 Web 应用前加上登录 | FoxAuth"
description: "用你的 Caddy、Traefik 或 nginx 代理和一个 FoxAuth 项目，保护没有自带登录的 Web 应用，例如 Grafana，无需改动应用。"
canonical: "https://foxauth.dev/zh-cn/docs/get-started/put-sign-in-in-front-of-a-web-app/"
lastmod: "2026-11-06T22:50:09+03:00"
---
在 Web 应用前加上登录

有些 Web 应用没有自带登录：一个看板、一个内部工具，或者有人花一个下午写出来的管理页面。任何知道地址的人都能打开它们。你可以在不改动应用的情况下解决这个问题：把应用放在你的代理后面，让代理在每个请求到达应用之前先询问 FoxAuth。

这种方式叫作 forward auth。你的反向代理（Caddy、Traefik 或 nginx）站在应用前面。对于每个请求，它都会询问你的 FoxAuth 项目这个请求能否通过。尚未登录的人会被送到项目的登录页面。可以打开这个页面的人会被放行，应用也会得知这个人是谁。不能打开的人会看到一个说明原因的页面。

如果你的代理已经在为这个应用提供服务，整个过程大约需要十分钟。

事先需要准备的

一个带有管理员账户的运行中实例（见创建第一个管理员），一个有用户的项目，以及其中至少一个用户组。应用必须通过一个你可以配置的代理以
https 提供服务。

1. 在控制台中创建应用Section titled “1. 在控制台中创建应用”

打开你的项目，选择 Applications 标签页，然后点击 New application。

选择 A web app with no sign-in of its own。

填写四项内容：

Name：控制台中显示的应用名称。

Address：应用自己的 https 地址，例如 https://grafana.example.com。只保留协议、主机和端口。如果你粘贴的地址带有路径或查询参数，表单会去掉它们并告诉你。

Who can open it：一个或多个用户组。只有这些组的成员才能打开应用。之后你可以把应用的某些部分开放给其他人。

Proxy：Caddy、Traefik 或 nginx。它只决定下一步首先显示哪种配置。

应用会出现在 Applications 标签页上单独的一张表中。它的页面有三个部分：Connect、Access 和 Settings。

2. 配置你的代理Section titled “2. 配置你的代理”

Connect 会显示你的代理所需的配置，其中已经填好项目地址和应用 ID。请从那里复制。下面的示例是同一段文字，由同一段代码生成，对应的是项目地址为 https://auth.example.com/acme、应用地址为 https://grafana.example.com 的情况。<appId> 处会是你的应用 ID。

每份配置都做三件事：

先把每个请求送到 https://auth.example.com/acme/verify/<appId> 进行检查，并带上请求原始的方法、主机和路径。缺少其中任何一项的请求都会被检查拒绝。

删除浏览器发来的所有 X-Auth-* 请求头，这样就没有人能冒充别人。

把请求连同检查返回的请求头一起转发给应用。

示例假定应用本身监听 127.0.0.1:8080。请换成它的真实地址。

CaddySection titled “Caddy”

Caddyfile

grafana.example.com {

route {

request_header -X-Auth-*

forward_auth https://auth.example.com {

uri /acme/verify/<appId>

header_up Host {upstream_hostport}

copy_headers X-Auth-User X-Auth-Email X-Auth-Groups X-Auth-Assertion X-Auth-Reason

}

reverse_proxy 127.0.0.1:8080

}

}

route 块会保持指令的书写顺序。没有它，Caddy 会在检查设置好 X-Auth-* 请求头之后再把它们删掉。

TraefikSection titled “Traefik”

Traefik dynamic configuration

http:

middlewares:

foxauth:

forwardAuth:

address: "https://auth.example.com/acme/verify/<appId>"

trustForwardHeader: false

authResponseHeadersRegex: "^X-Auth-"

preserveLocationHeader: true

routers:

app:

rule: "Host(`grafana.example.com`)"

entryPoints:

- websecure

middlewares:

- foxauth

service: app

tls: {}

services:

app:

loadBalancer:

servers:

- url: "http://127.0.0.1:8080"

这是一份供 file provider 使用的动态配置。authResponseHeadersRegex 会删除浏览器发来的所有 X-Auth-* 请求头，并复制检查返回的那些。preserveLocationHeader 让登录跳转保持指向项目。

nginxSection titled “nginx”

nginx server block

server {

listen 443 ssl;

server_name grafana.example.com;

# ssl_certificate and ssl_certificate_key for grafana.example.com

location / {

auth_request /_foxauth_check;

auth_request_set $foxauth_x_auth_user $upstream_http_x_auth_user;

auth_request_set $foxauth_x_auth_email $upstream_http_x_auth_email;

auth_request_set $foxauth_x_auth_groups $upstream_http_x_auth_groups;

auth_request_set $foxauth_x_auth_assertion $upstream_http_x_auth_assertion;

auth_request_set $foxauth_x_auth_reason $upstream_http_x_auth_reason;

error_page 401 403 = @foxauth;

proxy_set_header X-Auth-User $foxauth_x_auth_user;

proxy_set_header X-Auth-Email $foxauth_x_auth_email;

proxy_set_header X-Auth-Groups $foxauth_x_auth_groups;

proxy_set_header X-Auth-Assertion $foxauth_x_auth_assertion;

proxy_set_header X-Auth-Reason $foxauth_x_auth_reason;

proxy_set_header Host $host;

proxy_pass http://127.0.0.1:8080;

}

location = /_foxauth_check {

internal;

proxy_pass https://auth.example.com/acme/verify/<appId>?mode=status;

proxy_set_header X-Forwarded-Host $host;

proxy_set_header X-Forwarded-Uri $request_uri;

proxy_set_header X-Forwarded-Method $request_method;

proxy_set_header Host auth.example.com;

proxy_ssl_server_name on;

proxy_pass_request_body off;

proxy_set_header Content-Length "";

}

location /_foxauth/ {

rewrite ^ /acme/verify/<appId>? break;

proxy_pass https://auth.example.com;

proxy_redirect off;

proxy_set_header X-Forwarded-Host $host;

proxy_set_header X-Forwarded-Uri $request_uri;

proxy_set_header X-Forwarded-Method $request_method;

proxy_set_header Host auth.example.com;

proxy_ssl_server_name on;

proxy_pass_request_body off;

proxy_set_header Content-Length "";

}

location @foxauth {

rewrite ^ /acme/verify/<appId>? break;

proxy_pass https://auth.example.com;

proxy_redirect off;

proxy_set_header X-Forwarded-Host $host;

proxy_set_header X-Forwarded-Uri $request_uri;

proxy_set_header X-Forwarded-Method $request_method;

proxy_set_header Host auth.example.com;

proxy_ssl_server_name on;

proxy_pass_request_body off;

proxy_set_header Content-Length "";

}

}

nginx 的 auth_request 只理解三种答复：允许、未登录和拒绝。因此只向检查索取状态，登录跳转和拒绝页面则来自第二次调用。这次调用用于错误页面，以及 /_foxauth/ 下属于登录流程的路径。请在注释所在的位置加上证书配置。

3. 确保只能通过你的代理访问应用Section titled “3. 确保只能通过你的代理访问应用”

检查只保护经过你的代理的请求。通过其他途径到达应用的请求会跳过检查，应用也会相信它携带的任何 X-Auth-* 请求头。

所以要让应用只在代理能访问到的地方监听：127.0.0.1、私有网络，或者只允许代理通过的防火墙规则之后。Connect 也会提醒这一点，因为这是 FoxAuth 唯一无法替你完成的部分。

如果应用能够校验签名，它也可以不再依赖这一点。见下面的 X-Auth-Assertion。

4. 你的应用会收到什么Section titled “4. 你的应用会收到什么”

请求被放行时，代理会加上这些请求头：

请求头
内容

X-Auth-User
这个人在项目中的标识符。它永远不会改变，所以请用它来识别这个人。

X-Auth-Email
这个人的电子邮件地址。

X-Auth-Groups
这个人所属用户组的标识符，用逗号分隔。请按标识符匹配，而不是按组名：组名可能会变。

X-Auth-Assertion
同样的信息，用项目的密钥签名。它是一个 JWT，受众（audience）是你的应用地址，有效期 60 秒。其中还包含用户组的名称。

X-Auth-Reason
本次决定的简短代码，例如 allowed。拒绝也会带上代码，例如 not_in_group 或 no_session，这样代理的访问日志就能说明为什么某人被拒绝。

在对任何人开放的路径上，前四个请求头仍然存在，但内容为空。

如果应用用项目在其 jwks_uri 上公开的密钥来校验 X-Auth-Assertion，它就能确认这些信息来自项目，不必再相信每个请求都经过了代理。

5. 确认一切正常Section titled “5. 确认一切正常”

Connect 会显示四个步骤，并标出每一步第一次发生的时间：

应用已创建。

代理就这个应用询问了本项目。

有人通过代理登录。

有人被放行。

在浏览器的隐私窗口中打开应用。你应该先看到项目的登录页面，登录后回到你原本要打开的页面。如果第 2 步一直是空的，说明代理没有发送检查请求。如果 Connect 显示了一个与应用地址不同的主机，说明代理没有传递原始主机。

要退出应用，请在应用自己的地址上打开 /_foxauth/sign_out。

决定谁能打开哪一部分Section titled “决定谁能打开哪一部分”

Access 以树的形式列出规则，每个路径一条。规则说明谁可以打开这个路径及其下的所有内容：

一个或多个用户组的成员；

项目允许登录的所有人；

任何人，无需登录（只适用于 GET 和 HEAD，并且只针对这个路径本身，除非你同时开放它下面的所有内容）；

任何人都不行。

由匹配的最长路径决定，所以规则的顺序无关紧要。/admin 的规则同样适用于 /admin/users 和 /Admin/users。如果一次保存会让更多人能打开任何路径，控制台会列出这些放宽之处并请你确认。同一标签页上的访问检查会告诉你，某个人现在以及保存之后能否打开指定地址。

路径还可以要求更多：只允许来自你的网络、只在你设定的时间内、只允许某个部门，或要求近期登录。请参阅在代理处添加条件。

提示

在代理后面运行 FoxAuth 本身是另一项任务，见 Behind a reverse
proxy。

上一页用 OAuth 保护 MCP 服务器下一页在代理处保护 MCP 服务器
