Share via

Hozzáférés-vezérlés az Azure Cosmos DB SQL API-ban

  • Cikk

Az Azure Cosmos DB egy teljes körűen felügyelt NoSQL adatbázis-szolgáltatás a modern alkalmazásfejlesztéshez. Ez a cikk az Azure Cosmos DB SQL API-jával foglalkozik. Az SQL API-ban az erőforrásokhoz való hozzáférést egy főkulcs- vagy erőforrás-jogkivonat szabályozza. Az erőforrásokhoz való hozzáférés érdekében a kiválasztott jogkivonat bekerül a REST engedélyezési fejlécébe az engedélyezési sztring részeként.

Főkulcs-jogkivonatok

A főkulcs-jogkivonat az összes hozzáférési kulcs jogkivonata, amely lehetővé teszi a felhasználók számára, hogy teljes hozzáféréssel rendelkezzenek a Cosmos DB-erőforrások felett egy adott fiókban. A főkulcs a fiók létrehozásakor jön létre. Két főkulcskészlet létezik, az elsődleges kulcs és a másodlagos kulcs. A fiók rendszergazdája ezután a másodlagos kulccsal gyakorolhatja a kulcsrotálást. Emellett a fiókadminisztrátor szükség szerint újragenerálhatja a kulcsokat. A kulcsok újragenerálásával és működésével kapcsolatos utasításokért lásd: Adatok biztonságos elérése az Azure Cosmos DB-ben.

Erőforrás-jogkivonatok

Az erőforrás-jogkivonatok akkor jönnek létre, ha az adatbázis felhasználói hozzáférési engedélyekkel vannak beállítva az erőforráson végzett pontos hozzáférés-vezérléshez, más néven engedélyerőforrásként. Az engedélyerőforrás tartalmaz egy kivonaterőforrás-jogkivonatot, amely az erőforrás elérési útjával és a felhasználó hozzáféréssel rendelkező hozzáférési típusával kapcsolatos információkat tartalmazza. Az engedélyerőforrás-jogkivonat időhöz kötött, és az érvényességi időtartam felülírható. Ha egy engedélyerőforrást a rendszer a (POST, GET, PUT) alapján hajt végre, egy új erőforrás-jogkivonat jön létre. Az engedélyekkel és az erőforrás-jogkivonatokkal kapcsolatos információkért lásd : Műveletek a Cosmos DB-engedélyeken.

Engedélyezési fejléc

Minden REST-műveletnek, függetlenül attól, hogy főkulcs-jogkivonatot vagy erőforrás-jogkivonatot használ, tartalmaznia kell az engedélyezési fejlécet az engedélyezési sztringgel az erőforrással való interakcióhoz. Az engedélyezési sztring formátuma a következő:

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

Az engedélyezési sztring az alábbi példához hasonlóan néz ki:

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

A szögletes zárójelek közé foglalt részek a következők:

  • A(z) {typeoftoken} a token típusát jelöli: master, resource vagy aad (ha Azure Cosmos DB RBAC-t használ).

  • A {tokenversion} a jogkivonat verzióját jelöli, amely jelenleg 1.0.

  • A(z) {hashsignature} a kivonatolt jogkivonat aláírását vagy az oauth tokent jelöli, ha Azure Cosmos DB RBAC-t használ.

Az engedélyezési sztringet kódolni kell, mielőtt hozzáadja a REST-kérelemhez, hogy biztosan ne tartalmaz-e érvénytelen karaktereket. Győződjön meg arról, hogy a Base64 a MIME RFC2045 használatával van kódolva. Emellett a kivonatolóban használt főkulcsot a MIME RFC2045 használatával kell dekódolni, mivel az Base64 kódolású. Ha bármilyen problémát tapasztal az engedélyezéssel kapcsolatban, tekintse meg a jogosulatlan kivételek diagnosztizálásáról és hibaelhárításáról című témakört.

Kivonatolt jogkivonat aláírásának létrehozása fő jogkivonathoz

A főkulcs-jogkivonat kivonata a következő paraméterekből hozható létre: Verb, ResourceType, ResourceLink és Date.

  1. Az ige a kérés HTTP-parancsát jelöli. Lehetséges értékek: get, post, put, patch, delete

Megjegyzés:: Az értékeknek kisbetűsnek kell lenniük.

  1. A sztring ResourceType része azonosítja az erőforrás típusát, amelyről a kérés szól. Lehetséges értékek:
    • Adatbázis-műveletek: dbs
    • Tárolóműveletek: colls
    • Tárolt eljárások: sprocs
    • Felhasználó által definiált függvények: udfs
    • Eseményindítók: triggers
    • Felhasználók: users
    • Engedélyek: permissions
    • Elemszintű műveletek: docs

