使用 Microsoft Entra ID 和原生 PostgreSQL 角色對 Azure Cosmos DB for PostgreSQL 進行驗證

  • 發行項

適用於： Azure Cosmos DB for PostgreSQL (由 PostgreSQL 的 Citus 資料庫延伸模組提供)

在本文中，您會為 Azure Cosmos DB for PostgreSQL 設定驗證方法。 您可以管理 Microsoft Entra ID 管理使用者和原生 PostgreSQL 角色，以對 Azure Cosmos DB for PostgreSQL 進行驗證。 您也將了解如何搭配 Azure Cosmos DB for PostgreSQL 使用 Microsoft Entra ID 權杖。

使用一個名為「citus」的內建原生 PostgreSQL 角色來建立 Azure Cosmos DB for PostgreSQL 叢集。 完成叢集布建之後，您可以新增更多原生 PostgreSQL 角色。

您也可以為 Azure Cosmos DB for PostgreSQL 設定 Microsoft Entra ID (先前稱為 Azure Active Directory) 驗證。 您可以啟用 Microsoft Entra ID 驗證，以此取代叢集上的原生 PostgreSQL 驗證或做為其補充。 您可以在佈建叢集之後的任何時間點，變更叢集上啟用的驗證方法。 啟用 Microsoft Entra ID 驗證時，您可以將多個 Microsoft Entra ID 使用者新增至 Azure Cosmos DB for PostgreSQL 叢集，並將其中任一者設定為管理員。 Microsoft Entra ID 使用者可以是使用者或服務主體。

選擇驗證方法

您必須使用 Azure 入口網站在 Azure Cosmos DB for PostgreSQL 叢集上設定驗證方法。

在 Azure Cosmos DB for PostgreSQL 叢集上完成下列項目，以啟用或停用 Microsoft Entra ID 驗證和原生 PostgreSQL 驗證。

  1. 在叢集頁面上的 [叢集管理] 標題下，選擇 [驗證] 以開啟驗證管理選項。
  2. 在 [驗證方法] 區段中，選擇 [僅 PostgreSQL 驗證]、[Microsoft Entra ID 驗證]，或 [PostgreSQL 和 Microsoft Entra ID 驗證] 做為驗證方法。

完成之後，繼續設定 Microsoft Entra ID 驗證或在同一個驗證頁面上新增原生 PostgreSQL 角色。

設定 Microsoft Entra ID 驗證

必要條件

必須在 Microsoft Entra ID 租用戶中，允許使用者登入 Azure Cosmos DB for PostgreSQL。 針對即將用於 Azure Cosmos DB for PostgreSQL 叢集上驗證的 Microsoft Entra ID 租用戶，必須將這些步驟執行一次。

重要

需要 Microsoft Entra ID 租用戶系統管理員權限才能進行變更。 請參閱權限疑難排解指導。

  1. 在 Azure 入口網站中搜尋「Microsoft Entra ID」。
  2. 開啟 [Microsoft Entra ID] 服務。
  3. 在 Microsoft Entra ID 服務 [概觀] 頁面上的 [概觀] 區段中，搜尋「b4fa09d8-5da5-4352-83d9-05c2a44cf431」應用程式標識符。
  4. 在搜尋結果中選擇 [Azure Cosmos DB for PostgreSQL AAD 驗證] 企業應用程式。
  5. 在 [Azure Cosmos DB for PostgreSQL AAD 驗證] 企業應用程式中，選擇 [屬性] 頁面。
  6. 將 [為使用者啟用登入？] 設定為 [是]，然後儲存變更。

注意

編輯企業應用程式的屬性，例如「為使用者啟用登入」，需要授與具有更新企業應用程式屬性許可權的角色許可權。 企業應用程式擁有者等角色必須具有「更新企業應用程式屬性」許可權。 如需詳細資訊，請參閱 依工作 - 企業應用程式Microsoft輸入最低許可權角色。

將 Microsoft Entra ID 管理員新增至 Azure Cosmos DB for PostgreSQL 叢集

