跳至主要内容

設定 Azure AD

Microsoft Graph API​

Microsoft Graph API 現在是您設定 Azure AD 的流程。以下部分將協助新使用者使用新實例設定 Azure AD,並協助現有 Azure 應用程式擁有者遷移到新流程。

Rancher 中的 Microsoft Graph API 流程不斷演進。我們建議您使用 2.7 的最新修補版本,因為它仍在積極開發中,並將持續接收新功能和改進。

新使用者設定​

如果您在 Azure 中託管 Active Directory (AD) 實例,您可以設定 Rancher 以允許您的使用者使用他們的 AD 帳戶登入。Azure AD 外部身份驗證的設定需要您在 Azure 和 Rancher 中進行設定。

注意
  • Azure AD 整合僅支援服務提供者發起的登入。
  • 此程序的大部分步驟在 Microsoft Azure Portal 中進行。

Azure Active Directory 設定概述​

設定 Rancher 以允許您的使用者使用 Azure AD 帳戶進行身份驗證涉及多個程序。在開始之前,請查看以下概述。

提示

在開始之前,請開啟兩個瀏覽器分頁:一個用於 Rancher,一個用於 Azure 入口網站。這將有助於從入口網站複製和貼上設定值到 Rancher。

1. 向 Azure 註冊 Rancher​

在 Rancher 中啟用 Azure AD 之前,您必須向 Azure 註冊 Rancher。

  1. 以管理使用者身分登入 Microsoft Azure。未來步驟的設定需要管理存取權限。

  2. 使用搜尋開啟 App registrations 服務。

  3. 點擊 New registration 並完成表單。

    New App Registration

    1. 輸入 Name(例如 Rancher)。

    2. 從 Supported account types 中,選擇 "Accounts in this organizational directory only (AzureADTest only - Single tenant)"。這對應於舊版應用程式註冊選項。

      備註

      在更新的 Azure 入口網站中,Redirect URIs 與 Reply URLs 同義。為了將 Azure AD 與 Rancher 配合使用,您必須將 Rancher 加入 Azure 的白名單(以前透過 Reply URLs 完成)。因此,您必須確保使用您的 Rancher 伺服器 URL 填寫 Redirect URI,包括如下所列的驗證路徑。

    3. 在 Redirect URI 部分,確保從下拉式選單中選擇了 Web,並在下拉式選單旁邊的文字方塊中輸入您的 Rancher Server 的 URL。此 Rancher 伺服器 URL 應該附加驗證路徑:<MY_RANCHER_URL>/verify-auth-azure。

      提示

      您可以在 Rancher 的 Azure AD Authentication 頁面上找到您的個人化 Azure Redirect URI(reply URL)(Global View > Authentication > Web)。

    4. 點擊 Register。

備註

此更改最多可能需要五分鐘才能生效,因此如果您在 Azure AD 設定後無法立即進行身份驗證,請不要驚慌。

2. 建立新的客戶端密鑰​

從 Azure 入口網站建立客戶端密鑰。Rancher 將使用此密鑰與 Azure AD 進行身份驗證。

  1. 使用搜尋開啟 App registrations 服務。然後開啟您在上一個程序中為 Rancher 建立的條目。

    Open Rancher Registration

  2. 從導覽窗格中,點擊 Certificates & secrets。

  3. 點擊 New client secret。 Create new client secret

  4. 輸入 Description(例如 Rancher)。

  5. 從 Expires 下的選項中選擇持續時間。此下拉式選單設定密鑰的到期日期。較短的持續時間更安全,但需要您更頻繁地建立新密鑰。 請注意,如果 Rancher 偵測到應用程式密鑰已到期,使用者將無法登入 Rancher。為避免此問題,請在密鑰到期之前在 Azure 中輪換密鑰並在 Rancher 中更新它。

  6. 點擊 Add(您不需要輸入值—儲存後它會自動填充)。

  1. 您稍後將在 Rancher UI 中輸入此密鑰作為您的 Application Secret。由於您將無法在 Azure UI 中再次存取密鑰值,因此請在設定過程的其餘部分保持此視窗開啟。

3. 為 Rancher 設定所需權限​

