Keycloak 單一登入

Last reviewed 2025-01-13 UTC

本指南說明如何使用 SAML 同盟,在 Keycloak 與 Cloud Identity 或 Google Workspace 帳戶之間設定單一登入 (SSO)。本文假設您已安裝並使用 Keycloak。

目標

  • 設定 Keycloak 伺服器,讓 Cloud Identity 或 Google Workspace 能夠使用該伺服器做為身分識別提供者 (IdP)。
  • 設定 Cloud Identity 或 Google Workspace 帳戶,以便使用 Keycloak 進行單一登入。

事前準備

  1. 如果您沒有 Cloud Identity 帳戶,請註冊帳戶
  2. 確認 Cloud Identity 帳戶具備超級管理員權限。
  3. 如果 Keycloak 伺服器用於管理多個領域,請決定要將哪個領域用於同盟。
  4. 確認您具備所選領域的管理員存取權。

建立 SAML 設定檔

如要設定 Keycloak 單一登入,請先在 Cloud Identity 或 Google Workspace 帳戶中建立 SAML 設定檔。SAML 設定檔包含與 Keycloak 伺服器相關的設定,包括網址和簽署憑證。

之後再將 SAML 設定檔指派給特定群組或機構單位。

如要在 Cloud Identity 或 Google Workspace 帳戶中建立新的 SAML 設定檔,請按照下列步驟操作:

  1. 在管理控制台中,依序前往「安全性」>「驗證」>「使用第三方 IdP 的單一登入 (SSO) 服務」

    前往「使用第三方 IdP 的單一登入 (SSO) 服務」

  2. 依序按一下「第三方單一登入 (SSO) 設定檔」>「新增 SAML 設定檔」

  3. 在「SAML SSO profile」頁面中,輸入下列設定:

    • Name (名稱):Keycloak
    • IdP 實體 ID

      Keycloak 17 以上版本

      https://KEYCLOAK/realms/REALM
      

      Keycloak 16 以下版本

      https://KEYCLOAK/auth/realms/REALM
      
    • 登入頁面網址

      Keycloak 17 以上版本

      https://KEYCLOAK/realms/REALM/protocol/saml
      

      Keycloak 16 以下版本

      https://KEYCLOAK/auth/realms/REALM/protocol/saml
      
    • 登出網頁網址

      Keycloak 17 以上版本

      https://KEYCLOAK/realms/REALM/protocol/openid-connect/logout
      

      Keycloak 16 以下版本

      https://KEYCLOAK/auth/realms/REALM/protocol/openid-connect/logout?redirect_uri=https://KEYCLOAK/auth/realms/REALM/account/
      
    • 變更密碼網址

      Keycloak 17 以上版本

      https://KEYCLOAK/realms/REALM/account
      

      Keycloak 16 以下版本

      https://KEYCLOAK/auth/realms/REALM/account
      

    在所有網址中,請替換下列項目:

    • KEYCLOAK:Keycloak 伺服器的完整網域名稱
    • REALM:所選領域的名稱

    暫時不要上傳驗證憑證。

  4. 按一下 [儲存]

    隨即顯示「SAML SSO 設定檔」頁面,內含兩個網址:

    • 實體 ID
    • ACS 網址

    您會在下一節設定 Keycloak 時需要這些網址。

設定 Keycloak

建立用戶端即可設定 Keycloak 伺服器。

建立用戶端

在 Keycloak 中建立新的 SAML 用戶端:

  1. 登入 Keycloak 並開啟管理控制台。
  2. 選取要用於同盟的領域。
  3. 在選單中選取「用戶端」
  4. 按一下「建立用戶端」
  5. 為用戶端設定下列設定:

    Keycloak 19 以上版本

    • 用戶端類型SAML
    • 用戶端 ID:SSO 設定檔中的實體網址
    • Name (名稱):Google Cloud

    Keycloak 18 以下版本

    • 用戶端 ID:SSO 設定檔中的實體網址
    • 用戶端通訊協定saml
    • Client SAML Endpoint:留空
  6. 按一下 [儲存]

  7. 設定下列設定,指定用戶端詳細資料:

    Keycloak 19 以上版本

    在「設定」分頁中:

    • 有效的重新導向 URI:單一登入 (SSO) 設定檔中的 ACS 網址
    • 名稱 ID 格式電子郵件
    • 強制使用名稱 ID 格式開啟
    • 簽署文件關閉
    • 簽署聲明開啟

    在「Keys」分頁中:

    • 需要用戶端簽章關閉

    Keycloak 18 以下版本

    • 名稱:名稱,例如 Google Cloud
    • 簽署聲明開啟
    • 需要用戶端簽章關閉
    • 強制使用名稱 ID 格式開啟
    • 名稱 ID 格式電子郵件
    • 有效的重新導向 URI:單一登入 (SSO) 設定檔中的 ACS 網址

    保留其他設定的預設值。

  8. 按一下 [儲存]

