客戶端註冊 CLI

使用 CLI 自動化客戶端註冊

客戶端註冊 CLI 是一個命令列介面 (CLI) 工具，供應用程式開發人員在與 Keycloak 整合時，以自助方式設定新的客戶端。它專門設計用於與 Keycloak 客戶端註冊 REST 端點互動。

任何應用程式若要使用 Keycloak，都必須建立或取得客戶端設定。通常，您會為每個託管於唯一主機名稱上的新應用程式設定一個新的客戶端。當應用程式與 Keycloak 互動時，應用程式會使用客戶端 ID 來識別自己，以便 Keycloak 可以提供登入頁面、單一登入 (SSO) 工作階段管理和其他服務。

您可以使用客戶端註冊 CLI 從命令列設定應用程式客戶端，並且可以在 Shell Script 中使用它。

若要允許特定使用者使用 客戶端註冊 CLI，Keycloak 管理員通常會使用管理控制台來設定具有適當角色的新使用者，或設定新的客戶端和客戶端密碼，以授予對客戶端註冊 REST API 的存取權。

設定要與客戶端註冊 CLI 一起使用的新一般使用者

步驟

  1. 以 admin 身分登入管理控制台（例如，https://127.0.0.1:8080）。

  2. 選取要管理的領域。

  3. 如果您要使用現有的使用者，請選取該使用者進行編輯；否則，請建立新的使用者。

  4. 選取「角色對應」、「指派角色」。從選項清單中，按一下「依客戶端篩選」。在搜尋列中，輸入 manage-clients。選取角色，或者如果您在主領域中，請選取具有 NAME-realm 的角色，其中 NAME 是目標領域的名稱。您可以將存取權授予給主領域中的使用者，使其存取任何其他領域。

  5. 按一下「指派」，以授予完整的客戶端管理權限。另一個選項是選擇 view-clients 以進行唯讀，或選擇 create-client 以建立新客戶端。

  6. 選取「可用角色」、「manage-client」以授予完整的客戶端管理權限。另一個選項是選擇 view-clients 以進行唯讀，或選擇 create-client 以建立新客戶端。

    這些權限授予使用者執行操作的能力，而無需使用初始存取權杖或註冊存取權杖（如需詳細資訊，請參閱 客戶端註冊服務）。

可以不為使用者指派任何 realm-management 角色。在這種情況下，使用者仍然可以使用客戶端註冊 CLI 登入，但若沒有初始存取權杖則無法使用。嘗試在沒有權杖的情況下執行任何操作會導致 403 Forbidden 錯誤。

管理員可以從管理控制台的「客戶端」區域中的「初始存取權杖」標籤中發行初始存取權杖。

設定要與客戶端註冊 CLI 一起使用的客戶端

預設情況下，伺服器會將客戶端註冊 CLI 識別為 admin-cli 客戶端，該客戶端會自動為每個新領域設定。當使用使用者名稱登入時，不需要額外的客戶端設定。

步驟

  1. 如果您要為客戶端註冊 CLI 使用單獨的客戶端設定，請建立一個客戶端（例如，reg-cli）。

  2. 取消選取「啟用標準流程」。

  3. 將「客戶端驗證」切換為「開啟」以加強安全性。

  4. 選擇您要使用的帳戶類型。

    1. 如果您要使用與客戶端關聯的服務帳戶，請勾選「服務帳戶角色」。

    2. 如果您偏好使用一般使用者帳戶，請勾選「直接存取授權」。

  5. 按一下「下一步」。

  6. 按一下「儲存」。

  7. 按一下「憑證」標籤。

    設定 客戶端 ID 和密碼 或 簽署的 JWT。

  8. 如果您使用的是服務帳戶角色，請按一下「服務帳戶角色」標籤。

    選取要設定服務帳戶存取權的角色。如需有關選取哪些角色的詳細資訊，請參閱 設定要與客戶端註冊 CLI 一起使用的新一般使用者。

  9. 按一下「儲存」。

當您執行 kcreg config credentials 時，請使用 --secret 選項來提供設定的密碼。

  • 在執行 kcreg config credentials 時，請指定要使用的 clientId （例如，--client reg-cli）。

  • 啟用服務帳戶後，您可以省略執行 kcreg config credentials 時指定的使用者，而僅提供客戶端密碼或金鑰儲存資訊。

安裝客戶端註冊 CLI

客戶端註冊 CLI 會封裝在 Keycloak 伺服器發行版中。您可以在 bin 目錄中找到執行 Script。Linux Script 稱為 kcreg.sh，而 Windows Script 稱為 kcreg.bat。

設定客戶端以從檔案系統上的任何位置使用時，請將 Keycloak 伺服器目錄新增至您的 PATH。

例如，在

  • Linux

$ export PATH=$PATH:$KEYCLOAK_HOME/bin
$ kcreg.sh

  • Windows

c:\> set PATH=%PATH%;%KEYCLOAK_HOME%\bin
c:\> kcreg