接下來,在 Azure 中為 Rancher 設定 API 權限。

警告

確保您設定的是應用程式權限,而不是委派權限。否則,您將無法登入 Azure AD。

  1. 從導覽窗格中,選擇 API permissions。

  2. 點擊 Add a permission。

  3. 從 Microsoft Graph API 中,選擇以下應用程式權限:Directory.Read.All

    Select API Permissions

  4. 返回導覽列中的 API permissions。從那裡,點擊 Grant admin consent。然後點擊 Yes。應用程式的權限應該如下所示:

Open Required Permissions

備註

Rancher 不會驗證您授予 Azure 中應用程式的權限。只要權限允許 Rancher 與 AD 使用者和群組配合使用,您可以自由嘗試任何權限。

具體來說,Rancher 需要允許以下操作的權限:

  • 取得使用者。
  • 列出所有使用者。
  • 列出給定使用者所屬的群組。
  • 取得群組。
  • 列出所有群組。

Rancher 執行這些操作是為了登入使用者或執行使用者/群組搜尋。請記住,權限必須是 Application 類型。

以下是滿足 Rancher 需求的權限組合的一些範例:

  • Directory.Read.All
  • User.Read.All 和 GroupMember.Read.All
  • User.Read.All 和 Group.Read.All

4. 允許公開客戶端流程​

要從 Rancher CLI 登入,您必須允許公開客戶端流程:

  1. 從左側導覽選單中,選擇 Authentication。

  2. 在 Advanced Settings 下,在 Allow public client flows 旁邊的切換按鈕上選擇 Yes。

    Allow Public Client Flows

5. 複製 Azure 應用程式資料​

Application ID

  1. 取得您的 Rancher Tenant ID。

    1. 使用搜尋開啟 App registrations。

    2. 找到您為 Rancher 建立的條目。

    3. 複製 Directory ID 並將其貼到 Rancher 中作為您的 Tenant ID。

  2. 取得您的 Rancher Application (Client) ID。

    1. 如果您還不在那裡,請使用搜尋開啟 App registrations。

    2. 在 Overview 中,找到您為 Rancher 建立的條目。

    3. 複製 Application (Client) ID 並將其貼到 Rancher 中作為您的 Application ID。

  3. 在大多數情況下,您的端點選項將是 Standard 或 China。對於這兩個選項中的任何一個,您只需要輸入 Tenant ID、Application ID 和 Application Secret。

Standard Endpoint Options

對於自訂端點:

警告

自訂端點未經 Rancher 測試或完全支援。

您還需要手動輸入 Graph、Token 和 Auth 端點。

  • 從 App registrations 中,點擊 Endpoints:

Click Endpoints

  • 以下端點將是您的 Rancher 端點值。確保使用這些端點的 v1 版本:
    • Microsoft Graph API endpoint (Graph Endpoint)
    • OAuth 2.0 token endpoint (v1) (Token Endpoint)
    • OAuth 2.0 authorization endpoint (v1) (Auth Endpoint)

6. 在 Rancher 中設定 Azure AD​

要完成設定,請在 Rancher UI 中輸入有關您 AD 實例的資訊。

  1. 登入 Rancher。

  2. 在左上角,點擊 ☰ > Users & Authentication。

  3. 在左側導覽選單中,點擊 Auth Provider。

  4. 點擊 AzureAD。

  5. 使用您在完成複製 Azure 應用程式資料時複製的資訊完成 Configure Azure AD Account 表單。

    警告

    Azure AD 帳戶將被授予管理員權限,因為其詳細資訊將對應到 Rancher 本地主體帳戶。在繼續之前,請確保此權限級別是適當的。

    對於 Standard 或 China 端點:

    下表將您在 Azure 入口網站中複製的值對應到 Rancher 中的欄位:

    Rancher 欄位Azure 值
    Tenant IDDirectory ID
    Application IDApplication ID
    Application SecretKey Value
    Endpointhttps://login.microsoftonline.com/

    對於自訂端點:

    下表將您的自訂設定值對應到 Rancher 欄位:

    Rancher 欄位Azure 值
    Graph EndpointMicrosoft Graph API Endpoint
    Token EndpointOAuth 2.0 Token Endpoint
    Auth EndpointOAuth 2.0 Authorization Endpoint

    重要: 在自訂設定中輸入 Graph Endpoint 時,從 URL 中刪除租戶 ID:

    https://graph.microsoft.com/abb5adde-bee8-4821-8b03-e63efdc7701c

  6. (選擇性)在 Rancher v2.9.0 及更高版本中,您可以在 Azure AD 中篩選使用者的群組成員資格,以減少生成的日誌資料量。請參閱按照 Azure AD 授權群組成員資格篩選使用者的步驟 4–5 以取得完整說明。

  7. 點擊 Enable。

