Kontrol akses di Azure Cosmos DB SQL API

  • Artikel

Azure Cosmos DB adalah layanan database NoSQL yang terkelola sepenuhnya untuk pengembangan aplikasi modern. Artikel ini membahas SQL API untuk Azure Cosmos DB. Akses ke sumber daya di API SQL diatur oleh token kunci master atau token sumber daya. Untuk mengakses sumber daya, token yang dipilih disertakan dalam header otorisasi REST, sebagai bagian dari string otorisasi.

Token kunci master

Token kunci master adalah semua token kunci akses yang memungkinkan pengguna untuk memiliki kontrol penuh atas sumber daya Cosmos DB di akun tertentu. Kunci master dibuat selama pembuatan akun. Ada dua set kunci master, kunci primer dan kunci sekunder. Administrator akun kemudian dapat menjalankan rotasi kunci menggunakan kunci sekunder. Selain itu, administrator akun juga dapat meregenerasi kunci sesuai kebutuhan. Untuk instruksi tentang meregenerasi dan menggulirkan kunci, lihat Mengamankan akses ke data di Azure Cosmos DB.

Token sumber daya

Token sumber daya dibuat saat pengguna dalam database disiapkan dengan izin akses untuk kontrol akses yang tepat pada sumber daya, juga dikenal sebagai sumber daya izin. Sumber daya izin berisi token sumber daya hash yang dibangun dengan informasi mengenai jalur sumber daya dan jenis akses yang dapat diakses pengguna. Token sumber daya izin terikat waktu dan periode validitas dapat ditimpa. Saat sumber daya izin ditindaklanjuti pada (POST, GET, PUT), token sumber daya baru dibuat. Untuk informasi tentang izin dan token sumber daya, lihat Operasi pada Izin Cosmos DB.

Header otorisasi

Semua operasi REST, baik Anda menggunakan token kunci master atau token sumber daya, harus menyertakan header otorisasi dengan string otorisasi untuk berinteraksi dengan sumber daya. String otorisasi memiliki format berikut:

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

String otorisasi terlihat seperti contoh ini:

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

Bagian-bagian yang diapit dalam tanda kurung adalah sebagai berikut:

  • {typeoftoken} menunjukkan jenis token: master, sumber daya, atau aad(jika Anda menggunakan Azure Cosmos DB RBAC).

  • {tokenversion} menunjukkan versi token, saat ini 1.0.

  • {hashsignature} menunjukkan tanda tangan token yang di-hash atau token oauth jika Anda menggunakan Azure Cosmos DB RBAC.

String otorisasi harus dikodekan sebelum menambahkannya ke permintaan REST untuk memastikan bahwa string tersebut tidak berisi karakter yang tidak valid. Pastikan base64 dikodekan menggunakan MIME RFC2045. Selain itu, kunci master yang digunakan dalam hashsignature harus didekode menggunakan MIME RFC2045 karena dikodekan Base64. Jika Anda melihat masalah dengan otorisasi, lihat cara Mendiagnosis dan memecahkan masalah pengecualian yang tidak sah.

Membuat tanda tangan token yang di-hash untuk token master

Tanda tangan hash untuk token kunci master dapat dibangun dari parameter berikut: Verb, ResourceType, ResourceLink, dan Date.

  1. Kata Kerja mewakili kata kerja HTTP permintaan Anda. Nilai yang mungkin adalah: get, post, put, patch, delete

Catatan:: Nilai harus huruf kecil.

  1. Bagian ResourceType dari string mengidentifikasi jenis sumber daya yang diminta. Potensi nilai:
    • Operasi database: dbs
    • Operasi kontainer: colls
    • Prosedur Tersimpan: sprocs
    • Fungsi yang Ditentukan Pengguna: udfs
    • Memicu: triggers
    • Pengguna: users
    • Izin: permissions
    • Operasi tingkat item: docs

