Keycloak安裝與配置

• 安裝 Keycloak
• 配置 Keycloak 對接 SuperMap iServer/iPortal/iEdge
• 配置 Keycloak 對接 SuperMap iDesktop
• 添加角色
• 添加用戶

安裝 Keycloak

下載安裝 Keycloak，這里以 win64 系統為例，Keycloak 官網下載地址：https://www.keycloak.org/downloads

本示例下載 keycloak-4.0.0.Final.zip，需求的 Java 版本為 JDK 1.8及以上。下載完成后，解壓縮文件，雙擊運行 keycloak-4.0.0.Final/bin 目錄下的 standalone.bat 文件，啟動 Keycloak。

Keycloak 的本地訪問地址為：http://localhost:8080/auth/，訪問該地址，點擊頁面中的“Administration Console“，創建 Keycloak 的管理員賬戶，該賬戶用於在 Keycloak 中進行配置，管理用戶、角色等。

您可以通過以下方式配置使用 IP並更改 Keycloak 的端口：

在 keycloak-4.0.0.Final/bin 目錄下，執行以下 DOS 命令：

standalone.bat -Djboss.socket.binding.port-offset=100 -Djboss.bind.address=192.168.112.172

• -Djboss.socket.binding.port-offset：設置端口偏移量，100表示默認端口號+100，此時 Keycloak 端口號更改為：8180
• -Djboss.bind.address：設置 Keycloak 所在機器的 IP 地址

配置 Keycloak 對接 SuperMap iServer/iPortal/iEdge

訪問 Keycloak 服務地址：http://localhost:8080/auth/，點擊頁面中的“Administration Console“，進入 Keycloak 登錄頁面，輸入創建好的 Keycloak 的管理員賬戶，登錄 Keycloak。您可以通過以下方式切換 Keycloak 的語言環境，默認為英文，該示例中，將語言切換至中文：

點擊左側導航欄中的“Realm Settings”,在右側頁面選擇“Themes”選項卡，其中，“Login Theme”項、“Account Theme”項、“Admin Console Theme”項、“Email Theme”項全部選擇“keycloak”，“Internationalization Enabled”項選擇“ON”，開啟國際化，“Default Locale”選擇“zh-CN”,最后點擊“Save”按鈕。

此時，管理員登出，在 Keycloak 的登錄頁面會顯示語言切換項，選擇“中文簡體”，登錄 Keycloak。

接下來您需要在 Keycloak 中進行以下配置：

1. 添加域

Keycloak 默認的域為 Master，您可以使用默認的 Master 域，也可以新添加一個域。鼠標移動到左側導航欄 Master 域名上，在下拉按鈕中點擊“添加域”，輸入域名稱，例如：ispeco，點擊“創建”按鈕，此時，進入到新創建的 ispeco，進行以下配置。需要注意的是，域和域之間的資源（包括用戶、角色、客戶端等一切信息）是相互隔離的。

2. 創建一個客戶端

左側導航欄選擇“客戶端”，在右側頁面點擊“創建”按鈕，添加客戶端：

• “客戶端 ID”：輸入“客戶端 ID”，這個“客戶端 ID"您可以隨意命名，例如：ispeco-oidc。需要注意的是，這個"客戶端 ID”與在 SuperMap iServer/iPortal/iEdge 中的“Keycloak 登錄配置”的“客戶端 ID”一致。
• “客戶端協議”：選擇默認的 openid-connect。

• 點擊“保存”按鈕，進入客戶端配置詳情頁面，選擇“設置”選項卡，按照下圖所示繼續配置：

最后點擊“保存”按鈕。

