安全存取 Azure Cosmos DB 中的資料

發行項
03/27/2024

適用於：NoSQL

本文提供 Azure Cosmos DB 中資料存取控制的概觀。

Azure Cosmos DB 提供三種方法來控制資料存取。

存取控制類型	特性
主要/次要金鑰	允許任何管理或資料作業的共用祕密。它同時提供讀寫和唯讀變異。
角色型存取控制 (RBAC)	使用 Microsoft Entra 身分識別進行驗證的精細角色型權限模型。
資源權杖	根據原生 Azure Cosmos DB 使用者和權限的更細緻權限模型。

主要/次要金鑰

主要/次要金鑰可讓資料庫帳戶存取所有系統管理資源。每個帳戶都包含兩個金鑰：主要金鑰和次要金鑰。雙重金鑰的目的是讓您重新產生或輪替金鑰，以持續存取您的帳戶和資料。若要深入了解主要/次要金鑰，請參閱 Azure Cosmos DB 中的資料庫安全性概觀。

若要查看您的帳戶金鑰，請在左側功能表上選取 [金鑰]。然後，選取每個金鑰右邊的 [檢視] 圖示。選取 [複製] 按鈕以複製選取的金鑰。您可以選取每個金鑰相同的圖示，以在之後隱藏它們，以將圖示更新為 [隱藏] 按鈕。

Screenshot of the View account key for Azure Cosmos DB.

金鑰輪替和重新產生

注意

下節說明輪替和重新產生 NoSQL API 金鑰的步驟。如果您使用不同的 API，請參閱適用於 MongoDB 的 API、適用於 Cassandra 的 API、適用於 Gremlin 的 API，或適用於資料表的 API 章節。

若要監視您的帳戶是否有金鑰更新和金鑰重新產生，請參閱監視 Azure Cosmos DB 帳戶以取得金鑰更新和金鑰重新產生。

金鑰輪替和重新產生的程序很簡單。首先，請確定應用程式一直使用主要金鑰或次要金鑰來存取 Azure Cosmos DB 帳戶。然後，遵循下一節中的步驟。

如果應用程式目前使用主要金鑰
如果應用程式目前使用次要金鑰

在 Azure 入口網站中移至您的 Azure Cosmos DB 帳戶。
選取左側功能表上的 [金鑰]，然後從次要金鑰右側的省略號選取 [重新產生次要金鑰]。
驗證新的次要金鑰是否能針對 Azure Cosmos DB 帳戶保持正常運作。根據 Azure Cosmos DB 帳戶的大小，重新產生金鑰可能需要一分鐘到數小時不等的時間。
在應用程式中將主要金鑰取代為次要金鑰。
回到 Azure 入口網站，並觸發重新產生主要金鑰。

使用主要金鑰的程式碼範例

下列程式代碼範例說明如何使用 Azure Cosmos DB 帳戶端點和主要金鑰來具現化 CosmosClient：

// Read the Azure Cosmos DB endpointUrl and authorization keys from config.
// These values are available from the Azure portal on the Azure Cosmos DB account blade under "Keys".
// Keep these values in a safe and secure location. Together they provide Administrative access to your Azure Cosmos DB account.

private static readonly string endpointUrl = ConfigurationManager.AppSettings["EndPointUrl"];
private static readonly string authorizationKey = ConfigurationManager.AppSettings["AuthorizationKey"];

CosmosClient client = new CosmosClient(endpointUrl, authorizationKey);

角色型存取控制

Azure Cosmos DB 會公開內建的 RBAC 系統，讓您：

使用 Microsoft Entra 身分識別驗證您的資料要求。
使用更精細的角色型權限模型來授權資料要求。

在下列情況中，Azure Cosmos DB RBAC 是理想的存取控制方法：

您不想要使用共用祕密 (例如主要金鑰)，而且偏好依賴權杖型驗證機制。
您想要使用 Microsoft Entra 身分識別來驗證您的要求。
您需要更細緻的權限模型，以嚴格限制允許您的身分識別執行的資料庫作業。
您想要將存取控制原則具體化為可指派給多個身分識別的「角色」。

若要深入了解 Azure Cosmos DB RBAC，請參閱設定 Azure Cosmos DB 帳戶的角色型存取控制。

