mod_auth_mellon Apache 模块

使用 Keycloak 配置 mod_auth_mellon Apache 模块

The mod_auth_mellon 是 Apache 的身份验证模块。 如果您的语言/环境支持使用 Apache HTTPD 作为代理，那么您可以使用 mod_auth_mellon 来使用 SAML 保护您的 Web 应用程序。 有关此模块的更多详细信息，请参阅 mod_auth_mellon GitHub 存储库。

Keycloak 不提供对 mod_auth_mellon 的任何官方支持。 以下说明是尽力而为的，可能不是最新的。 本指南假设服务器是 RHEL 系统。 尽管其他 Linux 系统需要类似的步骤。 我们建议您详细了解官方 mod_auth_mellon 文档。

要配置 mod_auth_mellon，您需要以下文件

  • 一个身份提供者 (IdP) 实体描述符 XML 文件，它描述了与 Keycloak 或其他 SAML IdP 的连接

  • 一个 SP 实体描述符 XML 文件，它描述了您要保护的应用程序的 SAML 连接和配置。

  • 一个私钥 PEM 文件，它是一个 PEM 格式的文本文件，定义了应用程序用于签署文档的私钥。

  • 一个证书 PEM 文件，它是一个定义应用程序证书的文本文件。

  • 特定于 mod_auth_mellon 的 Apache HTTPD 模块配置。

如果您已经在 Keycloak 应用程序服务器上的域中定义和注册了客户端应用程序，Keycloak 可以生成您需要的除 Apache HTTPD 模块配置之外的所有文件。

执行以下步骤生成 Apache HTTPD 模块配置。

步骤

  1. 转到 SAML 客户端的安装页面。

  2. 选择Mod Auth Mellon 文件选项。

    Download auth-melon configuration
    图 1. mod_auth_mellon 配置下载

  3. 单击下载以下载包含您需要的 XML 描述符和 PEM 文件的 ZIP 文件。

使用 Keycloak 配置 mod_auth_mellon

涉及两个主机

  • 运行 Keycloak 的主机，它将被称为 $idp_host，因为 Keycloak 是一个 SAML 身份提供者 (IdP)。

  • 运行 Web 应用程序的主机，它将被称为 $sp_host。 在 SAML 中，使用 IdP 的应用程序被称为服务提供者 (SP)。

所有以下步骤都需要在 $sp_host 上以 root 权限执行。

安装软件包

要安装必要的软件包，您将需要

  • Apache Web 服务器 (httpd)

  • Apache 的 Mellon SAML SP 附加模块

  • 创建 X509 证书的工具

要安装必要的软件包，请运行此命令

yum install httpd mod_auth_mellon mod_ssl openssl

为 Apache SAML 创建一个配置目录

建议将与 Apache 使用 SAML 相关的配置文件保存在一个位置。

在 Apache 配置根目录 /etc/httpd 下创建一个名为 saml2 的新目录

mkdir /etc/httpd/saml2

配置 Mellon 服务提供者

Apache 附加模块的配置文件位于 /etc/httpd/conf.d 目录中，并且具有 .conf 的文件名扩展名。 您需要创建 /etc/httpd/conf.d/mellon.conf 文件并将 Mellon 的配置指令放入其中。

Mellon 的配置指令可以粗略地分为两类信息

  • 使用 SAML 身份验证保护哪些 URL

  • 引用受保护的 URL 时将使用哪些 SAML 参数。

Apache 配置指令通常遵循 URL 空间中的分层树结构，称为位置。 您需要为 Mellon 指定一个或多个 URL 位置来保护。 您在添加适用于每个位置的配置参数的方式上具有灵活性。 您可以在位置块中添加所有必要的参数，也可以将 Mellon 参数添加到 URL 位置层次结构中较高的公共位置，特定受保护位置继承该位置（或两者兼而有之）。 由于 SP 通常以相同的方式运行，无论哪个位置触发 SAML 操作，此处使用的示例配置将公共 Mellon 配置指令放置在层次结构的根目录中，然后可以使用最少的指令定义要由 Mellon 保护的特定位置。 此策略避免了为每个受保护位置重复相同的参数。