KEYCLOAK_HOME 是指解壓縮 Keycloak 伺服器發行版的目錄。

使用客戶端註冊 CLI

步驟

  1. 透過使用您的憑證登入來啟動已驗證的工作階段。

  2. 在 客戶端註冊 REST 端點上執行命令。

    例如，在

    • Linux

      $ kcreg.sh config credentials --server https://127.0.0.1:8080 --realm demo --user user --client reg-cli
$ kcreg.sh create -s clientId=my_client -s 'redirectUris=["https://127.0.0.1:8980/myapp/*"]'
$ kcreg.sh get my_client

    • Windows

      c:\> kcreg config credentials --server https://127.0.0.1:8080 --realm demo --user user --client reg-cli
c:\> kcreg create -s clientId=my_client -s "redirectUris=[\"https://127.0.0.1:8980/myapp/*\"]"
c:\> kcreg get my_client

      在生產環境中，必須使用 https: 來存取 Keycloak，以避免將權杖暴露給網路嗅探器。

  3. 如果伺服器的憑證不是由 Java 的預設憑證信任儲存區中包含的受信任憑證授權單位 (CA) 發行的，請準備 truststore.jks 檔案，並指示客戶端註冊 CLI 使用它。

    例如，在

    • Linux

      $ kcreg.sh config truststore --trustpass $PASSWORD ~/.keycloak/truststore.jks

    • Windows

      c:\> kcreg config truststore --trustpass %PASSWORD% %HOMEPATH%\.keycloak\truststore.jks

登入

步驟

  1. 當您使用客戶端註冊 CLI 登入時，請指定伺服器端點 URL 和領域。

  2. 指定使用者名稱或客戶端 ID，這會導致使用特殊的服務帳戶。當使用使用者名稱時，您必須使用指定使用者的密碼。當使用客戶端 ID 時，您可以使用客戶端密碼或 簽署的 JWT 而不是密碼。

無論使用哪種登入方法，登入的帳戶都需要適當的權限才能執行客戶端註冊作業。請記住，非主領域中的任何帳戶都只能具有管理相同領域內客戶端的權限。如果您需要管理不同的領域，您可以在不同的領域中設定多個使用者，或者您可以在 master 領域中建立單一使用者，並新增在不同領域中管理客戶端的角色。

您無法使用客戶端註冊 CLI 設定使用者。請使用管理控制台網頁介面或管理客戶端 CLI 來設定使用者。如需更多詳細資訊，請參閱 伺服器管理指南。

當 kcreg 成功登入時，它會收到授權權杖，並將其儲存在私有設定檔中，以便權杖可以用於後續的調用。如需有關設定檔的更多資訊，請參閱 使用替代設定。

如需有關使用客戶端註冊 CLI 的更多資訊，請參閱內建說明。

例如，在

  • Linux

$ kcreg.sh help

  • Windows

c:\> kcreg help

如需有關啟動已驗證的工作階段的更多資訊，請參閱 kcreg config credentials --help。

使用替代設定

預設情況下，客戶端註冊 CLI 會自動在預設位置 ./.keycloak/kcreg.config（位於使用者主目錄下）維護設定檔。您可以使用 --config 選項來指向不同的檔案或位置，以平行維護多個已驗證的工作階段。這是從單一執行緒執行與單一設定檔關聯的操作的最安全方法。

請勿讓系統上的其他使用者看到設定檔。設定檔包含應保持私有的存取權杖和密碼。

您可能會想避免將密碼儲存在設定檔中，方法是在所有命令中使用 --no-config 選項，儘管這樣不太方便，而且需要更多權杖請求。請在每次 kcreg 調用中指定所有驗證資訊。

初始存取權杖和註冊存取權杖

沒有在要使用的 Keycloak 伺服器上設定帳戶的開發人員可以使用客戶端註冊 CLI。只有在領域管理員向開發人員發行初始存取權杖時，才能執行此操作。由領域管理員決定如何以及何時發行和分發這些權杖。領域管理員可以限制初始存取權杖的最長期限以及可以使用它建立的客戶端總數。

開發人員取得初始存取權杖後，可以使用它來建立新客戶端，而無需使用 kcreg config credentials 進行驗證。初始存取權杖可以儲存在設定檔中，或者指定為 kcreg create 命令的一部分。

例如，在

  • Linux

$ kcreg.sh config initial-token $TOKEN
$ kcreg.sh create -s clientId=myclient

或

$ kcreg.sh create -s clientId=myclient -t $TOKEN

  • Windows

c:\> kcreg config initial-token %TOKEN%
c:\> kcreg create -s clientId=myclient

或

c:\> kcreg create -s clientId=myclient -t %TOKEN%

當使用初始存取權杖時，伺服器回應會包含新發行的註冊存取權杖。該客戶端的任何後續操作都需要透過使用該權杖進行驗證來執行，該權杖僅對該客戶端有效。

客戶端註冊 CLI 會自動使用其私有設定檔來儲存和使用此權杖及其關聯的客戶端。只要所有客戶端操作都使用相同的設定檔，開發人員就不需要驗證即可讀取、更新或刪除以此方式建立的客戶端。