若要在叢集上新增或移除 Microsoft Entra ID 角色，請在 [驗證] 頁面上執行下列步驟：

  1. 在 [Microsoft Entra ID 驗證] 區段中，選取 [新增 Microsoft Entra ID 管理員]。
  2. 在 [選取 Microsoft Entra ID 管理員] 面板中，選取目前 AD 租用戶中一或多個有效的 Microsoft Entra ID 使用者或企業應用程式，做為 Azure Cosmos DB for PostgreSQL 叢集上的 Microsoft Entra ID 管理員。
  3. 使用 [選取] 來確認您的選擇。
  4. 在 [驗證] 頁面中，選取工具列中的 [儲存] 以儲存變更，或繼續新增原生 PostgreSQL 角色。

設定原生 PostgreSQL 驗證

若要在叢集上新增 Postgres 角色，請在 [驗證] 頁面上執行下列步驟：

  1. 在 [PostgreSQL 驗證] 區段中，選取 [新增 PostgreSQL 角色]。
  2. 輸入角色名稱和密碼。 選取 [儲存]。
  3. 在 [驗證] 頁面中，選取工具列中的 [儲存] 以儲存變更，或繼續新增 Microsoft Entra ID 管理使用者。

在叢集的協調器節點上建立原生 PostgreSQL 使用者，並傳播至所有背景工作節點。 透過 Azure 入口網站建立的角色具有 LOGIN 屬性，表示這些角色是可以登入資料庫的真正使用者。

使用 Microsoft Entra ID 驗證連線至 Azure Cosmos for PostgreSQL

Microsoft Entra ID 整合可與標準 PostgreSQL 用戶端工具搭配運作 (例如 psql)，但 Microsoft Entra ID 無法感知 psql，且在連線到 PostgreSQL 時僅支援指定使用者名稱和密碼。 在此情況下，Microsoft Entra ID 權杖會以密碼的形式傳遞。

我們已測試下列用戶端：

  • psql 命令列：使用 PGPASSWORD 變數來傳遞權杖。
  • 其他基於 libpq 的用戶端：範例包括常見的應用程式架構和對象關係型對應程式 (ORM)。
  • pgAdmin：在建立伺服器時，取消核取 [立即連線] 選項。

使用下列程序，以 Azure Cosmos DB for PostgreSQL 使用者身分向 Microsoft Entra ID 進行驗證。 您可以在 Azure Cloud Shell、Azure 虛擬機器或本機電腦上遵循這些步驟。

登入使用者的 Azure 訂用帳戶

首先，使用 Azure CLI 以 Microsoft Entra ID 進行驗證。 您不需要在 Azure Cloud Shell 中執行此步驟。

az login

此命令將開啟 Microsoft Entra ID 驗證頁面的瀏覽器視窗。 此命令要求您提供 Microsoft Entra ID 使用者名稱和密碼。

您用來驗證的使用者帳戶名稱 (例如 user@tenant.onmicrosoft.com) 是下一個步驟中將為其產生存取權杖的帳戶名稱。

擷取 Microsoft Entra ID 存取權杖

使用 Azure CLI 取得 Microsoft Entra ID 驗證使用者的存取權杖，以存取 Azure Cosmos for PostgreSQL。 以下是範例：

az account get-access-token --resource https://token.postgres.cosmos.azure.com

驗證成功之後，Microsoft Entra ID 會傳回目前 Azure 訂用帳戶的存取權杖：

{
  "accessToken": "[TOKEN]",
  "expiresOn": "[expiration_date_and_time]",
  "subscription": "[subscription_id]",
  "tenant": "[tenant_id]",
  "tokenType": "Bearer"
}

TOKEN 是 Base64 字串。 它會編碼已驗證使用者的所有資訊，並與 Azure Cosmos DB for PostgreSQL 服務相關聯。 此權杖的有效時間至少 5 分鐘，最多 90 分鐘。 expiresOn 定義實際的權杖到期時間。

使用權杖做為以 psql 用戶端登入的密碼

連線時，最好使用存取權杖做為 PostgreSQL 使用者密碼。

使用 psql 命令列用戶端時，必須透過 PGPASSWORD 環境變數傳遞存取權杖。 這是因為存取權杖超過 psql 可以直接接受的密碼長度。

以下是 Windows 範例：

set PGPASSWORD=<TOKEN value from the previous step>

$env:PGPASSWORD='<TOKEN value from the previous step>'

以下是 Linux/macOS 範例：

export PGPASSWORD=<TOKEN value from the previous step>

您也可以使用命令替代將上述兩個步驟結合在一起。 可以將權杖擷取封裝到變數中，並做為 PGPASSWORD 環境變數的值直接傳遞：

