Share via

使用 Microsoft Entra ID 向 PostgreSQL 進行驗證

  • 發行項

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

重要

適用於 PostgreSQL 的 Azure 資料庫 - 單一伺服器位於淘汰路徑上。 強烈建議您升級至 適用於 PostgreSQL 的 Azure 資料庫 - 彈性伺服器。 如需移轉至 適用於 PostgreSQL 的 Azure 資料庫 - 彈性伺服器的詳細資訊，請參閱單一伺服器 適用於 PostgreSQL 的 Azure 資料庫 發生什麼事？。

本文將逐步引導您完成如何使用 適用於 PostgreSQL 的 Azure 資料庫 設定 Microsoft Entra 標識符存取，以及如何使用 Microsoft Entra 令牌進行連線的步驟。

設定 Microsoft Entra 管理使用者

只有 Microsoft Entra 系統管理員使用者可以建立/啟用 Microsoft Entra 識別符型驗證的使用者。 我們建議不要使用 Microsoft Entra 系統管理員進行一般資料庫作業，因為它具有較高的用戶權力（例如 CREATEDB）。

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

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

設定 Microsoft Entra 系統管理員

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

重要

設定系統管理員時，會將新的使用者新增至具有完整系統管理員許可權的 適用於 PostgreSQL 的 Azure 資料庫 伺服器。 適用於 PostgreSQL 的 Azure 資料庫 中的 Microsoft Entra 管理員 使用者將具有 角色azure_ad_admin。 每個 PostgreSQL 伺服器只能建立一個 Microsoft Entra 系統管理員，而另一個伺服器的選取專案將會覆寫為伺服器設定的現有 Microsoft Entra 管理員。 您可以指定 Microsoft Entra 群組，而不是個別用戶來擁有多個系統管理員。

每個 PostgreSQL 伺服器只能建立一個 Microsoft Entra 系統管理員，而另一個伺服器的選取專案將會覆寫為伺服器設定的現有 Microsoft Entra 管理員。 您可以指定 Microsoft Entra 群組，而不是個別用戶來擁有多個系統管理員。 請注意，您接著會使用組名登入，以供系統管理之用。

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

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

驗證流程

我們已設計 Microsoft Entra 整合，以使用常見的 PostgreSQL 工具，例如 psql，這不是 Microsoft Entra 感知，而且只支持在連線到 PostgreSQL 時指定使用者名稱和密碼。 我們會以密碼的形式傳遞 Microsoft Entra 權杖，如上圖所示。

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

  • psql 命令行 （利用 PGPASSWORD 變數傳遞令牌，請參閱步驟 3 以取得詳細資訊）
  • Azure Data Studio （使用 PostgreSQL 擴充功能）
  • 其他 libpq 型用戶端（例如常見的應用程式架構和 ORM）
  • Pg 管理員 （現在在建立伺服器時取消核取連線。如需詳細資訊，請參閱步驟 4）

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

必要條件

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

以單一使用者身分向 Microsoft Entra 識別碼進行驗證

步驟 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：使用令牌作為使用 Pg 登入的密碼 管理員

若要搭配 pg 使用 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 識別碼作為群組成員進行驗證

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

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

範例：

CREATE USER <new_user> IN ROLE azure_ad_user;

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

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

使用 Azure CLI 工具向 Microsoft Entra 識別碼進行驗證。 您不需要在 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 或 Pg 管理員 （請參閱上述步驟以取得使用者連線）

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

  • 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;

注意

透過 Microsoft Entra ID 驗證使用者並不會授與使用者存取 適用於 PostgreSQL 的 Azure 資料庫 資料庫中物件的任何許可權。 您必須手動向使用者授與必要權限。

權杖驗證

適用於 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 識別碼中或有不同的用戶名稱，您可以使用 Microsoft Entra 群組來驗證此 PostgreSQL 使用者。 您可以使用符合 PostgreSQL 使用者的名稱建立 Microsoft Entra 群組，然後將角色azure_ad_user授與現有的 PostgreSQL 使用者，藉此將現有的 適用於 PostgreSQL 的 Azure 資料庫 使用者移轉至 Microsoft Entra 識別符：

GRANT azure_ad_user TO <new_user>;

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

下一步

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