匯出簽署憑證

Keycloak 驗證完使用者之後,會將 SAML 宣告傳遞給 Cloud Identity 或 Google Workspace。為讓 Cloud Identity 和 Google Workspace 驗證該判斷的完整性和真實性,Keycloak 會使用特殊的權杖簽署金鑰簽署判斷,並提供憑證,讓 Cloud Identity 或 Google Workspace 檢查簽章。

現在從 Keycloak 匯出簽署憑證:

  1. 在選單中選取「領域設定」
  2. 選取「金鑰」分頁標籤。
  3. 找出「演算法:RS256」的資料列。如果有多個資料列,請使用「使用:SIG」的資料列。然後選取「認證」

    系統會顯示對話方塊,內含以 Base64 編碼的憑證。

  4. 將 Base64 編碼的憑證值複製到剪貼簿。

您必須先加入標頭和頁尾,將簽署憑證轉換為 PEM 格式,才能使用該憑證。

  1. 開啟文字編輯器,例如記事本或 vim。
  2. 貼上下列標頭,然後換行:

    -----BEGIN CERTIFICATE-----
    
  3. 從剪貼簿貼上 Base64 編碼憑證。

  4. 新增換行符,然後貼上下列頁尾:

    -----END CERTIFICATE-----
    

    變更後,檔案看起來會像以下這樣:

    -----BEGIN CERTIFICATE-----
    MIICmzCCAYMCBgF7v8/V1TANBgkq...
    -----END CERTIFICATE-----
    
  5. 將檔案儲存到電腦的暫存位置。

完成 SAML 設定檔

您可以使用簽署憑證完成 SAML 設定檔的設定:

  1. 返回管理控制台,然後依序前往「安全性」>「驗證」>「使用第三方 IdP 的單一登入 (SSO) 服務」

    前往「使用第三方 IdP 的單一登入 (SSO) 服務」

  2. 開啟先前建立的 Keycloak SAML 設定檔。

  3. 按一下「IDP 詳細資料」部分,編輯設定。

  4. 按一下「上傳憑證」,然後挑選您先前下載的符記簽署憑證。

  5. 按一下 [儲存]

SAML 設定檔已完成,但您仍需指派設定檔。

指派 SAML 設定檔

選取要套用新 SAML 設定檔的使用者:

  1. 在管理控制台的「使用第三方 IdP 的單一登入 (SSO) 服務」頁面中, 依序點選「管理單一登入 (SSO) 設定檔指派作業」>「管理」

    前往「管理單一登入 (SSO) 設定檔指派作業」

  2. 在左側窗格中,選取要套用單一登入 (SSO) 設定檔的群組或機構單位。如要為所有使用者套用設定檔,請選取根機構單位。

  3. 在右側窗格中,選取「Another SSO profile」(其他 SSO 設定檔)

  4. 在選單中,選取您先前建立的 Keycloak - SAML SSO 設定檔。

  5. 按一下 [儲存]

重複上述步驟,將 SAML 設定檔指派給其他群組或機構單位。

測試單一登入

