如何整合 Keycloak 以使用 Apache APISIX 進行身份驗證

2021 年 12 月 21 日，作者：Xinxin Zhu & Yilin Zeng

本文詳細說明如何透過 OpenID-Connect 協議和 Keycloak 在 Apache APISIX 中進行身份驗證。

Keycloak 是一個開源的身份和存取管理解決方案，適用於現代應用程式和服務。Keycloak 支援單一登入 (Single-Sign On)，使服務可以透過 OpenID Connect、OAuth 2.0 等協議與 Keycloak 介接。Keycloak 也支援與不同的身份驗證服務整合，例如 Github、Google 和 Facebook。

此外，Keycloak 還支援使用者聯合身分驗證，可以透過 LDAP 和 Kerberos 匯入使用者。有關 Keycloak 的更多資訊，請參閱官方文件。

Apache APISIX 是一個動態、即時、高效能的 API 閘道，提供豐富的流量管理功能。該專案提供負載平衡、動態上游、金絲雀發布、熔斷、身份驗證、可觀察性以及許多有用的外掛程式。此外，閘道支援動態外掛程式變更以及熱更新。Apache APISIX 的 OpenID Connect 外掛程式允許使用者透過 OpenID Connect 將傳統身份驗證模式替換為集中式身份驗證模式。

如何使用

安裝 Apache APISIX

安裝相依性

Apache APISIX 執行環境需要 NGINX 和 etcd 的相依性。

在安裝 Apache APISIX 之前，請根據您使用的作業系統安裝相依性。我們提供了 CentOS7、Fedora 31 和 32、Ubuntu 16.04 和 18.04、Debian 9 和 10 以及 macOS 的相依性安裝說明。有關更多詳細資訊，請參閱安裝相依性。

透過 RPM 套件安裝 (CentOS 7)

此安裝方法適用於 CentOS 7；請執行以下命令安裝 Apache APISIX。

sudo yum install -y https://github.com/apache/apisix/releases/download/2.7/apisix-2.7-0.x86_64.rpm

透過 Docker 安裝

請參閱使用 Docker 安裝 Apache APISIX。

透過 Helm Chart 安裝

請參閱使用 Helm Chart 安裝 Apache APISIX。

初始化相依性

執行以下命令來初始化 NGINX 設定檔和 etcd。

make init

啟動 Apache APISIX

執行以下命令來啟動 Apache APISIX。

apisix start

啟動 Keycloak

這裡我們使用 docker 來啟動 Keycloak。

docker run -p 8080:8080 -e KEYCLOAK_USER=admin -e KEYCLOAK_PASSWORD=password -e DB_VENDOR=h2  -d jboss/keycloak:9.0.2

執行後，您需要驗證 Keycloak 是否已成功啟動。

docker ps

設定 Keycloak

啟動 Keycloak 後，請使用您的瀏覽器存取「http://127.0.0.1:8080/auth/admin/」，並輸入 admin/password 帳戶密碼以登入管理員主控台。

建立領域

首先，您需要建立一個名為 apisix_test_realm 的領域。在 Keycloak 中，領域是專用於管理專案的工作區，不同領域的資源彼此隔離。

Keycloak 中的領域分為兩類：一類是 master realm，它是在 Keycloak 首次啟動時建立的，用於管理管理員帳戶和建立其他領域；另一類是 other realm，它是由 master realm 中的管理員建立的，可用於在此領域中建立、管理和使用使用者和應用程式。第二類是其他領域，由 master realm 中的管理員建立，使用者和應用程式可以在其中建立、管理和使用。如需更多詳細資訊，請參閱 Keycloak 中的領域和使用者部分。

Create realm
Edit realm title

建立客戶端

下一步是建立 OpenID Connect Client。在 Keycloak 中，Client 指的是允許向 Keycloak 發起身份驗證的客戶端。

在此範例場景中，Apache APISIX 等同於一個負責向 Keycloak 發起身份驗證請求的客戶端，因此我們建立一個名為 apisix 的客戶端。有關客戶端的更多詳細資訊，請參閱 Keycloak OIDC 客戶端。

Create OpenID Client
Create Client title

設定客戶端

建立客戶端後，您需要為該客戶端設定 Apache APISIX 存取類型。

在 Keycloak 中，有三種存取類型

  1. 機密 (Confidential)：用於需要執行瀏覽器登入的應用程式，客戶端將透過 client secret 取得 access token，主要用於由伺服器呈現的 Web 系統。

  2. 公開 (Public)：用於需要執行瀏覽器登入的應用程式，主要用於使用 vue 和 react 實作的前端專案。

  3. 僅限持有者 (Bearer-only)：用於不需要執行瀏覽器登入的應用程式，僅允許使用 bearer token 存取，主要用於 RESTful API 場景。

