forward_auth

一个用于将请求的克隆代理到身份验证网关的意见化指令，该网关可以决定是否继续处理，或需要将请求发送到登录页面。

• 语法
• 展开形式
• 示例
  • Authelia
  • Tailscale

Caddy 的 reverse_proxy 能够向外部服务执行“预检请求”，但此指令专门为身份验证用例量身定制。此指令实际上只是使用以下更长但更常见配置的一种便捷方式。

此指令对配置的上游进行一次带有重写后 uri 的 GET 请求：

• 如果上游响应 2xx 状态码，则授予访问权限，并将 copy_headers 中的报头字段复制到原始请求中，然后继续处理。
• 否则，如果上游响应任何其他状态码，则将上游的响应原样复制回客户端。此响应通常会包含重定向到身份验证网关登录页面的操作。

如果此行为不是您所需要的，您可以采用下面的展开形式作为基础并根据需要自定义。

reverse_proxy 的所有子指令都受支持，并会传递给底层的 reverse_proxy 处理器。

Syntax

forward_auth [<matcher>] [<upstreams...>] {
	uri          <to>
	copy_headers <fields...> {
		<fields...>
	}
}

• <upstreams...> 是用于发送认证请求的上游（后端）列表。

• uri 是发送到上游的请求中要设置的 URI（路径和查询）。这通常是身份验证网关的验证端点。

• copy_headers 是在请求返回成功状态码时，要从响应复制到原始请求的 HTTP 头字段列表。

  可以通过使用 > 后跟新名称来重命名字段，例如 Before>After。

  若为可读性考虑，你可以使用块格式列出所有字段，每行一个字段。

由于此指令是对反向代理的意见化封装，你可以使用任何 reverse_proxy 的子指令来定制它。

Expanded form

forward_auth 指令等同于以下配置。像 Authelia 这样的认证网关与此预设配合良好。如果你的认证网关不完全匹配，欢迎借鉴此配置并根据需要自定义，而不是使用 forward_auth 快捷方式。

reverse_proxy <upstreams...> {
	# 始终使用 GET，这样就不会消费传入请求的主体
	method GET

	# 将 URI 更改为认证网关的验证端点
	rewrite <to>

	# 转发原始的方法和 URI，因为它们在上面被重写了；
	# 这是在 reverse_proxy 已设置的其他 X-Forwarded-* 报头之外的补充
	header_up X-Forwarded-Method {method}
	header_up X-Forwarded-Uri {uri}

	# 在成功响应时，复制响应头
	@good status 2xx
	handle_response @good {
		# 例如，对于每个 copy_headers 字段...
		request_header Remote-User {rp.header.Remote-User}
		request_header Remote-Email {rp.header.Remote-Email}
	}
}

Examples

Authelia

在通过反向代理为你的应用提供服务之前，将身份验证委托给 Authelia：

# 提供认证网关本身的服务
auth.example.com {
	reverse_proxy authelia:9091
}

# 提供你的应用服务
app1.example.com {
	forward_auth authelia:9091 {
		uri /api/authz/forward-auth
		copy_headers Remote-User Remote-Groups Remote-Name Remote-Email
	}

	reverse_proxy app1:8080
}

有关更多信息，请参阅 Authelia 的文档，了解如何与 Caddy 集成。

Tailscale

将身份验证委托给 Tailscale（目前名为 nginx-auth，但它仍可与 Caddy 一起使用），并使用 copy_headers 的替代语法来重命名复制的头（注意每个头中的 >）：

forward_auth unix//run/tailscale.nginx-auth.sock {
	uri /auth
	header_up Remote-Addr {remote_host}
	header_up Remote-Port {remote_port}
	header_up Original-URI {uri}
	copy_headers {
		Tailscale-User>X-Webauth-User
		Tailscale-Name>X-Webauth-Name
		Tailscale-Login>X-Webauth-Login
		Tailscale-Tailnet>X-Webauth-Tailnet
		Tailscale-Profile-Picture>X-Webauth-Profile-Picture
	}
}