Megjegyzés: Az értékek megkülönböztetik a kis- és nagybetűket, és kisbetűknek kell lenniük.

  1. A sztring ResourceLink része annak az erőforrásnak az identitástulajdonsága, amelybe a kérés irányul. A ResourceLink értéke a végrehajtani kívánt művelettől függ. Minden műveletnek saját resourceLinkje lesz a következő konvenció szerint:

    • Ha a műveletet egy adott erőforráson hajtják végre, akkor az érték az adott erőforrásra mutató hivatkozás. Példák:

      • Az Adatbázis lekérése szolgáltatáshoz használja a következőt: dbs/{databaseId}
      • Dokumentum lekérése: dbs/{databaseId}/colls/{containerId}/docs/{docId}

    • Ha a műveletet erőforráskészleten (Lista, Létrehozás, Lekérdezés) hajtják végre, akkor az érték a szülőerőforrás csatolása. Példák:

      • Dokumentum létrehozásakor használja a következőt: dbs/{databaseId}/colls/{containerId}
      • Tárolt eljárás létrehozása esetén használja a következőt: dbs/{databaseId}/colls/{containerId}
      • Tároló létrehozása esetén használja a következőt: dbs/{databaseId}
      • Adatbázis létrehozása esetén használja a következőt: "" –> üres sztring, mivel az adatbázisok nem rendelkeznek szülőerőforrással

Megjegyzés: A ResourceLink érték részeként hivatkozott erőforrásnevek megkülönböztetik a kis- és nagybetűket, és meg kell egyezniük az adatbázisban deklarálásuk módjával. A többi összetevőnek kisbetűsnek kell lennie.

  1. A sztring Dátum része az üzenet elküldésének UTC-dátuma és időpontja (az RFC 7231 dátum-/időformátum által meghatározott HTTP-dátum formátumban), például "Kedd, 1994. nov. 11., 08:12:31 GMT".

    A C#-ban az "R" formátumkijelölővel szerezhető be az DateTime.UtcNow értéken.

    Ugyanezt a dátumot (azonos formátumú) fejlécként x-ms-date is át kell adni a kérelemben.

Megjegyzés: Az érték megkülönbözteti a kis- és nagybetűket, és kisbetűknek kell lenniük.

Az aláírás kiszámításához az SHA256-alapú kivonatalapú üzenethitelesítési kód (HMAC) függvényt használjuk, titkos kulcsként a CosmosDB-kulcsot használjuk.

A kivonatoló függvény hasznos adatai a fent bemutatott 4 összetevőn alapulnak a következő formátum használatával: "{verb}\n{resourceType}\n{resourceLink}\n{date}\n\n" (jegyezze fel a hasznos adat végén található extra új sort).

A függvény Base64 kódolású eredménye lesz aláírásként használva a hívás Engedélyezési fejlécének létrehozásakor.

Példa [C#] egy érvényes engedélyezési fejlécre:

    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");

Példa [C#] metódusra érvényes engedélyezési aláírás létrehozásához:

A Cosmos DB REST API teljes mintáinak megtekintéséhez látogasson el a Cosmos DB REST API-minták adattárára a GitHubon

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

Példa [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);  
}

Példakódolás:

Argumentum Érték
Művelet GET
Erőforrás típusa "dbs"
Erőforrás-hivatkozás "dbs/ToDoList"
Dátum Cs, 27 Apr 2017 00:51:12 GMT
Kulcs dsZQi3KtZmCv1ljt3VNWNm7sQUF1y5rJfC6kv5Jiwv
W0EndXdDku/dkKBp8/ufDToSxLzR4y+O/0H/t4bQtVNw==
Kulcs típusa master
Jogkivonat verziója 1.0
Kimeneti engedélyezési sztring type%3dmaster%26ver%3d1.0%26sig%3dc09PEVJr
gp2uQRkr934kFbTqhByc7TVr3OHyqlu%2bc%2bc%3d

Erőforrás-jogkivonat kivonataláírásának létrehozása

Az erőforrás-jogkivonatokat egy köztes kiszolgálónak kell létrehoznia. A kiszolgáló főkulcsőrként szolgál, és időkorlátos jogkivonatokat hoz létre nem megbízható ügyfelek, például webböngészők számára.

Ez a kiszolgáló a következő lépéseket hajtja végre:

  1. Kezeli az új jogkivonatok bejövő ügyfélkérelmeit.

  2. Alkalmazásspecifikus módon ellenőrzi az ügyfélidentitást.

  3. Ha az ügyfél sikeresen hitelesíti magát, a Cosmos DB-felületek (SDK vagy REST) használatával hoz létre egy új, időkorlátos jogkivonatot, és visszaadja az ügyfélnek.

Lásd még: