使用 Microsoft Entra ID 向 PostgreSQL 進行驗證

適用於： 適用於 PostgreSQL 的 Azure 資料庫 - 單一伺服器

本文會逐步引導您了解如何設定適用於 PostgreSQL 的 Azure 資料庫的 Microsoft Entra ID 存取的步驟，以及如何使用 Microsoft Entra 權杖來連線的步驟。

設定 Microsoft Entra 管理員使用者

只有 Microsoft Entra 管理員使用者可以針對 Microsoft Entra ID 型驗證來建立/啟用使用者。 建議您不要使用 Microsoft Entra 管理員來進行一般資料庫作業，因為其具有更高的使用者權限 (例如 CREATEDB)。

若要設定 Microsoft Entra 管理員 (您可以使用使用者或群組)，請遵循下列步驟

1. 在 Azure 入口網站中，選取您想要啟用 Microsoft Entra ID 的適用於 PostgreSQL 的 Azure 資料庫執行個體。
2. 在 [設定] 下，選取 [Active Directory 管理員]：

3. 選取客戶租用戶中要成為 Microsoft Entra 管理員的有效 Microsoft Entra 使用者。

每個 PostgreSQL 伺服器只能建立一個 Microsoft Entra 管理員，選取另一位管理員將會覆寫為伺服器設定的現有 Microsoft Entra 管理員。 您可以指定 Microsoft Entra 群組 (而非個別使用者) 以擁有多個管理員。 請注意，您接著會使用群組名稱來登入，以進行系統管理。

使用 Microsoft Entra ID 連線到適用於 PostgreSQL 的 Azure 資料庫

下列高階圖表摘要說明搭配使用 Microsoft Entra 驗證搭配適用於 PostgreSQL 的 Azure 資料庫的工作流程：

我們將 Microsoft Entra 整合設計為可搭配常見的 PostgreSQL 工具使用，例如 mysql，Microsoft Entra 無法感知此工具，而且此工具只支援在連線到 PostgreSQL 時指定使用者名稱和密碼。 我們會以密碼的形式傳遞 Microsoft Entra 權杖，如上圖所示。

我們目前已測試過下列用戶端：

• psql 命令列 (利用 PGPASSWORD 變數來傳遞權杖，請參閱步驟 3 以取得更多資訊)
• Azure Data Studio (使用 PostgreSQL 擴充功能)
• 其他 libpq 型用戶端 (例如常見的應用程式架構和 ORM)
• PgAdmin (在伺服器建立時取消核取 [立即連線]。)如需詳細資訊，請參閱步驟 4)

使用者/應用程式為了使用 Microsoft Entra ID 進行驗證所必須執行的步驟如下所述：

必要條件

您可以在 Azure Cloud Shell、Azure VM 或本機電腦上遵循這些步驟。 請確定您已安裝 Azure CLI。

以單一使用者身分使用 Microsoft Entra ID 進行驗證

步驟 1：登入使用者的 Azure 訂用帳戶

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

az login

此命令會啟動 Microsoft Entra 驗證頁面的瀏覽器視窗。 您需要提供 Microsoft Entra 使用者識別碼和密碼。

步驟 2：擷取 Microsoft Entra 存取權杖

叫用 Azure CLI 工具，以取得步驟 1 中 Microsoft Entra 已驗證使用者的存取權杖，以便存取適用於 PostgreSQL 的 Azure 資料庫。

範例 (適用於公用雲端)：

az account get-access-token --resource https://ossrdbms-aad.database.windows.net

上述資源值必須完全依所示內容加以指定。 若為其他雲端，則可以使用下列內容以查看資源值：

az cloud show

針對 Azure CLI 2.0.71 版和更新版本，您可以在下列適用於所有雲端的更方便版本中指定此命令：

az account get-access-token --resource-type oss-rdbms

驗證成功之後，Microsoft Entra ID 會傳回存取權杖：

{
  "accessToken": "TOKEN",
  "expiresOn": "...",
  "subscription": "...",
  "tenant": "...",
  "tokenType": "Bearer"
}

