mod_auth_mellon Apache 模块

使用 Keycloak 配置 mod_auth_mellon Apache 模块

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 应用程序服务器上的 realm 中定义和注册了客户端应用程序，则 Keycloak 可以生成您需要的所有文件，除了 Apache HTTPD 模块配置。

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

步骤

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

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

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

  3. 单击 下载 下载一个 ZIP 文件，其中包含您需要的 XML 描述符和 PEM 文件。

使用 Keycloak 配置 mod_auth_mellon

涉及两个主机

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

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

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

安装软件包

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

  • 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 的配置指令大致可以分为两类信息

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

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

Apache 配置指令通常遵循 URL 空间中的分层树结构，这称为位置。您需要指定一个或多个 URL 位置供 Mellon 保护。您可以灵活地添加应用于每个位置的配置参数。您可以将所有必要的参数添加到位置块，也可以将 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

mod_auth_mellon 模块版本 0.16.0 及更高版本中提供了对此配置的支持。

创建服务提供商元数据

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

  • SP 使用的 IdP 的元数据

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

SAML 元数据的组件之一是 X509 证书。这些证书用于两个目的

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

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

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

因为 Mellon 的 SP 元数据必须反映已安装的 mod_auth_mellon 版本的 capabilities，必须是有效的 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 支持多租户，其中所有用户、客户端等都分组在称为 realm 的内容中。每个 realm 都独立于其他 realm。您可以使用 Keycloak 中现有的 realm，但此示例演示如何创建一个名为 test_realm 的新 realm 并使用该 realm。

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

步骤

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

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

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

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

将 Mellon 服务提供商作为 realm 的客户端添加

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

  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 上创建了 realm，您需要检索与其关联的 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（及其下所有内容）。

在此页面上
编辑本指南