export PGPASSWORD=$(az account get-access-token --resource https://token.postgres.cosmos.azure.com --query "[accessToken]" -o tsv)

注意

為進行 Microsoft Entra ID 驗證，請確定 PGPASSWORD 變數已設定為您的訂用帳戶的 Microsoft Entra ID 存取權杖。 如果需要從相同工作階段執行 Postgres 角色驗證，您可以將 PGPASSWORD 設定為 Postgres 角色密碼，或清除 PGPASSWORD 變數值，以互動方式輸入密碼。 當 PGPASSWORD 中的值錯誤，驗證將會失敗。

現在，您可以使用產生存取權杖的 Microsoft Entra ID 使用者帳戶，起始與 Azure Cosmos DB for PostgreSQL 的連線。 您可以像往常一樣將使用者帳戶做為使用者，但不需要在命令列中包含 [password] 參數：

psql "host=mycluster.[uniqueID].postgres.cosmos.azure.com user=user@tenant.onmicrosoft.com dbname=[db_name] sslmode=require"

使用權杖做為以 PgAdmin 登入的密碼

若要搭配 PgAdmin 使用 Microsoft Entra ID 權杖進行連線，請遵循下列步驟：

  1. 在伺服器建立時，取消核取 [立即連線] 選項。
  2. 在 [連線] 索引標籤中輸入您的伺服器詳細資料，然後儲存。
    1. 請確定已在 [使用者名稱中] 指定有效的 Microsoft Entra ID 使用者。
  3. 從 pgAdmin 的 [物件] 功能表中，選取 [連接伺服器]。
  4. 出現提示時，請輸入 Microsoft Entra ID 權杖密碼。

以下是連線時的一些基本考量：

  • user@tenant.onmicrosoft.com 是 Microsoft Entra ID 使用者的名稱。
  • 請務必使用 Azure 使用者的確切名稱。 Microsoft Entra ID 使用者和群組名稱會區分大小寫。
  • 如果名稱包含空格，請在每個空格之前使用反斜線 (\) 將其逸出。
  • 存取權杖的有效性是 5 分鐘到 90 分鐘。 建議您在要起始登入 Azure Cosmos for PostgreSQL 之前取得存取權杖。

您現在已透過 Microsoft Entra ID 驗證向 Azure Cosmos for PostgreSQL 伺服器進行驗證。

管理原生 PostgreSQL 角色

在叢集上啟用原生 PostgreSQL 驗證時，除了內建的「citus」角色之外，您還可以新增和刪除 Postgres 角色。 您也可以重設原生角色的密碼，以及修改其 Postgres 權限。

如何刪除原生 PostgreSQL 使用者角色或變更其密碼

若要更新使用者，請造訪您叢集的 [驗證] 頁面，選取使用者旁的省略符號 [...]。 此省略符號會開啟功能表來刪除使用者或重設其密碼。

citus 角色具有特殊權限，無法刪除。 不過，如果為叢集選取了 [僅限 Microsoft Entra ID 驗證] 驗證方法，則 citus 角色會被停用。

如何修改使用者角色的權限

新的使用者角色通常用來支援以有限權限存取資料庫。 若要修改使用者權限，請在 PgAdmin 或 psql 之類的工具中使用標準 PostgreSQL 命令。 如需詳細資訊，請參閱連線到叢集。

例如，若要允許 PostgreSQL db_user 讀取 mytable，請授與權限：

GRANT SELECT ON mytable TO db_user;

若要將相同的權限授與 Microsoft Entra ID 角色 user@tenant.onmicrosoft.com，請使用下列命令：

GRANT SELECT ON mytable TO "user@tenant.onmicrosoft.com";

Azure Cosmos DB for PostgreSQL 將單一資料表 GRANT 陳述式傳播至整個叢集，將其套用在所有背景工作節點上。 也傳播全系統的 GRANT (例如結構描述中的所有資料表)：

-- applies to the coordinator node and propagates to worker nodes for Postgres role db_user
GRANT SELECT ON ALL TABLES IN SCHEMA public TO db_user;

或者對於 Microsoft Entra ID 使用者

-- applies to the coordinator node and propagates to worker nodes for Azure AD role user@tenant.onmicrosoft.com
GRANT SELECT ON ALL TABLES IN SCHEMA public TO "user@tenant.onmicrosoft.com";

下一步