有關客戶端設定的更多詳細資訊，請參閱 Keycloak OIDC 客戶端進階設定。

由於我們使用 Apache APISIX 作為伺服器端的客戶端，我們可以選擇「機密」存取類型或「僅限持有者」存取類型。在下面的示範中，我們使用「機密」存取類型作為範例。

Set Client type

建立使用者

Keycloak 支援與其他第三方使用者系統介接，例如 Google 和 Facebook，或者使用 LDAP 匯入或手動建立使用者。在這裡，我們將使用「手動建立使用者」進行示範。

Create user
Add user info

然後在「認證 (Credentials)」頁面中設定使用者的密碼。

Set user password

建立路由

設定 Keycloak 後，您需要建立路由並開啟 Openid-Connect 外掛程式。有關此外掛程式設定的詳細資訊，請參閱Apache APISIX OpenID-Connect 外掛程式。

取得 client_id 和 client_secret

Get client information

在上面的設定中。

  • client_id 是之前建立客戶端時使用的名稱，即 apisix

  • client_secret 應從 Clients-apisix-Credentials 中取得，例如：d5c42c50-3e71-4bbbe-aa9e-31083ab29da4。

取得探索設定

Get configuration

前往「領域設定 (Realm Settings)」-「一般 (General)」-「端點 (Endpoints)」，選擇「OpenID 端點設定 (OpenID Endpoint Configuration)」連結並複製該連結指向的位址，例如：`http://127.0.0.1:8080/auth/realms/apisix_test_realm/.well-known/openid-configuration`。

建立路由並啟用外掛程式

使用以下命令存取 Apache APISIX 管理介面以建立路由，將上游設定為 httpbin.org，並啟用 OpenID Connect 外掛程式進行身份驗證。

注意：如果您在建立客戶端時選擇 bearer-only 作為存取類型，則在設定路由時需要將 bearer_only 設定為 true，以便存取 Apache APISIX 時不會跳轉到 Keycloak 登入畫面。

curl  -XPOST 127.0.0.1:9080/apisix/admin/routes -H "X-Api-Key: edd1c9f034335f136f87ad84b625c8f1" -d '{
    "uri":"/*",
    "plugins":{
        "openid-connect":{
            "client_id":"apisix",
            "client_secret":"d5c42c50-3e71-4bbe-aa9e-31083ab29da4",
            "discovery":"http://127.0.0.1:8080/auth/realms/apisix_test_realm/.well-known/openid-configuration",
            "scope":"openid profile",
            "bearer_only":false,
            "realm":"apisix_test_realm",
            "introspection_endpoint_auth_method":"client_secret_post",
            "redirect_uri":"http://127.0.0.1:9080/"
        }
    },
    "upstream":{
        "type":"roundrobin",
        "nodes":{
            "httpbin.org:80":1
        }
    }
}'

存取測試

完成上述設定後，我們準備在 Apache APISIX 中執行相關的存取測試。

存取 Apache APISIX

使用您的瀏覽器存取 http://127.0.0.1:9080/image/png。

由於已啟用 OpenID-Connect 外掛程式且 bearer-only 設定為 false，因此當您第一次存取此路徑時，Apache APISIX 會將您重新導向至 Keycloak 中 apisix_test_realm 設定的登入畫面並發出使用者登入請求。

Login page

輸入在 Keycloak 設定期間建立的使用者 peter 以完成使用者登入。

成功存取

成功登入後，瀏覽器會再次將連結重新導向至 http://127.0.0.1:9080/image/png 並成功存取影像內容。該內容與上游 http://httpbin.org/image/png 的內容相同。

Access successfully

登出

測試完成後，請使用您的瀏覽器存取 http:/127.0.0.1:9080/logout 以登出您的帳戶。

注意：登出路徑可以使用 OpenID-Connect 外掛程式設定中的 logout_path 指定，預設為 logout。

總結

本文說明了如何使用 OpenID-Connect 協議和 Keycloak 在 Apache APISIX 中進行身份驗證的步驟。透過與 Keycloak 整合，Apache APISIX 可以設定為驗證使用者和應用程式服務，這大大減少了開發工作。

有關 Apache APISIX 中身份驗證實作的更多資訊，請參閱Apache APISIX 部落格。