原文作者：Derek DeJonghe
原文链接：将 NGINX 配置为 SAML 身份验证的服务提供商 | 《NGINX 完全指南》章节精选
转载来源：NGINX 开源社区

NGINX 唯一中文官方社区 ，尽在 nginx.org.cn

编者按——由 O'Reilly 出版的经典书籍《NGINX 完全指南》中文版（2024 年最新版）现已正式上线。

《NGINX 完全指南》涵盖了最新的 NGINX 操作指南和使用技巧，提供了针对 100 多个实际应用交付用例的最新解决方案。本书内容丰富全面，探讨了 NGINX 的大部分主要特性，是 NGINX 学习及实操的必备指南。

本书最新版不仅更新了许多章节来介绍 NGINX 的新功能，还增添了新章节来讨论可扩展的安全防护功能以及如何有效利用 HTTP/2、HTTP/3 (QUIC) 和 gRPC。

本文选自 2024 年最新版《NGINX完全指南》，点击此处免费下载电子版全本。

问题

您希望将 NGINX Plus 与 SAML 身份验证供应商 (IdP) 相集成，以保护资源。

解决方案

此解决方案利用了 NGINX Plus 键值存储，因此仅适用于 NGINX Plus。此外，它还使用了 NGINX JavaScript (njs) 模块。首先安装 njs。

使用 APT 软件包管理器的 NGINX Plus：

$ apt install nginx-plus-module-njs

使用 YUM 软件包管理器的 NGINX Plus：

$ yum install nginx-plus-module-njs

上面的操作将 njs 安装为动态模块。您需要将以下内容添加到 nginx.conf 配置，从而指示 NGINX Plus 加载该模块：

load_module modules/ngx_http_js_module.so;

下载、解压并移动 SAML JavaScript 和 NGINX Plus 配置文件，以激活此功能：

$ wget https://github.com/nginxinc/nginx-saml/archive/refs/heads/main.zip 
    -0 nginx-saml-main.zip
$ unzip nginx-saml-main.zip
$ mv nginx-saml-main/* /etc/nginx/conf.d/

NGINX Plus SAML 解决方案尚无法解析标准 SAML XML 配置文件。您需要更新在前面步骤中下载的配置文件，以便与您的系统相集成。以下是每个文件的描述以及所需更新内容的说明：

saml_sp_configuration.conf

在 map{} 代码块中包含一个或多个服务提供商 (SP) 和 IdP 的主要配置。可使用映射功能根据 $host 变量配置多个 SP 或 IdP。

• 修改所有提供带 $saml_sp_ 前缀的变量的 map 代码块，以匹配 SP 配置。
• 修改所有提供带 $saml_idp_ 前缀的变量的 map 代码块，以匹配 IdP 配置。
• 修改提供 $saml_log out_redirect 变量的 map 代码块中定义的 URI，以指定在请求 /logout location 后显示的未受保护资源。
• 如果 NGINX Plus 部署在另一个代理或负载均衡器后面，请修改 $redirect_base 和 $proto 变量的映射，以定义获取原始协议和端口号的方式。

frontend.conf

使用 SAML 解决方案通过导入 saml_sp.server_conf 文件来保护资源的反向代理配置示例。

• 在服务器配置中复制 include conf.d/saml_sp.server_conf;。
• 当请求未经授权时，使用 error_page 指令启动 SAML SP 流。在需要保护的 location 代码块中添加以下内容：

error_page 401 = @do_samlsp_flow;
if ($saml_access_granted != "1") {
return 401;
}

• 使用经过身份验证的用户名设置上游请求的请求头：

proxy_set_header username: $saml_name_id;

• 可选择通过更新传递给 error_log 指令的 level 参数来更新日志级别。

saml_sp.server_conf

用于处理 IdP 响应的 NGINX 配置。

• 该文件通常无需更改。
• 为了进行优化，修改 client_body_buffer_size 指令，以匹配最大 IdP 响应（post 正文）大小。

saml_sp.js

用于执行 SAML 身份验证的 JavaScript 代码。

• 无需更改。

详解

此解决方案结合使用了 NGINX JavaScript 模块与 NGINX Plus 键值存储模块，支持 NGINX 作为 SAML 服务提供商 (SP) 通过单点登录保护资源。

F5 公司的 NGINX 团队在 GitHub 上以公共仓库的形式提供了 JavaScript 代码（需要将其安装到配置中并启用）。

端点和密钥的配置及其他 SAML 配置由一系列 map 代码块提供给 JavaScript 代码，以便根据所处理请求的主机名配置多个 SP 或 IdP。配置 SP 和 IdP 后，您可将 saml_sp.server_conf 添加到服务器配置中，并在 NGINX Plus 未为用户保存会话时使用 error_page 指令启动与 IdP 的 SP 流。

SP 流会将用户定向到 IdP 以使用现有会话或登录，成功后，用户将被重定向到 NGINX Plus，并收到经过 NGINX Plus 验证并存储在键值存储中的 SAML 响应。SAML 响应的密钥将以 cookie 的形式返回给客户端，供后续请求使用，最后，客户端将被定向回最初请求的资源。

该解决方案还支持 SAML 单点注销 (SLO)，允许用户通过单个操作注销所有 SP 和 IdP。这一操作既可由 SP 发起，也可由 IdP 发起。当 SP 发起注销时，NGINX Plus 会向 IdP 发送 LogoutRequest 消息。然后，IdP 终止用户会话，并向 NGINX Plus 返回 LogoutResponse 消息，NGINX Plus 会删除存储在该用户会话键值存储中的值。

当 IdP 发起注销时，它负责以 SP 的身份联系 NGINX Plus，并通过向已注册的 Logout URL 发送 LogoutRequest 来启动注销流程。在此过程中，NGINX Plus 会从与用户会话相关的键值存储中删除值，并向 IdP 返回 LogoutResponse 消息。

如果 IdP 不支持 SLO 功能，或者您不希望 NGINX Plus SP 允许使用该功能，则可将其禁用。要禁用 SLO，请将 $saml_idp_slo_url 的变量映射配置设置为空字符串。

立即下载

《NGINX 完全指南》英文纸质版原价为 $40 美元（含税价约为300元人民币），现可扫描下方二维码或点击此处前往 NGINX 中文官网免费下载电子版全本。

NGINX 唯一中文官方社区 ，尽在 nginx.org.cn

更多 NGINX 相关的技术干货、互动问答、系列课程、活动资源： 开源社区官网 | 微信公众号 | B 站