Azure Cosmos DB SQL API 中的存取控制

發行項
08/05/2023

Azure Cosmos DB 是適用於現代化應用程式開發的完全受管理 NoSQL 資料庫服務。本文涵蓋適用於 Azure Cosmos DB 的 SQL API。 SQL API 中資源的存取權受到主要金鑰權杖或為資源權杖的控管。若要存取資源，選取的權杖會包含在 REST 授權標頭中，作為授權字串的一部分。

主要金鑰權杖

主要金鑰權杖是所有存取金鑰權杖，可讓使用者完全控制特定帳戶中的 Cosmos DB 資源。帳戶建立期間，會建立主要金鑰。有兩個集合的主索引鍵、主索引鍵和次要金鑰。帳戶的系統管理員可以再運用金鑰循環使用次要金鑰。此外，帳戶管理員可以也重新產生金鑰所需。如需重新產生和輪流金鑰的指示，請參閱保護 Azure Cosmos DB 中資料的存取。

資源權杖

在資料庫中的使用者設定資源權杖時，會建立資源權杖，以精確控制資源的存取控制，也稱為許可權資源。許可權資源包含雜湊資源權杖，其中包含使用者可存取的資源路徑和存取類型相關資訊所建構的雜湊資源權杖。權限資源語彙基元是時間界限，而且有效期間可以加以覆寫。當權限資源有 (POST、 GET、 PUT) 上作用時，會產生新的資源語彙基元。如需許可權和資源權杖的相關資訊，請參閱 Cosmos DB 許可權上的作業。

驗證標頭

無論您是使用主要金鑰權杖或資源權杖，所有 REST 作業都必須包含授權標頭與授權字串，才能與資源互動。授權字串具有下列格式：

type={typeoftoken}&ver={tokenversion}&sig={hashsignature}

授權字串看起來像下列範例：

type=master&ver=1.0&sig=5mDuQBYA0kb70WDJoTUzSBMTG3owkC0/cEN4fqa18/s=

以括弧括住的部分如下所示：