結果: Azure Active Directory 身份驗證已設定。

(選擇性)使用多個 Rancher 網域設定身份驗證​

如果您有多個 Rancher 網域,則無法透過 Rancher UI 設定多個重新導向 URI。Azure AD 設定檔案 azuread 預設只允許一個重新導向 URI。您必須手動編輯 azuread 以根據需要為任何其他網域設定重新導向 URI。如果您不手動編輯 azuread,那麼在成功登入任何網域後,Rancher 會自動將使用者重新導向到您在步驟 1. 向 Azure 註冊 Rancher 中註冊應用程式時設定的 Redirect URI 值。

從 Azure AD Graph API 遷移到 Microsoft Graph API​

由於 Azure AD Graph API 已棄用並計劃於 2023 年 6 月停用,管理員應該在 Rancher 中將他們的 Azure AD App 更新為使用 Microsoft Graph API。 這需要在端點停用之前提前完成。 如果在 Azure AD Graph API 停用時 Rancher 仍設定為使用它,使用者可能無法使用 Azure AD 登入 Rancher。

在 Rancher UI 中更新端點​

警告

管理員應該在承諾進行下面描述的端點遷移之前建立 Rancher 備份。

  1. 更新您的 Azure AD 應用程式註冊的權限。這一點至關重要。

  2. 登入 Rancher。

  3. 在 Rancher UI 首頁中,注意螢幕頂部的橫幅,該橫幅建議使用者更新他們的 Azure AD 身份驗證。點擊提供的連結進行更新。

    Rancher UI Banner

  4. 要完成遷移到新的 Microsoft Graph API,請點擊 Update Endpoint。

    注意: 確保您的 Azure 應用程式在開始更新之前具有新的權限集。

    Update Endpoint

  5. 當您收到彈出警告訊息時,請點擊 Update。

    Azure Update Pop-up

  6. 請參閱下面的表格以取得 Rancher 執行的端點更改的完整清單。管理員不需要手動執行此操作。

離線環境​

在離線環境中,管理員應該確保他們的端點在白名單中(請參閱向 Azure 註冊 Rancher 的步驟 3.2 上的注意事項),因為 Graph Endpoint URL 正在更改。

回滾遷移​

如果您需要回滾遷移,請注意以下事項:

  1. 如果管理員想要返回,建議使用適當的還原流程。請參閱備份文件、還原文件和範例以供參考。

  2. 想要輪換 Application Secret 的 Azure 應用程式擁有者還需要在 Rancher 中輪換它,因為 Rancher 不會在 Azure 中更改時自動更新 Application Secret。在 Rancher 中,請注意它儲存在名為 azureadconfig-applicationsecret 的 Kubernetes secret 中,該 secret 位於 cattle-global-data 命名空間中。

警告

如果您升級到 Rancher v2.7.0+ 並使用現有的 Azure AD 設定,並選擇停用授權提供者,您將無法還原先前的設定。您也將無法使用舊流程設定 Azure AD。您需要使用新的授權流程重新註冊。由於 Rancher 現在使用 Graph API,使用者需要在 Azure 入口網站中設定適當的權限。

Global:​

Rancher 欄位已棄用的端點
Auth Endpointhttps://login.microsoftonline.com/{tenantID}/oauth2/authorize
Endpointhttps://login.microsoftonline.com/
Graph Endpointhttps://graph.windows.net/
Token Endpointhttps://login.microsoftonline.com/{tenantID}/oauth2/token
Rancher 欄位新端點
Auth Endpointhttps://login.microsoftonline.com/{tenantID}/oauth2/v2.0/authorize
Endpointhttps://login.microsoftonline.com/
Graph Endpointhttps://graph.microsoft.com
Token Endpointhttps://login.microsoftonline.com/{tenantID}/oauth2/v2.0/token