如需有關初始存取權杖和註冊存取權杖的更多資訊，請參閱 客戶端註冊服務。

執行 kcreg config initial-token --help 和 kcreg config registration-token --help 命令，以取得有關如何使用客戶端註冊 CLI 設定權杖的更多資訊。

建立客戶端設定

使用憑證驗證或設定初始存取權杖後的第一項任務通常是建立新的客戶端。通常，您可能會想使用準備好的 JSON 檔案作為範本，並設定或覆寫某些屬性。

以下範例說明如何讀取 JSON 檔案、覆寫其中可能包含的任何客戶端 ID、設定任何其他屬性，以及在成功建立後將設定列印到標準輸出。

  • Linux

$ kcreg.sh create -f client-template.json -s clientId=myclient -s baseUrl=/myclient -s 'redirectUris=["/myclient/*"]' -o

  • Windows

C:\> kcreg create -f client-template.json -s clientId=myclient -s baseUrl=/myclient -s "redirectUris=[\"/myclient/*\"]" -o

如需有關 kcreg create 命令的更多資訊，請執行 kcreg create --help。

您可以使用 kcreg attrs 列出可用的屬性。請記住，許多設定屬性不會檢查有效性或一致性。由您自行指定正確的值。請記住，您的範本中不應有任何 ID 欄位，也不應將它們指定為 kcreg create 命令的引數。

擷取客戶端設定

您可以使用 kcreg get 命令擷取現有的客戶端。

例如，在

  • Linux

$ kcreg.sh get myclient

  • Windows

C:\> kcreg get myclient

您也可以將客戶端設定擷取為配接器設定檔，您可以將其與您的 Web 應用程式一起封裝。

例如，在

  • Linux

$ kcreg.sh get myclient -e install > keycloak.json

  • Windows

C:\> kcreg get myclient -e install > keycloak.json

如需有關 kcreg get 命令的更多資訊，請執行 kcreg get --help 命令。

修改客戶端設定

有兩種方法可以更新客戶端設定。

一種方法是在取得目前的設定後，將完整的全新狀態提交至伺服器，將其儲存至檔案、編輯，然後再發佈回伺服器。

例如，在

  • Linux

$ kcreg.sh get myclient > myclient.json
$ vi myclient.json
$ kcreg.sh update myclient -f myclient.json

  • Windows

C:\> kcreg get myclient > myclient.json
C:\> notepad myclient.json
C:\> kcreg update myclient -f myclient.json

第二種方法是提取目前的客戶端，設定或刪除其中的欄位，然後一步發佈回去。

例如，在

  • Linux

$ kcreg.sh update myclient -s enabled=false -d redirectUris

  • Windows

C:\> kcreg update myclient -s enabled=false -d redirectUris

您也可以使用僅包含要套用變更的檔案，這樣您就不必將太多值指定為引數。在這種情況下，請指定 --merge，以告知客戶端註冊 CLI，不要將 JSON 檔案視為完整的全新設定，而是將其視為要套用在現有設定上的屬性集。

例如，在

  • Linux

$ kcreg.sh update myclient --merge -d redirectUris -f mychanges.json

  • Windows

C:\> kcreg update myclient --merge -d redirectUris -f mychanges.json

執行 kcreg update --help 命令，以取得有關 kcreg update 命令的更多資訊。

刪除客戶端設定

使用以下範例來刪除客戶端。

  • Linux

$ kcreg.sh delete myclient

  • Windows

C:\> kcreg delete myclient

執行 kcreg delete --help 命令，以取得有關 kcreg delete 命令的更多資訊。

重新整理無效的註冊存取權杖

當使用 --no-config 模式執行建立、讀取、更新和刪除 (CRUD) 操作時，客戶端註冊 CLI 無法為您處理註冊存取權杖。在這種情況下，可能會遺失客戶端最近發行的註冊存取權杖，這會導致無法在不使用具有 manage-clients 權限的帳戶進行驗證的情況下，對該客戶端執行任何進一步的 CRUD 操作。

如果您具有權限，您可以為客戶端發行新的註冊存取權杖，並將其列印到標準輸出或儲存到您選擇的設定檔中。否則，您必須請 realm 管理員為您的客戶端發行新的註冊存取權杖，並將其傳送給您。然後，您可以透過 --token 選項將其傳遞給任何 CRUD 命令。您也可以使用 kcreg config registration-token 命令將新權杖儲存到設定檔中，並讓客戶端註冊 CLI 從那時起自動為您處理它。

執行 kcreg update-token --help 命令，以取得有關 kcreg update-token 命令的更多資訊。

疑難排解

  • 問：登入時，我收到錯誤訊息：Parameter client_assertion_type is missing [invalid_client]。

    答：此錯誤表示您的客戶端已設定 Signed JWT 權杖憑證，這表示您在登入時必須使用 --keystore 參數。

本頁內容
編輯本指南