{typeoftoken} 表示如果您使用Azure Cosmos DB RBAC) ，則表示權杖類型：master、resource或aad (。
{tokenversion} 表示權杖的版本，目前為 1.0。
{hashsignature} 表示您使用Azure Cosmos DB RBAC的雜湊權杖簽章或oauth 權杖。

授權字串應該進行編碼，再將其新增至 REST 要求，以確保它包含無效的字元。請確定它是使用 MIME RFC2045 編碼的 Base64。此外，雜湊簽署中所使用的主要金鑰應該使用 MIME RFC2045 解碼，因為它是 Base64 編碼。如果您看到授權的任何問題，請參閱如何診斷和疑難排解未經授權的例外狀況。

建構主要權杖的雜湊權杖簽章

主要金鑰權杖的雜湊簽章可以從下列參數建構：Verb、ResourceType、ResourceLink和Date。

Verb 代表您要求的 HTTP 動詞。可能的值為：get、post、put、patch、delete

注意：值必須是小寫。

字串的 ResourceType 部分會識別要求所在的資源類型。可能的值包括：
- 資料庫作業： dbs
- 容器作業： colls
- 預存程式： sprocs
- 使用者定義函式： udfs
- 觸發器： triggers
- 使用者： users
- 許可權： permissions
- 專案層級作業： docs

注意： 這些值會區分大小寫，而且必須是小寫。

字串的 ResourceLink 部分是要求導向之資源的識別屬性。 ResourceLink 值取決於您嘗試執行的作業。每個作業都會遵循下列慣例，有自己的對應 ResourceLink：
- 如果針對特定資源執行作業，則此值就是該資源的連結。範例：
  - 針對取得資料庫使用： dbs/{databaseId}
  - 針對取得檔使用： dbs/{databaseId}/colls/{containerId}/docs/{docId}
- 如果針對一組資源執行作業， (List、Create、Query) 則此值為父資源的連結。範例：
  - 針對 [建立檔] 使用： dbs/{databaseId}/colls/{containerId}
  - 針對建立預存程式，請使用： dbs/{databaseId}/colls/{containerId}
  - 針對 [建立容器] 使用： dbs/{databaseId}
  - 針對建立資料庫使用：「」 - > 空字串，因為資料庫沒有父資源

注意： 當做 ResourceLink 值的一部分所參考的資源名稱會區分大小寫，而且必須符合它們在資料庫中宣告方式的大小寫。其他元件必須是小寫。

字串的 Date 部分是 UTC 日期和時間，訊息是以「HTTP-date」格式傳送 (，如 RFC 7231 日期/時間格式) 所定義，例如「Tue， 01 Nov 1994 08：12：31 GMT」。

在 C# 中，您可以在值上使用 DateTime.UtcNow 「R」格式規範來取得它。

這個相同的日期 (相同格式) 也必須在要求中當做 x-ms-date 標頭傳遞。

注意： 此值區分大小寫，而且必須全部小寫。

若要計算簽章，我們使用 SHA256 型雜湊型訊息驗證碼 (HMAC) 函式搭配 CosmosDB 金鑰作為秘密。

雜湊函式的承載是以上述 4 個元件為基礎，使用下列格式： "{verb}\n{resourceType}\n{resourceLink}\n{date}\n\n" (記下承載結尾的額外新行) 。

建構呼叫的 Authorization 標頭時，會使用函式的 Base64 編碼結果作為簽章。

有效授權標頭的範例 [C#]：

    httpClient.DefaultRequestHeaders.Clear();
    httpClient.DefaultRequestHeaders.Add("Accept", "application/json");
    httpClient.DefaultRequestHeaders.Add("authorization", auth); //generated using method below
    httpClient.DefaultRequestHeaders.Add("x-ms-date", requestDateString);
    httpClient.DefaultRequestHeaders.Add("x-ms-version", "2018-12-31");

產生有效授權簽章的範例 [C#] 方法：

若要查看 Cosmos DB REST API 的完整範例，請造訪 GitHub 上的 Cosmos DB REST API 範例存放庫

  
string GenerateMasterKeyAuthorizationSignature(HttpMethod verb, ResourceType resourceType, string resourceLink, string date, string key)
{
    var keyType = "master";
    var tokenVersion = "1.0";
    var payload = $"{verb.ToString().ToLowerInvariant()}\n{resourceType.ToString().ToLowerInvariant()}\n{resourceLink}\n{date.ToLowerInvariant()}\n\n";

    var hmacSha256 = new System.Security.Cryptography.HMACSHA256 { Key = Convert.FromBase64String(key) };
    var hashPayload = hmacSha256.ComputeHash(System.Text.Encoding.UTF8.GetBytes(payload));
    var signature = Convert.ToBase64String(hashPayload);
    var authSet = WebUtility.UrlEncode($"type={keyType}&ver={tokenVersion}&sig={signature}");

    return authSet;
}

Example [Node.js]:

  
var crypto = require("crypto");  
  
function getAuthorizationTokenUsingMasterKey(verb, resourceType, resourceId, date, masterKey) {  
    var key = new Buffer(masterKey, "base64");  
  
    var text = (verb || "").toLowerCase() + "\n" +   
               (resourceType || "").toLowerCase() + "\n" +   
               (resourceId || "") + "\n" +   
               date.toLowerCase() + "\n" +   
               "" + "\n";  
  
    var body = new Buffer(text, "utf8");  
    var signature = crypto.createHmac("sha256", key).update(body).digest("base64");  
  
    var MasterToken = "master";  
  
    var TokenVersion = "1.0";  
  
    return encodeURIComponent("type=" + MasterToken + "&ver=" + TokenVersion + "&sig=" + signature);  
}

範例編碼：

引數	值
動詞命令	GET
資源類型	「dbs」
資源連結	「dbs/ToDoList」
Date	2017 年 4 月 27 日 00：51：12 GMT
答案	dsZQi3KtZmCv1ljt3VNWNm7sQUF1y5rJfC6kv5Jiwv W0EndXdDku/dkKBp8/ufDToSxLzR4y+O/0H/t4bQtVNw==
索引鍵類型	master
權杖版本	1.0
輸出授權字串	type%3dmaster%26ver%3d1.0%26sig%3dc09PEVJr gp2uQRkr934kFbTqhByc7TVr3OHyqlu%2bc%2bc%3d

建構資源權杖的雜湊簽章

轉送伺服器必須產生資源權杖。伺服器可作為主要金鑰守護者，並針對不受信任的用戶端產生時間限制的權杖，例如網頁瀏覽器。

此伺服器會執行下列步驟：

處理新權杖的傳入用戶端要求。
以應用程式特定方式驗證用戶端身分識別。
如果用戶端成功驗證，它會使用 Cosmos DB 介面 (SDK 或 REST) 來產生新的限時權杖，並將其傳回給用戶端。

共用方式為