如需為 Azure Cosmos DB for MongoDB 設定 RBAC 的資訊和範例程式碼，請參閱為 Azure Cosmos DB for MongoDB 設定角色型存取控制。

資源權杖

資源權杖允許存取資料庫內的應用程式資源。資源權杖：

提供特定容器、分割區索引鍵、檔和附件的存取權。
在使用者被授與特定資源的權限時建立。
當 POST、GET 或 PUT 呼叫處理權限資源時，會重新建立。
使用特別為使用者、資源和權限建構的雜湊資源權杖。
是與可自訂的有效期間繫結的時間。預設有效時間範圍是一小時。不過，您可以明確指定權杖存留期，最多 24 個小時。
提供安全的替代方式來分發主要金鑰。
可讓用戶端根據所授與的權限，讀取、寫入和刪除 Azure Cosmos DB 帳戶中的資源。

若要對無法託付主要金鑰的用戶端提供 Azure Cosmos DB 帳戶內資源的存取權，您可以使用資源權杖 (方法是建立 Azure Cosmos DB 使用者和權限)。

Azure Cosmos DB 資源權杖提供一個安全的替代方式，不需要主要或唯讀金鑰即可讓用戶端根據授與他們的權限來讀取、寫入和刪除 Azure Cosmos DB 帳戶中的資源。

以下是典型的設計模式，其中資源權杖可能會被要求、產生和傳遞給用戶端：

設定中間層服務，以協助行動應用程式分享使用者相片。
中間層服務擁有 Azure Cosmos DB 帳戶的主要金鑰。
相片應用程式安裝於使用者的行動裝置上。
登入時，相片應用程式會建立中間層服務的使用者身分識別。這項身分識別建立的機制完全取決於應用程式。
建立身分識別之後，中間層服務會根據身分識別要求權限。
中間層服務會將資源權杖送回電話應用程式。
電話應用程式可以繼續使用資源權杖，利用資源權杖所定義的權限並在資源權杖所允許的間隔內，直接存取 Azure Cosmos DB 資源。
資源權杖過期時，後續要求會收到 401 未經授權的例外狀況。此時，電話應用程式會重新建立身分識別，並要求新的資源權杖。

原生 Azure Cosmos DB 用戶端程式庫會處理資源權杖產生和管理。不過，如果您使用 REST，則必須建構要求/驗證標頭。如需建立 REST 驗證標頭的詳細資訊，請參閱 Azure Cosmos DB 資源的存取控制或是 .NET SDK 或 Node.js SDK 的原始程式碼。

如需用來產生或代理資源權杖的中間層服務的範例，請參閱 ResourceTokenBroker 應用程式。

使用者

Azure Cosmos DB 使用者與 Azure Cosmos DB 資料庫相關聯。每個資料庫都包含零個或多個 Azure Cosmos DB 使用者。下列程式碼範例顯示如何使用 Azure Cosmos DB .NET SDK v3 來建立 Azure Cosmos DB 使用者。

// Create a user.
Database database = client.GetDatabase("SalesDatabase");
User user = await database.CreateUserAsync("User 1");

注意

每個 Azure Cosmos DB 使用者都有一種方法 ReadAsync() ，可用來擷取與使用者相關聯的權限清單。

權限

權限資源會與使用者相關聯，並指派給特定資源。每位使用者都可能包含零個或多個權限。使用者嘗試存取特定容器或是特定分割區索引鍵中的資料時，權限資源會提供使用者所需的安全性權杖存取權。權限資源可能提供兩種可用的存取等級：

全部：使用者具有資源的完整權限。
讀取：使用者只能讀取資源的內容，但無法執行資源的寫入、更新或刪除作業。

注意

若要執行預存程序，使用者必須具有即將執行預存程序之容器的所有權限。

如果您啟用資料平面要求的診斷記錄，則會記錄對應至權限的下列兩個屬性：

resourceTokenPermissionId：此屬性指出您指定的資源權杖權限識別碼。
resourceTokenPermissionMode：此屬性指出您在建立資源權杖時所設定的權限模式。權限模式可以有 All 或 Read 這類的值。

建立權限的程式碼範例

下列程式碼範例示範如何建立權限資源，讀取權限資源的資源權杖，並將權限與您剛建立的使用者產生關聯。