China:​

Rancher 欄位已棄用的端點
Auth Endpointhttps://login.chinacloudapi.cn/{tenantID}/oauth2/authorize
Endpointhttps://login.chinacloudapi.cn/
Graph Endpointhttps://graph.chinacloudapi.cn/
Token Endpointhttps://login.chinacloudapi.cn/{tenantID}/oauth2/token
Rancher 欄位新端點
Auth Endpointhttps://login.partner.microsoftonline.cn/{tenantID}/oauth2/v2.0/authorize
Endpointhttps://login.partner.microsoftonline.cn/
Graph Endpointhttps://microsoftgraph.chinacloudapi.cn
Token Endpointhttps://login.partner.microsoftonline.cn/{tenantID}/oauth2/v2.0/token

按照 Azure AD 授權群組成員資格篩選使用者​

在 Rancher v2.9.0 及更高版本中,您可以從 Azure AD 篩選使用者的群組成員資格,以減少生成的日誌資料量。如果您在初始設定期間未篩選群組成員資格,您仍然可以在現有的 Azure AD 設定上新增篩選器。

注意

篩選出使用者群組成員資格不僅影響日誌記錄。

由於篩選器阻止 Rancher 看到使用者屬於被排除的群組,它也看不到該群組的任何權限。這意味著從篩選器中排除群組可能會產生拒絕使用者應有權限的副作用。

  1. 在 Rancher 中,在左上角點擊 ☰ > Users & Authentication。

  2. 在左側導覽選單中,點擊 Auth Provider。

  3. 點擊 AzureAD。

  4. 點擊 Limit users by group membership 旁邊的核取方塊。

  5. 在 Group Membership Filter 欄位中輸入 OData 篩選子句。例如,如果您想要將日誌記錄限制為名稱以 test 開頭的群組成員資格,請點擊核取方塊並輸入 startswith(displayName,'test')。

Adding a group membership filter to Azure AD

已棄用的 Azure AD Graph API​

重要:

  • Azure AD Graph API 已棄用,Microsoft 將在 2023 年 6 月 30 日之後的任何時間停用它,恕不另行通知。我們將在停用時更新文件以通知社群。Rancher 現在使用 Microsoft Graph API 作為設定 Azure AD 作為外部授權提供者的新流程。

  • 如果您是新使用者或希望遷移,請參閱 Rancher v2.7.0+ 的新流程說明。

  • 如果您不希望在 Azure AD Graph API 停用後升級到 v2.7.0+,您需要:

  • 使用內建的 Rancher 授權或
  • 使用另一個第三方授權系統並在 Rancher 中進行設定。請參閱身份驗證文件以了解如何設定其他開放身份驗證提供者。

Azure AD 角色聲明​

Rancher 支援 Azure AD OIDC 提供者權杖提供的角色聲明,允許將基於角色的存取控制 (RBAC) 完全委派給 Azure AD。以前,Rancher 僅處理 Groups 聲明以確定使用者的 group 成員資格。此增強功能將邏輯擴展為也包括使用者 OIDC 權杖中的角色聲明。

透過包含角色聲明,管理員可以:

  • 在 Azure AD 中定義特定的高級角色。
  • 將這些 Azure AD 角色直接綁定到 Rancher 中的 ProjectRoles 或 ClusterRoles。
  • 將存取控制決策集中並完全委派給外部 OIDC 提供者。

例如,考慮 Azure AD 中的以下角色結構:

Azure AD 角色名稱成員
project-alpha-devUser A, User C

使用者 A 透過 Azure AD 登入 Rancher。OIDC 權杖包含角色聲明 [project-alpha-dev]。Rancher 邏輯處理權杖,使用者 A 的內部 groups/角色清單包括 project-alpha-dev。管理員已建立專案角色綁定,將 Azure AD 角色 project-alpha-dev 對應到專案 Alpha 的專案角色 Dev Member。使用者 A 自動被授予專案 Alpha 中的 Dev Member 角色。