跳转到内容

在 Web 应用前加上登录

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

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

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

  1. 打开你的项目,选择 Applications 标签页,然后点击 New application。
  2. 选择 A web app with no sign-in of its own。
  3. 填写四项内容:
    • Name:控制台中显示的应用名称。
    • Address:应用自己的 https 地址,例如 https://grafana.example.com。只保留协议、主机和端口。如果你粘贴的地址带有路径或查询参数,表单会去掉它们并告诉你。
    • Who can open it:一个或多个用户组。只有这些组的成员才能打开应用。之后你可以把应用的某些部分开放给其他人。
    • Proxy:Caddy、Traefik 或 nginx。它只决定下一步首先显示哪种配置。

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

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。请换成它的真实地址。

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-* 请求头之后再把它们删掉。

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 让登录跳转保持指向项目。

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。

请求被放行时,代理会加上这些请求头:

请求头 内容
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,它就能确认这些信息来自项目,不必再相信每个请求都经过了代理。

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

  1. 应用已创建。
  2. 代理就这个应用询问了本项目。
  3. 有人通过代理登录。
  4. 有人被放行。

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

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

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

  • 一个或多个用户组的成员;
  • 项目允许登录的所有人;
  • 任何人,无需登录(只适用于 GET 和 HEAD,并且只针对这个路径本身,除非你同时开放它下面的所有内容);
  • 任何人都不行。

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

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