移轉 Python 應用程式以對 Azure SQL 資料庫使用無密碼連線

適用於：Azure SQL 資料庫

對 Azure SQL 資料庫的應用程式要求必須經過驗證。 儘管有多個選項可用於對 Azure SQL 資料庫進行驗證，但您應該盡可能優先考慮在應用程式中使用無密碼連線。 使用密碼或祕密金鑰的傳統驗證方法會帶來安全風險並提高複雜性。 請瀏覽 Azure 服務中樞的無密碼連線，深入了解移至無密碼連線的好處。 下列教學課程說明如何移轉現有的 Python 應用程式以連線至 Azure SQL 資料庫，從而使用無密碼連線，而不是使用者名稱和密碼解決方案。

mssql-python 驅動程式內建支援 Microsoft Entra 認證，使無密碼連線變得簡單且只需最小的程式碼變更。

設定 Azure SQL 資料庫

無密碼連線使用 Microsoft Entra 驗證來連線到 Azure 服務，包括 Azure SQL 資料庫。 Microsoft Entra 驗證，您可以在中央位置管理身分識別，以簡化權限管理。 了解有關為 Azure SQL 資料庫設定 Microsoft Entra 驗證的詳細資訊：

• Microsoft Entra 驗證概觀
• 設定 Microsoft Entra 驗證

針對此移轉指南，請確定您已將 Microsoft Entra 管理員指派至 Azure SQL 資料庫。

1. 瀏覽至邏輯伺服器的 Microsoft Entra 頁面。

2. 選取 [設定管理員] 以開啟 [Microsoft Entra ID] 飛出視窗功能表。

3. 在 [Microsoft Entra ID] 飛出視窗功能表中，搜尋要指派為管理員的使用者。

4. 選取使用者，再選擇 [選取]。

   

設定您的本機開發環境

可以將無密碼連線設定為同時適用於本機和 Azure 託管的環境。 在本節中，您會套用設定，以允許個別使用者向 Azure SQL 資料庫驗證，進行本機開發。

登入 Azure

本地開發時，請確保你用的是你想用來存取 Azure SQL 資料庫的 Microsoft Entra 帳號登入。 可以透過熱門的開發工具進行驗證，例如 Azure CLI 或 Azure PowerShell。 您可以用來驗證的開發工具會因語言而異。

Azure CLI

請透過 Azure CLI 使用以下指令登入 Azure。 這方法適用於 Windows、macOS 和 Linux。

az login

Visual Studio

選取 Visual Studio 右上角的 [登入] 按鈕。

使用您先前指派角色的 Microsoft Entra 帳戶登入。

Visual Studio 程式碼

對於 Visual Studio Code，請在整合終端機使用 Azure CLI 登入：

1. 在 VS Code 中開啟終端機（終端機 > 新終端機）。

2. 使用下列命令登入 Azure：

   az login
   

此方法在 Windows、macOS 與 Linux 上都能穩定運作。

PowerShell

請使用以下指令使用 PowerShell 登入 Azure：

Connect-AzAccount

建立資料庫使用者並指派角色

在 Azure SQL 資料庫中建立使用者。 使用者應與 [登入 Azure] 區段用於本機登入的 Azure 帳戶對應。

1. 在 Azure 入口網站中，瀏覽至 SQL Database，然後選取 [查詢編輯器 (預覽版)]。

2. 選取畫面右側的 [以 <your-username> 的身分繼續]，使用您的帳戶登入資料庫。

3. 在查詢編輯器檢視上，執行下列 T-SQL 命令：

   CREATE USER [user@domain] FROM EXTERNAL PROVIDER;
   ALTER ROLE db_datareader ADD MEMBER [user@domain];
   ALTER ROLE db_datawriter ADD MEMBER [user@domain];
   ALTER ROLE db_ddladmin ADD MEMBER [user@domain];
   GO
   

   

   執行這些命令會將 SQL DB 參與者角色指派給指定的帳戶。 此角色可讓身分識別讀取、寫入及修改資料庫的資料和結構描述。 如需指派的角色的詳細資訊，請參閱固定資料庫角色。

更新本機連線設定

使用 mssql-python 遷移到無密碼連線只需要更換連線字串。 驅動程式內建支援 Microsoft Entra 認證模式，免除手動令牌處理的需求。

from os import getenv
from dotenv import load_dotenv
from mssql_python import connect

load_dotenv()

connection_string = getenv("AZURE_SQL_CONNECTIONSTRING")

def get_all():
    with connect(connection_string) as conn:
        cursor = conn.cursor()
        cursor.execute("SELECT * FROM Persons")
        # Do something with the data
    return

若要更新本地開發所需的參考連接字串（AZURE_SQL_CONNECTIONSTRING），請在專案資料夾中建立 .env 一個檔案，採用無密碼連接字串格式，並使用 ActiveDirectoryDefault 認證技術：

