Azure Cosmos DB SQL API'sinde erişim denetimi

  • Makale

Azure Cosmos DB, modern uygulama geliştirme için tam olarak yönetilen bir NoSQL veritabanı hizmetidir. Bu makale Azure Cosmos DB için SQL API’sini kapsar. SQL API’sinde kaynaklara erişim bir ana anahtar belirteci veya kaynak belirteciyle yönetilir. Kaynağa erişmek için, seçilen belirteç kimlik doğrulama dizesinin bir parçası olarak REST kimlik doğrulama üst bilgisine eklenir.

Ana anahtar belirteçleri

Ana anahtar belirteci, kullanıcıların belirli bir hesaptaki Cosmos DB kaynakları için tam denetime sahip olmasını sağlayan tüm erişim anahtarı belirtecidir. Ana anahtar, hesap oluşturulurken oluşturulur. İki ana anahtar kümesi vardır: birincil anahtar ve ikincil anahtar. Hesabın yöneticisi daha sonra ikincil anahtarı kullanarak anahtar döndürme alıştırması yapabilir. Buna ek olarak, hesap yöneticisi gerektiğinde anahtarları yeniden oluşturabilir. Anahtarları yeniden oluşturma ve döndürme yönergeleri için bkz. Azure Cosmos DB'de verilere güvenli erişim.

Kaynak belirteçleri

Bir veritabanındaki kullanıcılar, izin kaynağı olarak da bilinen bir kaynakta hassas erişim denetimi için erişim izinleri ile ayarlandığında kaynak belirteçleri oluşturulur. İzin kaynağı, bir kullanıcının erişimi olan kaynak yolu ve erişim türüyle ilgili bilgilerle birlikte bir karma kaynak belirteci içerir. İzin kaynak belirteci zamana bağlıdır ve geçerlilik süresi geçersiz kılınabilir. üzerinde bir izin kaynağı üzerinde işlem yapıldığında (POST, GET, PUT), yeni bir kaynak belirteci oluşturulur. İzinler ve kaynak belirteçleri hakkında bilgi için bkz. Cosmos DB İzinlerinde İşlemler.

Yetkilendirme üst bilgisi

İster ana anahtar belirteci ister kaynak belirteci kullanıyor olun tüm REST işlemleri, bir kaynakla etkileşim kurmak için yetkilendirme dizesiyle birlikte yetkilendirme üst bilgisini içermelidir. Yetkilendirme dizesi aşağıdaki biçime sahiptir:

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

Yetkilendirme dizesi şu örneğe benzer:

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

Köşeli ayraç içine alınmış parçalar aşağıdaki gibidir:

  • {typeoftoken} belirtecin türünü belirtir: ana, kaynak veya aad ( Azure Cosmos DB RBAC kullanıyorsanız).

  • {tokenversion}, belirtecin şu anda 1.0 olan sürümünü belirtir.

  • Azure Cosmos DB RBAC kullanıyorsanız {hashsignature}, karma belirteç imzasını veya oauth belirtecini belirtir.

Yetkilendirme dizesi, geçersiz karakter içermediğinden emin olmak için REST isteğine eklenmeden önce kodlanmalıdır. MIME RFC2045 kullanılarak Kodlanmış Base64 olduğundan emin olun. Ayrıca, hashsignature içinde kullanılan ana anahtarın, Base64 kodlanmış olduğu için MIME RFC2045 kullanılarak kodu çözülmelidir. Yetkilendirmeyle ilgili herhangi bir sorun görürseniz yetkisiz özel durumları tanılama ve giderme konusuna bakın.

Ana belirteç için karma belirteç imzasını oluşturma

Ana anahtar belirtecinin karma imzası şu parametrelerden oluşturulabilir: Fiil, ResourceType, ResourceLink ve Date.

  1. Fiil, isteğinizin HTTP fiilini temsil eder. Olası değerler şunlardır: get, post, put, patch, delete

Not:: Değerler küçük harfle yazılmalıdır.

  1. Dizenin ResourceType bölümü, isteğin hedeflediği kaynak türünü tanımlar. Olası değerler şunlardır:
    • Veritabanı işlemleri: dbs
    • Kapsayıcı işlemleri: colls
    • Saklı Yordamlar: sprocs
    • Kullanıcı Tanımlı İşlevler: udfs
    • Tetikleyiciler: triggers
    • Kullanıcı: users
    • Izin: permissions
    • Öğe düzeyi işlemleri: docs

