共用方式為

Azure Cosmos DB 中的資源令牌

  • 發行項

適用於：NoSQL MongoDB Cassandra Gremlin 桌子

資源令牌是可提供容器、分割區索引鍵或專案特定存取權的認證。 您可以微調它們，以根據每個使用者授與特定許可權，並直接使用適用於 Azure Cosmos DB 的 REST API。 資源令牌會使用針對讀取/寫入或只讀存取設定的主要或次要密鑰，提供驗證的替代方案。

重要

Microsoft 建議您使用最安全的可用驗證流程。 這個程序描述的驗證流程需要在應用程式中具備極高的信任度，且伴隨著其他流程並未面臨的風險。 請僅在其他較安全的流程 (例如受控身分識別) 皆不具可行性的情況下，才使用這個流程。

對於 Azure Cosmos DB，Microsoft Entra 驗證是可用的最安全驗證機制。 檢閱 API 的適當安全性指南：

原生 Azure Cosmos DB 用戶端連結庫會直接處理資源令牌產生和管理。 不過，如果您使用 REST，您必須自行建構要求/驗證標頭。 如需為 REST 建立驗證標頭的詳細資訊，請參閱 REST 中 Azure Cosmos DB 資源的訪問控制。

必要條件

  • 現有的 Azure Cosmos DB 帳戶
  • .NET 8 SDK （或更新版本）

建立使用者和許可權

首先，您必須使用適用於 NoSQL SDK 的 Azure Cosmos DB 來建立使用者。 然後，您可以為使用者建立許可權。

注意

許多 API，例如 Cassandra 和 Gremlin，不會透過其原生 SDK 公開介面來建立資源令牌。 若要使用資源令牌，您必須使用 NoSQL SDK 來與您的帳戶端點進行介面，而不論您選取的 API 為何。

  1. 從現有的帳戶取得 NoSQL 端點和其中一個帳戶的讀寫密鑰。

  2. 將 3.x 版的 Microsoft.Azure.Cosmos 套件新增至您的 .NET 專案。

    dotnet add package Microsoft.Azure.Cosmos --version 3.*

  3. 為 Microsoft.Azure.Cosmos 命名空間新增 using 區塊。

    using Microsoft.Azure.Cosmos;

  4. 建立新的用戶端，指定您的帳戶 NoSQL 端點和讀寫密鑰。

    CosmosClient client = new(
    accountEndpoint: "<account-nosql-endpoint>",
    authKeyOrResourceToken: "<account-read-write-key>"
);

    注意

    您必須針對通常採用下列格式的帳戶使用 NoSQL 端點： https://<account-name>.documents.azure.com:443/。

  5. 取得您的資料庫和容器物件。

    Database database = client.GetDatabase("<database-name>");
Container container = database.GetContainer("<container-name>");

  6. 在資料庫中建立指定用戶名稱的新使用者。

    User user = await database.CreateUserAsync("demo-user");

  7. 為使用者建立新的許可權，以指定許可權模式 （Read 或 All）、唯一標識符、限定範圍的容器，以及選擇性的數據分割索引鍵範圍。

    PermissionProperties permissionProperties = new(
    id: "read-permission",
    permissionMode: PermissionMode.All,
    container: container,
    resourcePartitionKey: new PartitionKey("partition-key-value")
);
Permission permission = await user.CreatePermissionAsync(permissionProperties);

取得資源令牌

現在，再次使用 NoSQL SDK 從帳戶取得資源令牌。

PermissionResponse response = await permission.ReadAsync();
string resourceToken = response.Resource.Token;

使用資源令牌

最後，您可以使用 API 的原生 SDK 來使用資源令牌。

using Microsoft.Azure.Cosmos;

CosmosClient client = new(
    accountEndpoint: "<account-nosql-endpoint>",
    authKeyOrResourceToken: "<resource-token>"
);

Container container = client.GetContainer("<database-name>", "<container-name>");

var iterator = container.GetItemQueryIterator<dynamic>("SELECT * FROM c");

while (iterator.HasMoreResults)
{
    foreach (var item in await iterator.ReadNextAsync())
    {
        Console.WriteLine(item);
    }
}