AZURE_SQL_CONNECTIONSTRING=Server=tcp:<database-server-name>.database.windows.net,1433;Database=<database-name>;Encrypt=yes;TrustServerCertificate=no;Connection Timeout=30;Authentication=ActiveDirectoryDefault

ActiveDirectoryDefault 自動從多個來源（Azure CLI、環境變數、Visual Studio 等）發現憑證，無需互動式登入。 這種方法對開發來說很方便，但因為會依序嘗試每個憑證來源，會增加延遲。

重要

ActiveDirectoryDefault 僅供地方開發。 它會依序嘗試多種認證方法，這會增加延遲，並可能在生產環境中造成意外行為。 對於生產應用，請使用你情境下的特定認證方法：

• Azure App Service/Functions：使用ActiveDirectoryMSI（受管理的身份）
• 互動式使用者登入：使用 ActiveDirectoryInteractive
• 服務主體：使用 ActiveDirectoryServicePrincipal

測試應用程式

在本機執行您的應用程式，並驗證 Azure SQL 資料庫的連線是否如預期般運作。 請記住，變更 Azure 使用者和角色可能需要幾分鐘的時間，才能透過 Azure 環境傳播。 您的應用程式現已設定為在本機執行，而開發人員不需要管理應用程式本身的祕密。

設定 Azure 主控環境

一旦您的應用程式設定為在本機使用無密碼連線，相同的程式碼就可以在部署至 Azure 之後向 Azure SQL 資料庫驗證。 下列各節說明如何設定已部署的應用程式，以使用受控識別連線至 Azure SQL 資料庫。 受控識別在 Microsoft Entra ID (以前稱為 Azure Active Directory) 中提供自動受控識別，供應用程式在連接到支援 Microsoft Entra 驗證的資源時使用。 深入了解受控識別：

• 無密碼概觀
• 受控識別最佳做法

建立受控識別

使用 Azure 入口網站或 Azure CLI 建立使用者指派的受控識別。 您的應用程式使用身分識別向其他服務進行驗證。

Azure 入口網站

1. 在 Azure 入口網站頂端，搜尋受控識別。 選取受控識別結果。
2. 選取受控識別概觀頁面頂端的+ 建立。
3. 在 [基本] 索引標籤上，輸入下列值：
   • 訂用帳戶：選取您想要的訂用帳戶。
   • [資源群組]：選取您需要的資源群組。
   • 區域：選取靠近您所在位置的區域。
   • 名稱：輸入身分識別的可辨識名稱，例如 MigrationIdentity。
4. 選取頁面底部的 [檢閱 + 建立] 。
5. 驗證檢查完成時，請選取建立。 Azure 會建立新的使用者指派身分識別。

建立資源之後，請選取移至資源以檢視受控識別的詳細資料。

Azure CLI

使用az identity create命令，以建立使用者指派的受控識別：

az identity create --name MigrationIdentity --resource-group <resource-group>

將受控識別與您的 Web 應用程式關聯

將 Web 應用程式設定為使用您建立的使用者指派的受控識別。

Azure 入口網站

完成 Azure 入口網站中的下列步驟，以將使用者指派的受控識別與您的應用程式關聯。 這些步驟也適用於下列 Azure 服務：

• Azure Spring 應用程式
• Azure 容器應用程式
• Azure 虛擬機器
• Azure Kubernetes Service

1. 導覽至您 Web 應用程式的概觀頁面。

2. 從左側導覽中，選取身分識別。

3. 在身分識別頁面上，切換至使用者指派索引標籤。

4. 選取+ 新增，以開啟新增使用者指派的受控識別 飛出視窗。

5. 選取先前用來建立身分識別的訂用帳戶。

6. 依名稱搜尋 MigrationIdentity，然後從搜尋結果中予以選取。

7. 選取新增，以將身分識別與您的應用程式相關聯。

   

Azure CLI

使用下列 Azure CLI 命令，將身分識別與您的應用程式關聯：

擷取您使用 az identity show 命令建立之受控識別的完整資源識別碼。 複製輸出值以在下一個步驟中使用。

az identity show --name MigrationIdentity -g <your-identity-resource-group-name> --query id

Azure 應用服務

可以使用 az webapp identity assign 命令，將受控識別指派給 Azure App Service 執行個體。 --identities 參數需要您在上一個步驟中擷取之受控識別的完整資源識別碼。 完整資源識別碼應以 '/subscriptions/{subscriptionId}' 或 '/providers/{resourceProviderNamespace}/' 開頭。

az webapp identity assign \
    --resource-group <resource-group-name> \
    --name <webapp-name> \
    --identities <managed-identity-id>

如果您使用 Git Bash，請在使用完整資源識別碼時注意路徑轉換。 若要停用路徑轉換，請將 MSYS_NO_PATHCONV=1 新增至命令的開頭。 如需詳細資訊，請參閱自動翻譯資源識別碼。