// Create a permission on a container and specific partition key value
Container container = client.GetContainer("SalesDatabase", "OrdersContainer");
await user.CreatePermissionAsync(
    new PermissionProperties(
        id: "permissionUser1Orders", 
        permissionMode: PermissionMode.All, 
        container: container,
        resourcePartitionKey: new PartitionKey("012345")));

使用者讀取權限的程式碼範例

下列代碼段示範如何擷取與您建立的使用者相關聯的權限，並為使用者具現化新的 CosmosClient，範圍設定為單一分割區索引鍵。

// Read a permission, create user client session.
Permission permission = await user.GetPermission("permissionUser1Orders").ReadAsync();

CosmosClient client = new CosmosClient(accountEndpoint: "MyEndpoint", authKeyOrResourceToken: permission.Resource.Token);

RBAC 與資源權杖之間的差異

主旨	RBAC	資源權杖
驗證	使用 Microsoft Entra ID。	根據原生 Azure Cosmos DB 使用者。整合資源權杖與 Microsoft Entra 識別碼需要額外的工作，才能橋接 Microsoft Entra 身分識別和 Azure Cosmos DB 使用者。
授權	角色型：角色定義會對應允許的動作，而且可以指派給多個身分識別。	權限型：針對每個 Azure Cosmos DB 使用者，您需要指派資料存取權限。
權杖範圍	Microsoft Entra 權杖會攜帶要求者的身分識別。此身分識別會與所有指派的角色定義進行比對，以執行授權。	資源權杖會攜帶授與特定 Azure Cosmos DB 資源上特定 Azure Cosmos DB 使用者的權限。不同資源上的授權要求可能需要不同的權杖。
權杖重新整理	Microsoft Entra 權杖在到期時會由 Azure Cosmos DB SDK 自動重新整理。	不支援資源權杖重新整理。資源權杖到期時，需要發出新的資源權杖。

新增使用者和指派角色

若要將 Azure Cosmos DB 帳戶讀者存取權新增至您的使用者帳戶，請在 Azure 入口網站執行下列步驟，以取得訂用帳戶擁有者。

開啟 Azure 入口網站並選取您的 Azure Cosmos DB 帳戶。
選取 [存取控制 (IAM)]。
選取 [新增]> [新增角色指派]，開啟 [新增角色指派] 頁面。
指派下列角色。如需詳細步驟，請參閱使用 Azure 入口網站指派 Azure 角色。

設定值

角色 Cosmos DB 帳戶讀者。

存取權指派對象使用者、群組或服務主體。

成員目錄中您要為其授與存取權的使用者、群組或應用程式。

設定	值
角色	Cosmos DB 帳戶讀者。
存取權指派對象	使用者、群組或服務主體。
成員	目錄中您要為其授與存取權的使用者、群組或應用程式。

實體現在已可讀取 Azure Cosmos DB 資源。

刪除或匯出使用者資料

作為資料庫服務，Azure Cosmos DB 可讓您搜尋、選取、修改，和刪除位於資料庫或容器中的任何資料。您必須負責使用提供的 API，並視需要定義尋找和清除任何個人資料所需的邏輯。

每個多模型 API (SQL、MongoDB、Gremlin、Cassandra，或資料表) 都會提供不同的語言 SDK，其中包含根據自訂述詞來搜尋和刪除資料的方法。您也可以啟用存留時間 (TTL) 功能，在指定期間後自動刪除資料，完全不會產生任何額外費用。

注意

如需檢視或刪除個人資料的詳細資訊，請參閱適用於 GDPR 的 Azure 資料主體要求。如需 GDPR 的詳細資訊，請參閱 Microsoft 信任中心的 GDPR 區段和服務信任入口網站的 GDPR 區段。

下一步

若要深入了解 Azure Cosmos DB 資料庫安全性，請參閱 Azure Cosmos DB 資料庫安全性。
若要了解如何建構 Azure Cosmos DB 授權權杖，請參閱 Azure Cosmos DB 資源的存取控制。
如需使用者管理範例 (含使用者和權限)，請參閱 .NET SDK v3 使用者管理範例。
如需為 Azure Cosmos DB for MongoDB 設定 RBAC 的資訊和範例程式碼，請參閱為 Azure Cosmos DB for MongoDB 設定角色型存取控制。