權杖是 Base 64 字串，會將所有關於已驗證使用者的資訊編碼，並且會以適用於 PostgreSQL 的 Azure 資料庫服務作為目標。

步驟 3：使用權杖作為以用戶端 psql 登入的密碼

在連線時，您必須使用存取權杖作為 PostgreSQL 使用者密碼。

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

Windows 範例：

set PGPASSWORD=<copy/pasted TOKEN value from step 2>

$env:PGPASSWORD='<copy/pasted TOKEN value from step 2>'

Linux/macOS 範例：

export PGPASSWORD=<copy/pasted TOKEN value from step 2>

現在您可以像往常一樣使用適用於 PostgreSQL 的 Azure 資料庫來起始連線：

psql "host=mydb.postgres... user=user@tenant.onmicrosoft.com@mydb dbname=postgres sslmode=require"

步驟 4：使用權杖作為以 PgAdmin 登入的密碼

若要搭配 pgAdmin 使用 Microsoft Entra 權杖進行連線，您必須遵循後續步驟：

1. 在伺服器建立時取消核取 [立即連線] 選項。
2. 在 [連線] 索引標籤中輸入您的伺服器詳細資料，然後儲存。
3. 從瀏覽器功能表中，選取 [連線至適用於 PostgreSQL 的 Azure 資料庫伺服器]
4. 在系統提示時輸入 AD 權杖密碼。

連線時的重要考量：

• user@tenant.onmicrosoft.com 是 Microsoft Entra 使用者的名稱
• 請務必使用 Azure 使用者的確切拼字，因為 Microsoft Entra 使用者和群組名稱會區分大小寫。
• 如果名稱包含空格，請在每個空格之前使用 \ 將其逸出。
• 存取權杖的有效時間介於 5 分鐘到 60 分鐘之間。 建議您在要起始對於「適用於 PostgreSQL 的 Azure 資料庫」的登入前一刻，才去取得存取權杖。

您現在已使用 Microsoft Entra 驗證向適用於 PostgreSQL 的 Azure 資料庫伺服器進行驗證。

以群組成員身分使用 Microsoft Entra ID 進行驗證

步驟 1：在適用於 PostgreSQL 的 Azure 資料庫中建立 Microsoft Entra 群組

若要啟用 Microsoft Entra 群組以便能夠存取您的資料庫，請使用與使用者相同的機制，但改為指定群組名稱：

範例：

CREATE USER <new_user> IN ROLE azure_ad_user;

登入時，群組的成員會使用其個人存取權杖，但會以指定為使用者名稱的群組名稱來登入。

步驟 2：登入使用者的 Azure 訂用帳戶

使用 Azure CLI 工具使用 Microsoft Entra ID 進行驗證。 您不需要在 Azure Cloud Shell 中進行此步驟。 使用者必須是 Microsoft Entra 群組的成員。

az login

步驟 3：擷取 Microsoft Entra 存取權杖

叫用 Azure CLI 工具，以取得步驟 2 中 Microsoft Entra 已驗證使用者的存取權杖，以便存取適用於 PostgreSQL 的 Azure 資料庫。

範例 (適用於公用雲端)：

az account get-access-token --resource https://ossrdbms-aad.database.windows.net

上述資源值必須完全依所示內容加以指定。 若為其他雲端，則可以使用下列內容以查看資源值：

az cloud show

針對 Azure CLI 2.0.71 版和更新版本，您可以在下列適用於所有雲端的更方便版本中指定此命令：

az account get-access-token --resource-type oss-rdbms

驗證成功之後，Microsoft Entra ID 會傳回存取權杖：

{
  "accessToken": "TOKEN",
  "expiresOn": "...",
  "subscription": "...",
  "tenant": "...",
  "tokenType": "Bearer"
}

步驟 4：使用權杖作為以 psql 或 PgAdmin 登入的密碼 (請參閱上述的使用者連線步驟)

以群組成員身分連線時的重要考量：

