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 應用程式伺服器上的領域中定義並註冊了用戶端應用程式，則 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)。

以下所有步驟都需要在具有 root 權限的 $sp_host 上執行。

安裝套件

要安裝必要的套件，您需要

  • Apache Web 伺服器 (httpd)

  • Mellon SAML SP 的 Apache 外掛程式模組

  • 建立 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 空間中的階層樹狀結構，稱為位置。您需要指定一個或多個要由 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，請將以下設定新增至 mellon.conf 檔案中的 <Location / > 標籤內。

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

  • 將使用 Mellon 稱為 MellonEndPointPath 的 SP 的 SAML 訊息的 URL。

要建立 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`。（SAML ECP 需要 paosResponse URL。）

  5. 點擊底部的 儲存。

許多 SAML SP 會根據使用者在群組中的成員資格來判斷授權。Keycloak IdP 可以管理使用者群組資訊，但除非將 IdP 設定為以 SAML 屬性提供資訊，否則不會提供使用者的群組。

執行以下步驟，將 IdP 設定為以 SAML 屬性提供使用者的群組。

步驟

  1. 點擊用戶端的 用戶端範圍 標籤。

  2. 點擊第一列中的專用範圍。

  3. 在 [對應器] 頁面中，點擊 新增對應器 按鈕，然後選取 依設定。

  4. 從 [對應器類型] 清單中選取 群組清單。

  5. 將 [名稱] 設定為 群組清單。

  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

您現在已在 test_realm 中將 Keycloak 設定為 SAML IdP，並將 mod_auth_mellon 設定為 SAML SP，保護 URL $sp_host/protected（以及其下的所有內容），透過向 $idp_host IdP 驗證身分。

在本頁面
編輯本指南