Azure Spring Apps

您可以使用 Azure CLI 中的 az spring app identity assign 命令，將受控識別指派給 Azure Spring Apps 執行個體。

az spring app identity assign \
    --resource-group <resource-group-name> \
    --name <app-name> \
    --service <service-name> \
    --user-assigned <managed-identity-id>

Azure 容器應用程式

您可以使用 az containerapp identity assign 命令，以將受控識別指派給虛擬機器。

az containerapp identity assign \
    --resource-group <resource-group-name> \
    --name <app-name> \
    --user-assigned <managed-identity-id>

Azure 虛擬機器

您可以使用 az vm identity assign 命令，將受控識別指派給虛擬機器。

az vm identity assign \
    --resource-group <resource-group-name> \
    --name <virtual-machine-name> \
    --identities <managed-identity-id>

Azure Kubernetes 服務

可以使用 az aks update 命令，將受控識別指派給 Azure Kubernetes Service (AKS) 執行個體。

az aks update \
    --resource-group <resource-group-name> \
    --name <cluster-name> \
    --enable-managed-identity \
    --assign-identity <managed-identity-id> \
    --assign-kubelet-identity <managed-identity-id>

為身分識別建立資料庫使用者並指派角色

建立對應回使用者指派的受控識別的 SQL 資料庫使用者。 將必要的 SQL 角色指派給使用者，以允許您的應用程式讀取、寫入和修改資料庫資料和結構描述。

1. 在 Azure 入口網站中，瀏覽至您的 SQL 資料庫，然後選取 [查詢編輯器 (預覽)]。

2. 選取畫面右側的 [以 <username> 的身分繼續]，使用您的帳戶登入資料庫。

3. 在查詢編輯器檢視上，執行下列 T-SQL 命令：

   CREATE USER [user-assigned-identity-name] FROM EXTERNAL PROVIDER;
   ALTER ROLE db_datareader ADD MEMBER [user-assigned-identity-name];
   ALTER ROLE db_datawriter ADD MEMBER [user-assigned-identity-name];
   ALTER ROLE db_ddladmin ADD MEMBER [user-assigned-identity-name];
   GO
   

   

   執行這些命令會將 SQL DB 參與者角色指派給使用者指派的受控識別。 此角色可讓身分識別讀取、寫入及修改資料庫的資料和結構描述。

重要

在企業實際執行環境中指派資料庫使用者角色時請小心。 在這些案例中，應用程式不應該使用提升權限的單一身分識別來執行所有作業。 針對特定工作設定具特定權限的多個識別，以實作最低權限的準則。

您可以在下列資源上深入了解如何設定資料庫角色和安全性：

• 教學課程：保護 Azure SQL 資料庫中的資料庫
• 授權資料庫存取 SQL Database

更新連接字串

更新你的 Azure 應用程式設定，改用無密碼的連線字串格式，並搭配 ActiveDirectoryMSI 認證來管理身份。

連接字串可以作為環境變數儲存在應用程式主控環境中。 下列指示針對 App Service，但其他 Azure 主控服務會提供類似的設定。

Server=tcp:<database-server-name>.database.windows.net,1433;Database=<database-name>;Encrypt=yes;TrustServerCertificate=no;Connection Timeout=30;Authentication=ActiveDirectoryMSI

<database-server-name> 是 Azure SQL 資料庫伺服器的名稱，<database-name> 是您的 Azure SQL 資料庫的名稱。

建立受控識別用戶端識別碼的應用程式設定

若要使用使用者指派的受控識別，請建立 AZURE_CLIENT_ID 環境變數，並將它設定為等於受控識別的用戶端標識符。 可以在應用程式的 [設定] 區段中，於 Azure 入口網站中設定此變數。 可以在 Azure 入口網站受控識別資源的 [概觀] 區段中找到用戶端識別碼。

儲存變更，並在應用程式未自動執行時重新啟動。

注意

使用使用者指派的管理身份時，請在連接字串中包含客戶端 ID，並使用參數：User Id

Server=tcp:<database-server-name>.database.windows.net,1433;Database=<database-name>;Encrypt=yes;TrustServerCertificate=no;Connection Timeout=30;Authentication=ActiveDirectoryMSI;User Id=<managed-identity-client-id>

若省略參數 User Id ，驅動程式將使用系統指定的管理身份（若已設定）。

測試應用程式

測試應用程式，確保一切都能正常運作。 所有變更可能需要幾分鐘的時間，才能透過 Azure 環境傳播。

相關內容

• MSSQL-Python 驅動程式文件
• 無密碼概觀
• 受控識別最佳做法
• 教學課程：保護 Azure SQL 資料庫中的資料庫
• 授權資料庫存取 SQL Database