此示例只有一个受保护位置：https://$sp_host/private。

要配置 Mellon 服务提供者，请执行以下步骤。

步骤

  1. 使用以下内容创建文件 /etc/httpd/conf.d/mellon.conf

 <Location / >
    MellonEnable info
    MellonEndpointPath /mellon/
    MellonSPMetadataFile /etc/httpd/saml2/mellon_metadata.xml
    MellonSPPrivateKeyFile /etc/httpd/saml2/mellon.key
    MellonSPCertFile /etc/httpd/saml2/mellon.crt
    MellonIdPMetadataFile /etc/httpd/saml2/idp_metadata.xml
 </Location>
 <Location /private >
    AuthType Mellon
    MellonEnable auth
    Require valid-user
 </Location>
上面代码中引用的某些文件将在后续步骤中创建。

设置 mod_auth_mellon 使用的 cookie 的 SameSite 值

浏览器计划将 cookie 的 SameSite 属性的默认值设置为 Lax。 此设置意味着只有在请求源自同一域的情况下，才会将 cookie 发送到应用程序。 此行为会影响 SAML POST 绑定，这可能会导致其无法正常工作。 为了保持 mod_auth_mellon 模块的完整功能，我们建议将 mod_auth_mellon 创建的 cookie 的 SameSite 值设置为 None。 如果不这样做，可能会导致无法使用 Keycloak 登录。

要将 SameSite 值设置为 None，请将以下配置添加到 <Location / > 标记内的 mellon.conf 文件中。

MellonSecureCookie On
MellonCookieSameSite none

对该配置的支持在版本 0.16.0 及更高版本的 mod_auth_mellon 模块中可用。

创建服务提供者元数据

在 SAML 中，IdP 和 SP 交换 SAML 元数据，该元数据采用 XML 格式。 元数据的模式是一个标准，因此确保参与的 SAML 实体可以使用彼此的元数据。 您需要

  • SP 使用的 IdP 的元数据

  • 描述提供给 IdP 的 SP 的元数据

SAML 元数据的组成部分之一是 X509 证书。 这些证书用于两种目的

  • 签署 SAML 消息，以便接收方可以证明消息源自预期方。

  • 在传输过程中加密消息（很少使用，因为 SAML 消息通常发生在受 TLS 保护的传输上）

如果您已经有证书颁发机构 (CA)，您可以使用自己的证书，也可以生成自签名证书。 为简单起见，此示例使用自签名证书。

因为 Mellon 的 SP 元数据必须反映已安装的 mod_auth_mellon 版本的功能，必须是有效的 SP 元数据 XML，并且必须包含 X509 证书（除非您熟悉 X509 证书生成，否则证书的创建可能很繁琐），因此生成 SP 元数据的最便捷方式是使用 mod_auth_mellon 包中包含的工具 (mellon_create_metadata.sh)。 生成的元数据始终可以在以后编辑，因为它是一个文本文件。 该工具还会创建您的 X509 密钥和证书。

SAML IdP 和 SP 使用称为 EntityID 的唯一名称来标识自己。 要使用 Mellon 元数据创建工具，您需要

  • EntityID，它通常是 SP 的 URL，并且通常是 SP 可以检索 SP 元数据的 URL

  • SP 将接收 SAML 消息的 URL，Mellon 称之为 MellonEndPointPath。

要创建 SP 元数据，请执行以下步骤。

步骤

  1. 创建一些辅助 shell 变量

    fqdn=`hostname`
mellon_endpoint_url="https://${fqdn}/mellon"
mellon_entity_id="${mellon_endpoint_url}/metadata"
file_prefix="$(echo "$mellon_entity_id" | sed 's/[^A-Za-z.]/_/g' | sed 's/__*/_/g')"

  2. 通过运行以下命令调用 Mellon 元数据创建工具

    /usr/libexec/mod_auth_mellon/mellon_create_metadata.sh $mellon_entity_id $mellon_endpoint_url

  3. 将生成的文件移到它们的目的地（在上面创建的 /etc/httpd/conf.d/mellon.conf 文件中引用）

    mv ${file_prefix}.cert /etc/httpd/saml2/mellon.crt
