在 Web 应用前加上登录
有些 Web 应用没有自带登录:一个看板、一个内部工具,或者有人花一个下午写出来的管理页面。任何知道地址的人都能打开它们。你可以在不改动应用的情况下解决这个问题:把应用放在你的代理后面,让代理在每个请求到达应用之前先询问 FoxAuth。
这种方式叫作 forward auth。你的反向代理(Caddy、Traefik 或 nginx)站在应用前面。对于每个请求,它都会询问你的 FoxAuth 项目这个请求能否通过。尚未登录的人会被送到项目的登录页面。可以打开这个页面的人会被放行,应用也会得知这个人是谁。不能打开的人会看到一个说明原因的页面。
如果你的代理已经在为这个应用提供服务,整个过程大约需要十分钟。
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。请换成它的真实地址。
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
Section titled “Traefik”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 让登录跳转保持指向项目。
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。如果一次保存会让更多人能打开任何路径,控制台会列出这些放宽之处并请你确认。同一标签页上的访问检查会告诉你,某个人现在以及保存之后能否打开指定地址。
路径还可以要求更多:只允许来自你的网络、只在你设定的时间内、只允许某个部门,或要求近期登录。请参阅在代理处添加条件。