您已完成單一登入設定。現在可以檢查單一登入是否正常運作。

  1. 選擇符合下列條件的 Keycloak 使用者:

    • 使用者有電子郵件地址。
    • 電子郵件地址對應至 Cloud Identity 或 Google Workspace 帳戶中現有使用者的主要電子郵件地址。
    • Cloud Identity 使用者沒有超級管理員權限。

      擁有超級管理員權限的使用者帳戶一律必須使用 Google 憑證登入,因此不適合用來測試單一登入功能。

  2. 開啟新的瀏覽器視窗,然後前往 Google Cloud 控制台

  3. 在 Google 登入頁面上,輸入使用者帳戶的電子郵件地址,然後按一下「下一步」

    Google 登入頁面。

    系統會將您重新導向至 Keycloak。

  4. 輸入 Keycloak 憑證,然後按一下「登入」

    成功驗證之後,Keycloak 會將您重新導向回Google Cloud 控制台。由於這是該使用者第一次登入,系統會要求您接受 Google 服務條款與隱私權政策。

  5. 如果您同意條款,請點選 [Accept] (接受)

  6. 系統會將您重新導向至 Google Cloud 主控台,並要求您確認偏好設定,並接受 Google Cloud 服務條款。如果您同意條款,請按一下「是」,然後點選「同意並繼續」

  7. 按一下顯示圖片圖示,然後點選「登出」

    系統會將您重新導向至 Keycloak。

如果無法登入,請記住,具有超級管理員權限的使用者帳戶不必執行單一登入,因此您仍然可以使用管理控制台驗證或變更設定。

選用:設定網域專屬服務網址的重新導向

從內部入口網站或文件連結至 Google Cloud 控制台時,您可以使用網域專屬的服務網址,提升使用者體驗。

與一般服務網址 (例如 https://console.cloud.google.com/) 不同,網域專屬服務網址會包含主要網域名稱。未經驗證的使用者點選專屬服務網址的連結後,系統會立即將他們重新導向至 Keycloak,而不是先顯示 Google 登入頁面。

網域專屬服務網址的範例如下:

Google 服務 網址 標誌
Google Cloud 控制台 https://www.google.com/a/DOMAIN/ServiceLogin?continue=https://console.cloud.google.com/ Google Cloud 標誌
Google 文件 https://docs.google.com/a/DOMAIN Google 文件標誌
Google 試算表 https://www.google.com/a/DOMAIN/ServiceLogin?continue=https://sheets.google.com/ Google 試算表標誌
Google 協作平台 https://www.google.com/a/DOMAIN/ServiceLogin?continue=https://slides.google.com/ Google 協作平台標誌
Google 雲端硬碟 https://drive.google.com/a/DOMAIN Google 雲端硬碟標誌
Gmail https://mail.google.com/a/DOMAIN Gmail 標誌
Google 網路論壇 https://www.google.com/a/DOMAIN/ServiceLogin?continue=https://groups.google.com/ Google 網路論壇標誌
Google Keep https://www.google.com/a/DOMAIN/ServiceLogin?continue=https://keep.google.com/ Google Keep 標誌
Looker Studio https://www.google.com/a/DOMAIN/ServiceLogin?continue=https://lookerstudio.google.com/ Looker Studio 標誌
YouTube https://www.google.com/a/DOMAIN/ServiceLogin?continue=https://www.youtube.com/ YouTube 標誌

如要設定網域專屬服務網址,使其重新導向至 Keycloak,請按照下列步驟操作:

  1. 在管理控制台的「使用第三方 IdP 的單一登入 (SSO) 服務」頁面中,依序點選「網域專屬的服務網址」>「編輯」

    前往網域專屬的服務網址

  2. 將「自動將使用者重新導向至下列單一登入 (SSO) 設定檔的第三方 IdP」設為「已啟用」

  3. 將「單一登入設定檔」設為 Keycloak

  4. 按一下 [儲存]

選用:設定登入身分確認問題

如果使用者從不明裝置登入,或登入嘗試因其他原因而顯得可疑,Google 登入可能會要求使用者進行額外驗證。登入身分確認問題有助於提升安全性,建議您啟用這項功能。

如果登入身分確認問題造成太多阻礙,可以按照下列步驟停用:

  1. 在管理控制台中,依序點選「安全性」>「驗證」>「登入身分確認問題」
  2. 在左側窗格中,選取要停用登入身分確認問題的機構單位。如要為所有使用者停用登入挑戰,請選取根機構單位。
  3. 在「透過其他單一登入 (SSO) 設定檔登入時,使用者所看到的設定」下方,選取「不要求使用者透過 Google 進行其他驗證」
  4. 按一下 [儲存]

後續步驟