mv ${file_prefix}.key /etc/httpd/saml2/mellon.key
mv ${file_prefix}.xml /etc/httpd/saml2/mellon_metadata.xml

将 Mellon 服务提供者添加到 Keycloak 身份提供者

假设：Keycloak IdP 已经安装在 $idp_host 上。

Keycloak 支持多个租户，其中所有用户、客户端等都分组在称为域的东西中。 每个域都是独立于其他域的。 您可以使用 Keycloak 中的现有域，但此示例展示了如何创建一个名为 test_realm 的新域并使用该域。

所有这些操作都是使用 Keycloak 管理控制台执行的。 您必须拥有 $idp_host 的管理员用户名和密码才能执行以下步骤。

步骤

  1. 打开管理控制台并输入管理员用户名和密码登录。

    登录管理控制台后，将存在一个现有域。 当 Keycloak 首次设置时，默认情况下会创建一个根域 master。 任何以前创建的域都将在管理控制台的左上角的下拉列表中列出。

  2. 从域下拉列表中选择添加域。

  3. 在名称字段中键入 test_realm 并单击创建。

将 Mellon 服务提供者作为域的客户端添加

在 Keycloak 中，SAML SP 被称为客户端。 要添加 SP，我们必须位于域的客户端部分。

  1. 单击左侧的客户端菜单项，然后单击导入客户端按钮。

  2. 在资源文件字段中，提供上面创建的 Mellon SP 元数据文件 (/etc/httpd/saml2/mellon_metadata.xml)。

    根据您的浏览器运行的位置，您可能需要将 SP 元数据从 $sp_host 复制到浏览器运行的机器上，以便浏览器可以找到该文件。

  3. 单击保存。

编辑 Mellon SP 客户端

使用此步骤设置重要的客户端配置参数。

步骤

  1. 确保强制使用 POST 绑定已开启。

  2. 将 paosResponse 添加到有效的重定向 URI 列表中

  3. 复制有效的重定向 URI 中的 postResponse URL 并将其粘贴到下面的空白添加文本字段中。

  4. 将 postResponse 更改为 paosResponse`。（paosResponse URL 是 SAML ECP 所需的。）

  5. 单击底部的保存。

许多 SAML SP 会根据用户的组成员身份确定授权。 Keycloak IdP 可以管理用户组信息，但除非 IdP 配置为将其作为 SAML 属性提供，否则它不会提供用户的组。

执行以下步骤将 IdP 配置为将用户的组作为 SAML 属性提供。

步骤

  1. 单击客户端的客户端范围选项卡。

  2. 单击第一行中的专用范围。

  3. 在映射器页面中，单击添加映射器按钮并选择通过配置。

  4. 从映射器类型列表中选择组列表。

  5. 将名称设置为 group list。

  6. 将 SAML 属性名称设置为 groups。

  7. 单击保存。

剩余步骤在 $sp_host 上执行。

检索身份提供者元数据

现在您已经在 IdP 上创建了域，您需要检索与其关联的 IdP 元数据，以便 Mellon SP 识别它。 在之前创建的 /etc/httpd/conf.d/mellon.conf 文件中，MellonIdPMetadataFile 指定为 /etc/httpd/saml2/idp_metadata.xml，但直到现在，该文件在 $sp_host 上并不存在。

使用此步骤从 IdP 检索该文件。

步骤

  1. 使用此命令，用 $idp_host 的正确值替换

    curl -k -o /etc/httpd/saml2/idp_metadata.xml \
https://$idp_host/realms/test_realm/protocol/saml/descriptor

    Mellon 现在已完全配置。

  2. 要对 Apache 配置文件运行语法检查，请使用此命令

    apachectl configtest
    Configtest 等效于 apachectl 的 -t 参数。 如果配置测试显示任何错误，请在继续之前更正它们。

  3. 重新启动 Apache 服务器

    systemctl restart httpd.service

您现在已将 Keycloak 设置为 test_realm 中的 SAML IdP，并将 mod_auth_mellon 设置为 SAML SP，通过针对 $idp_host IdP 身份验证来保护 URL $sp_host/protected（以及其下的所有内容）。

在此页面上
编辑此指南