Not: Değerler büyük/küçük harfe duyarlıdır ve küçük harfle yazılmalıdır.

  1. Dizenin ResourceLink bölümü, isteğin yönlendirildiğini kaynağın kimlik özelliğidir. ResourceLink değeri, yürütmeye çalıştığınız işleme bağlıdır. Bu kuralı izleyerek her işlemin kendi ResourceLink'i olacaktır:

    • İşlem belirli bir kaynakta gerçekleştiriliyorsa, değer bu kaynağın bağlantısıdır. Örnekler:

      • Get Database kullanımı için: dbs/{databaseId}
      • Belge Al için kullanın: dbs/{databaseId}/colls/{containerId}/docs/{docId}

    • İşlem bir kaynak kümesine (Liste, Oluştur, Sorgu) karşı gerçekleştiriliyorsa, değer üst kaynağın bağlantısıdır. Örnekler:

      • Belge Oluştur'u kullanmak için: dbs/{databaseId}/colls/{containerId}
      • Saklı Yordam Oluştur için kullanın: dbs/{databaseId}/colls/{containerId}
      • Kapsayıcı Oluşturma için kullanın: dbs/{databaseId}
      • Veritabanı Oluştur için: "" -> Veritabanları üst kaynağa sahip olmadığından boş bir dize

Not: ResourceLink değerinin bir parçası olarak başvuruda bulunan kaynak adları büyük/küçük harfe duyarlıdır ve bunların veritabanında nasıl bildirildiğiyle eşleşmelidir. Diğer bileşenler küçük harf olmalıdır.

  1. Dizenin Tarih bölümü, iletinin gönderildiği UTC tarih ve saatidir ( RFC 7231 Tarih/Saat Biçimleri tarafından tanımlanan "HTTP-tarih" biçimindedir), örneğin, "Sal, 01 Kas 1994 08:12:31 GMT".

    C# dilinde, değerdeki "R" biçim belirticisi DateTime.UtcNow kullanılarak elde edilebilir.

    Aynı tarihin (aynı biçimde) istekte üst bilgi olarak x-ms-date geçirilmesi de gerekir.

Not: Değer büyük/küçük harfe duyarlıdır ve tümü küçük harf olmalıdır.

İmzayı hesaplamak için SHA256 tabanlı Karma Tabanlı İleti Kimlik Doğrulama Kodu (HMAC) işlevini, gizli dizi olarak CosmosDB Anahtarı ile birlikte kullanırız.

Karma işlevi için yük, yukarıda aşağıdaki biçim kullanılarak sunulan 4 bileşeni temel alır: "{verb}\n{resourceType}\n{resourceLink}\n{date}\n\n" (yükün sonundaki ek yeni satırı not edin).

İşlevin Base64 kodlanmış sonucu, çağrı için Yetkilendirme üst bilgisi oluştururken imza olarak kullanılır.

Geçerli bir Yetkilendirme üst bilgisi için [C#] örneği:

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

Geçerli bir Yetkilendirme imzası oluşturmak için örnek [C#] yöntemi:

Cosmos DB REST API'sine yönelik tüm örnekleri görmek için GitHub'da Cosmos DB REST API Örnekleri deposunu ziyaret edin

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

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

Örnek Kodlama:

Bağımsız Değişken Değer
Fiil GET
Kaynak Türü "dbs"
Kaynak Bağlantısı "dbs/ToDoList"
Tarih Per, 27 Nisan 2017 00:51:12 GMT
Anahtar dsZQi3KtZmCv1ljt3VNWNm7sQUF1y5rJfC6kv5Jiwv
W0EndXdDku/dkKBp8/ufDToSxLzR4y+O/0H/t4bQtVNw==
Anahtar Türü ana
Belirteç Sürümü 1.0
Çıktı Yetkilendirme Dizesi type%3dmaster%26ver%3d1.0%26sig%3dc09PEVJr
gp2uQRkr934kFbTqhByc7TVr3OHyqlu%2bc%2bc%3d

Kaynak belirteci için karma imza oluşturma

Kaynak belirteçleri bir ara sunucu tarafından oluşturulmalıdır. Sunucu ana anahtar koruyucusu görevi görür ve web tarayıcıları gibi güvenilmeyen istemciler için zaman kısıtlanmış belirteçler oluşturur.

Bu sunucu aşağıdaki adımları gerçekleştirir:

  1. Yeni belirteçler için gelen istemci isteklerini işler.

  2. İstemci kimliğini uygulamaya özgü bir şekilde doğrular.

  3. İstemci başarıyla kimlik doğrulaması yaparsa, cosmos DB arabirimlerini (SDK veya REST) kullanarak yeni bir sınırlı zaman belirteci oluşturur ve istemciye döndürür.

Ayrıca Bkz.