Catatan: Nilainya peka huruf besar/kecil dan harus huruf kecil.

  1. Bagian ResourceLink dari string adalah properti identitas sumber daya tempat permintaan diarahkan. Nilai ResourceLink bergantung pada operasi yang coba Anda jalankan. Setiap operasi akan memiliki ResourceLink yang sesuai dengan mengikuti konvensi ini:

    • Jika operasi dilakukan terhadap sumber daya tertentu, nilainya adalah tautan ke sumber daya tersebut. Contoh:

      • Untuk Penggunaan Get Database: dbs/{databaseId}
      • Untuk Dapatkan Penggunaan dokumen: dbs/{databaseId}/colls/{containerId}/docs/{docId}

    • Jika operasi dilakukan terhadap sekumpulan sumber daya (Daftar, Buat, Kueri) maka nilainya adalah tautan sumber daya induk. Contoh:

      • Untuk Buat Dokumen, gunakan: dbs/{databaseId}/colls/{containerId}
      • Untuk Membuat Prosedur Tersimpan, gunakan: dbs/{databaseId}/colls/{containerId}
      • Untuk Membuat Kontainer, gunakan: dbs/{databaseId}
      • Untuk Buat Penggunaan database: "" -> string kosong karena Database tidak memiliki sumber daya induk

Catatan: Nama sumber daya yang direferensikan sebagai bagian dari nilai ResourceLink peka huruf besar/kecil dan harus cocok dengan casing bagaimana mereka dideklarasikan dalam database. Komponen lainnya harus huruf kecil.

  1. Bagian Tanggal dari string adalah tanggal dan waktu UTC pesan dikirim (dalam format "TANGGAL HTTP" seperti yang ditentukan oleh Format Tanggal/Waktu RFC 7231), misalnya, "Tue, 01 Nov 1994 08:12:31 GMT".

    Dalam C#, itu dapat diperoleh dengan menggunakan penentu format "R" pada DateTime.UtcNow nilai .

    Tanggal yang sama ini (dalam format yang sama) juga perlu diteruskan sebagai x-ms-date header dalam permintaan.

Catatan: Nilainya peka huruf besar/kecil dan harus huruf kecil semua.

Untuk menghitung tanda tangan, kami menggunakan fungsi Kode Autentikasi Pesan berbasis Hash (HMAC) berbasis SHA256 dengan Kunci CosmosDB sebagai rahasia.

Payload untuk fungsi hashing didasarkan pada 4 komponen yang disajikan di atas menggunakan format berikut: "{verb}\n{resourceType}\n{resourceLink}\n{date}\n\n" (perhatikan baris baru tambahan di akhir payload).

Hasil fungsi yang dikodekan Base64 akan digunakan sebagai tanda tangan saat membuat header Otorisasi untuk panggilan.

Contoh [C#] untuk header Otorisasi yang valid:

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

Contoh metode [C#] untuk menghasilkan tanda tangan Otorisasi yang valid:

Untuk melihat sampel lengkap untuk Cosmos DB REST API, kunjungi repositori Sampel Cosmos DB REST API di GitHub

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

Contoh [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);  
}

Contoh Pengodean:

Argumen Nilai
Kata kerja GET
Jenis Sumber Daya "dbs"
Tautan Sumber Daya "dbs/ToDoList"
Tanggal Kam, 27 Apr 2017 00:51:12 GMT
Kunci dsZQi3KtZmCv1ljt3VNWNm7sQUF1y5rJfC6kv5Jiwv
W0EndXdDku/dkKBp8/ufDToSxLzR4y+O/0H/t4bQtVNw==
Jenis Kunci master
Versi Token 1,0
String Otorisasi Output type%3dmaster%26ver%3d1.0%26sig%3dc09PEVJr
gp2uQRkr934kFbTqhByc7TVr3OHyqlu%2bc%2bc%3d

Membuat tanda tangan hash untuk token sumber daya

Token sumber daya harus dihasilkan oleh server perantara. Server berfungsi sebagai wali kunci master dan menghasilkan token yang dibatasi waktu untuk klien yang tidak tepercaya, seperti browser web.

Server ini melakukan langkah-langkah berikut:

  1. Menangani permintaan klien masuk untuk token baru.

  2. Memverifikasi identitas klien dengan cara khusus aplikasi.

  3. Jika klien berhasil mengautentikasi, klien menggunakan antarmuka Cosmos DB (SDK atau REST) untuk menghasilkan token terbatas waktu baru dan mengembalikannya ke klien.

Lihat juga