• groupname@mydb 是您嘗試以 Microsoft Entra 群組身分進行連線的名稱
• 一律在 Microsoft Entra 使用者/群組名稱之後附加伺服器名稱 (例如 @mydb)
• 請務必使用完整的 Microsoft Entra 群組名稱。
• Microsoft Entra 使用者和群組名稱會區分大小寫
• 以群組身分連線時，請只使用群組名稱 (例如 GroupName@mydb)，而不是群組成員的別名。
• 如果名稱包含空格，請在每個空格之前使用 \ 來將其逸出。
• 存取權杖的有效時間介於 5 分鐘到 60 分鐘之間。 建議您在要起始對於「適用於 PostgreSQL 的 Azure 資料庫」的登入前一刻，才去取得存取權杖。

您現在已使用 Microsoft Entra 驗證向 PostgreSQL 伺服器進行驗證。

在適用於 PostgreSQL 的 Azure 資料庫中建立 Microsoft Entra 使用者

若要將 Microsoft Entra 使用者新增至適用於 PostgreSQL 的 Azure 資料庫資料庫，請在連線之後執行下列步驟 (請參閱後面關於如何連線的章節)：

1. 首先，確保 Microsoft Entra 使用者 <user>@yourtenant.onmicrosoft.com 是 Microsoft Entra 租用戶中的有效使用者。
2. 以 Microsoft Entra 管理員使用者身分登入適用於 PostgreSQL 的 Azure 資料庫執行個體。
3. 在適用於 PostgreSQL 的 Azure 資料庫中建立角色 <user>@yourtenant.onmicrosoft.com。
4. 使 <user>@yourtenant.onmicrosoft.com 成為角色 azure_ad_user 的成員。 這必須只提供給 Microsoft Entra 使用者。

範例：

CREATE USER "user1@yourtenant.onmicrosoft.com" IN ROLE azure_ad_user;

權杖驗證

適用於 PostgreSQL 的 Azure 資料庫中的 Microsoft Entra 驗證可確保使用者存在於 PostgreSQL 伺服器中，並藉由驗證權杖的內容來檢查權杖是否有效。 會執行以下權杖驗證步驟：

• 權杖是由 Microsoft Entra ID 簽署的，而且尚未遭到篡改
• 權杖是由 Microsoft Entra ID 針對與伺服器相關聯的租用戶核發
• 權杖尚未過期
• 權杖適用於「適用於 PostgreSQL 的 Azure 資料庫」資源 (而不是另一個 Azure 資源)

將現有的 PostgreSQL 使用者移轉至 Microsoft Entra ID 型驗證

您可以為現有使用者啟用 Microsoft Entra 驗證。 有兩種情況需要考慮:

案例 1：PostgreSQL 使用者名稱符合 Microsoft Entra 使用者主體名稱

如果是現有使用者已符合 Microsoft Entra 使用者名稱的罕見情況，您可以向其授與 azure_ad_user 角色，以便為其啟用 Microsoft Entra 驗證：

GRANT azure_ad_user TO "existinguser@yourtenant.onmicrosoft.com";

這些使用者現在能夠使用 Microsoft Entra 認證 (而不是使用先前設定的 PostgreSQL 使用者密碼) 來登入。

案例 2：PostgreSQL 使用者名稱與 Microsoft Entra 使用者主體名稱不同

如果 PostgreSQL 使用者不存在於 Microsoft Entra ID 中或有不同的使用者名稱，您可以使用 Microsoft Entra 群組來以此 PostgreSQL 使用者身分驗證。 您可以使用符合 PostgreSQL 使用者的名稱來建立 Microsoft Entra 群組，然後將角色 azure_ad_user 授與給現有 PostgreSQL 使用者，以將現有的適用於 PostgreSQL 的 Azure 資料庫使用者移轉至 Microsoft Entra ID：

GRANT azure_ad_user TO <new_user>;

這會假設您已在 Microsoft Entra ID 中建立 "DBReadUser" 群組。 屬於該群組的使用者現在將能夠以這位使用者的身分登入資料庫。

下一步

• 檢閱使用適用於 PostgreSQL 的 Azure 資料庫進行 Microsoft Entra 驗證 - 單一伺服器的整體概念