說明：“有效的重定向 URL”是填寫 Keycloak 所允許的哪些應用（業務）系統（URL）能夠使用 Keycloak 的認證授權服務，支持填寫多個，填寫格式建議為：服務根地址后面加上/*號。

• 選擇“憑據”選項卡，如下圖所示：

說明：“秘密”即客戶端密鑰，與在 SuperMap iServer/iPortal/iEdge 中的“Keycloak 登錄配置”的“客戶端密鑰”一致。

• 選擇“Mappers”選項卡，配置角色映射，點擊“創建”按鈕，創建協議映射器，配置如下圖所示：

說明：

• “名稱”：映射器的名稱，可隨意填寫，例如：roles，建議與下面的“Token申請名”保持一致。
• “Realm角色前綴”：Keycloak 將用戶的角色信息返回給客戶端時，自動將每個角色帶上的一個前綴。可隨意填寫，例如：KC_。如果不填，代表原樣傳給客戶端。（該值對應 SuperMap iServer/iPortal/iEdge 中的“Keycloak登錄配置”中的“屬性角色關聯信息配置”添加角色映射時的“屬性值”的前綴）
• “Token申請名”：建議與上面的“名稱”保持一致，例如：roles。Keycloak 將用戶的角色信息返回給客戶端時，客戶端可以從哪個屬性中獲取角色信息（該值對應於 SuperMap iServer/iPortal/iEdge 中的“Keycloak登錄配置”中的“角色屬性標識”）

至此，完成了 Keycloak 客戶端與 SuperMap iServer/iPortal/iEdge 的對接。之后，您還需要在創建的客戶端中進行添加角色、添加用戶等操作。

配置 Keycloak 對接 SuperMap iDesktop

這里以創建好的 ispeco 域為例，創建一個客戶端，客戶端 ID 命名為：iDesktop，這個是 SuperMap 約定的一個客戶端 ID 名稱，如下圖所示：

點擊“保存”按鈕，進入如下圖所示的詳細配置頁面：

說明：“有效的重定向 URL”填寫 urn:ietf:wg:oauth:2.0:oob。

至此，對接桌面 SuperMap iDesktop 的 Keycloak 配置完成。打開 SuperMap iDesktop 時，可以直接使用 Keycloak 中的賬戶登錄 SuperMap iServer/iPortal/iEdge。

添加角色

接下來，您可以點擊導航欄中的“角色”，開始添加角色，您可以根據使用需求，創建多個角色，角色名稱建議與 SuperMap iServer/iPortal/iEdge 中的角色名稱保持一致，例如：DATA_CENTER，該角色在 SuperMap iServer/iPortal/iEdge 中的“Keycloak登錄配置”中的“屬性角色關聯信息配置”中會加上前綴 KC_進行顯示，例如：KC_DATA_CENTER。

添加用戶

添加完角色后，您就可以進行創建用戶操作。Keycloak 允許直接由管理員添加用戶與開放用戶注冊兩種方式進行用戶的添加。

• 管理員添加用戶

1. 管理員在 Keycloak 管理頁面中點擊左側導航欄中的“用戶”，進行添加用戶操作。點擊“添加用戶”按鈕，進行用戶信息的填寫，其中用戶名為必填項，其余可按需求進行填寫，完成后點擊“保存”按鈕。

2. 選擇“憑據”選項卡，填寫並確認密碼，並關閉“臨時”選項。

    

3. 選擇“角色映射”選項卡，選中要分配給用戶的角色，點擊“添加選擇”按鈕，完成角色的分配。至此，完成管理員添加用戶流程。

 

• 開放用戶注冊

1. 在 Keycloak 登錄頁面中可以開放用戶的注冊功能，管理員需要在 Keycloak 管理頁面中進行配置。選擇左側導航欄“領域設置”，點擊“登錄”選項卡，啟用“用戶注冊”選項，其余設置可按需求進行選擇性啟用，完畢后點擊“保存”按鈕。

2. 啟用注冊后還需要進行默認的角色分配，否則注冊用戶將因為沒有分配的角色而無法登錄 SuperMap iServer/iPortal/iEdge 。選擇左側導航欄“角色”選項，點擊“默認角色”，選中所要分配給注冊用戶的默認角色，點擊“添加選擇”按鈕，即完成了默認角色的分配，推薦賦予用戶默認 PORTAL_USER 角色，具體的角色信息請參見角色和權限。

3. 完成注冊功能開啟和默認角色分配后，需要在 SuperMap iServer/iPortal/iEdge 中進行 Keycloak 的對接，具體方法參見：配置使用Keycloak進行認證授權。對接完成后在 SuperMap iServer/iPortal/iEdge 中點擊“登錄”按鈕，即跳轉到 Keycloak 登錄頁面，可在頁面右側找到用戶注冊入口。至此，完成用戶注冊功能的啟用。

以上，完成了 Keycloak 的安裝與配置過程。