Azure Cosmos DB SQL API 'sindeki erişim denetimiAccess control in the Azure Cosmos DB SQL API

Azure Cosmos DB birden çok API desteği olan global olarak dağıtılmış, çok modelli bir veritabanıdır.Azure Cosmos DB is a globally distributed multi-model database with support for multiple APIs. Bu makale Azure Cosmos DB için SQL API’sini kapsar.This article covers the SQL API for Azure Cosmos DB. SQL API’sinde kaynaklara erişim bir ana anahtar belirteci veya kaynak belirteciyle yönetilir.Access to resources in the SQL API is governed by a master key token or a resource token. Kaynağa erişmek için, seçilen belirteç kimlik doğrulama dizesinin bir parçası olarak REST kimlik doğrulama üst bilgisine eklenir.To access a resource, the selected token is included in the REST authorization header, as part of the authorization string.

Ana anahtar belirteçleriMaster key tokens

Ana anahtar belirteci, kullanıcıların belirli bir hesapta Cosmos DB kaynak üzerinde tam denetime sahip olmasını sağlayan tüm erişim anahtarı belirteçtir.The master key token is the all access key token that allows users to have full control of Cosmos DB resources in a particular account. Ana anahtar, bir hesabın oluşturulması sırasında oluşturulur.The master key is created during the creation of an account. Birincil anahtar ve ikincil anahtar olmak üzere iki ana anahtar kümesi vardır.There are two sets of master keys, the primary key and the secondary key. Hesabın Yöneticisi daha sonra ikincil anahtarı kullanarak anahtar dönüşü uygulayabilir.The administrator of the account can then exercise key rotation using the secondary key. Ayrıca Hesap Yöneticisi, gerektiğinde anahtarları da yeniden oluşturabilir.In addition, the account administrator can also regenerate the keys as needed. Anahtar oluşturma ve yuvarlama hakkında yönergeler için bkz. Azure Cosmos DB verilere güvenli erişim.For instructions on regenerating and rolling keys, see Secure access to data in Azure Cosmos DB.

Kaynak belirteçleriResource tokens

Kaynak belirteçleri, bir veritabanındaki kullanıcılar, izin kaynağı olarak da bilinen bir kaynakta kesin erişim denetimi için erişim izinleriyle ayarlandığında oluşturulur.Resource tokens are created when users in a database are set up with access permissions for precise access control on a resource, also known as a permission resource. Bir izin kaynağı, bir kullanıcının erişimi olan kaynak yolu ve erişim türüyle ilgili bilgilerle oluşturulmuş bir karma kaynak belirteci içerir.A permission resource contains a hash resource token constructed with the information regarding the resource path and access type a user has access to. İzin kaynak belirtecinin zaman sınırı ve geçerlilik süresi geçersiz kılınabilir.The permission resource token is time bound and the validity period can be overridden. Bir izin kaynağı (POST, al, PUT) üzerinde işlem yapıldığında, yeni bir kaynak belirteci oluşturulur.When a permission resource is acted upon on (POST, GET, PUT), a new resource token is generated. İzinler ve kaynak belirteçleri hakkında daha fazla bilgi için, Cosmos DB izinlerle Ilgili işlemlerbölümüne bakın.For information on permissions and resource tokens, see Operations on Cosmos DB Permissions.

Yetkilendirme üst bilgisiAuthorization header

Bir ana anahtar belirteci veya kaynak belirteci kullandığınız tüm REST işlemleri, bir kaynakla etkileşim kurmak için yetkilendirme dizesiyle yetkilendirme üst bilgisini içermelidir.All REST operations, whether you're using a master key token or resource token, must include the authorization header with the authorization string in order to interact with a resource. Yetkilendirme dizesi aşağıdaki biçimdedir:The authorization string has the following format:

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

Bir yetkilendirme dizesi şu örneğe benzer şekilde görünür:An authorization string looks like this example:

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

Köşeli ayraçlar içine alınmış parçalar şunlardır:The parts enclosed in brackets are as follows:

  • {typeoftoken} belirtecin türünü belirtir: Ana veya kaynak.{typeoftoken} denotes the type of token: master or resource.

  • {tokenversion}, belirtecin sürümünü gösterir, şu anda 1,0.{tokenversion} denotes the version of the token, currently 1.0.

  • {hashsignature} karma belirteç imzasını gösterir.{hashsignature} denotes the hashed token signature.

Yetkilendirme dizesi, geçersiz karakter içermediğinden emin olmak için REST isteğine eklenmeden önce kodlanmalıdır.The authorization string should be encoded before adding it to the REST request to ensure that it contains no invalid characters. MIME RFC2045 kullanarak Base64 kodlamalı olduğundan emin olun.Ensure that it's Base64 encoded using MIME RFC2045. Ayrıca, bu, Base64 kodlamalı olduğundan, diyez imzasında kullanılan ana anahtarın kodu, MIME RFC2045 kullanılarak çözülebilir.Also, the master key used in the hashsignature should be decoded using MIME RFC2045 as it's Base64 encoded. Yetkilendirmeyle ilgili herhangi bir sorun görürseniz, bkz . yetkisiz özel durumları tanılama ve giderme.If you see any issues with authorization, see how to Diagnose and troubleshoot unauthorized exceptions.

Ana belirteç için karma belirteç imzasını oluşturmaConstructing the hashed token signature for a master token

Ana anahtar belirtecinin karma imzası şu parametrelerden oluşturulabilir: fiil, ResourceType, ResourceLink ve Tarih.The hash signature for the master key token can be constructed from the following parameters: Verb, ResourceType, ResourceLink, and Date.

Ana anahtar belirtecinin karma imzasını oluştururken şunları göz önünde bulundurun:When constructing the hash signature for the master key token, keep these things in mind:

  1. Dizenin fiil kısmı Get, post veya put gibi http fiiline sahiptir.The Verb portion of the string is the HTTP verb, such as GET, POST, or PUT.

  2. Dizenin ResourceType bölümü, isteğin için olduğu kaynak türünü tanımlar, örn.The ResourceType portion of the string identifies the type of resource that the request is for, Eg. "DBS", "colls", "Docs"."dbs", "colls", "docs".

  3. Dizenin ResourceLink bölümü, isteğin yönlendirildiği kaynağın Identity özelliğidir.The ResourceLink portion of the string is the identity property of the resource that the request is directed at. ResourceLink kaynağın kimliği için durumunu korumalıdır.ResourceLink must maintain its case for the ID of the resource. Örnek, bir koleksiyon için şöyle görünür: "DBS/MyDatabase/colls/MyCollection".Example, for a collection it looks like: "dbs/MyDatabase/colls/MyCollection".

  4. Dizenin Tarih kısmı ILETININ gönderildiği UTC tarihi ve saati (örneğin, RFC 7231 tarih/saat biçimleritarafından tanımlanan "http-Date" biçiminde), örneğin, Tue, 01 Nov 1994 08:12:31 GMT .The Date portion of the string is the UTC date and time the message was sent (in "HTTP-date" format as defined by RFC 7231 Date/Time Formats), for example, Tue, 01 Nov 1994 08:12:31 GMT. C# dilinde, DateTime. UtcNow değeri üzerinde "R" Biçim belirleyicisi kullanılarak elde edilebilir.In C#, it can be obtained by using the "R" format specifier on the DateTime.UtcNow value. Bu aynı tarih (aynı biçimde), istekte Ayrıca x-MS-Date üst bilgisi olarak geçirilmesi gerekir.This same date(in same format) also needs to be passed as x-ms-date header in the request.

  5. Son boş dize ("") dahil olmak üzere imza dizesi içinde gösterilen tüm yeni satır karakterleri (\n) gereklidir.All new line characters (\n) shown are required within the signature string including the last empty string("").

Cosmos DB bir isteğin imza dizesini kodlamak için aşağıdaki biçimi kullanın:To encode the signature string for a request against Cosmos DB, use the following format:

StringToSign = fiil. Toküçük () + "\n" + ResourceType. Toharfler () + "\n" + ResourceLink + "\n" + Date. Toharfler () + "\n" + "" + "\n";StringToSign = Verb.toLowerCase() + "\n" + ResourceType.toLowerCase() + "\n" + ResourceLink + "\n" + Date.toLowerCase() + "\n" + "" + "\n";

Örnek [C#] geçerli bir yetkilendirme üst bilgisi oluşturmak için yöntemi:Example [C#] method to generate a valid Authorization header:

Bu yöntemin nasıl kullanılacağına ilişkin örnekler ve her bir işlem türü için her bir parametre için hangi değerlerin geçirilmesi gerektiği hakkındaFor examples on how to use this method, and what values should be passed for each parameter for each type of operation, refer to
Bir .NET istemcisinden REST kullanmaUsing REST from a .NET client

  
string GenerateAuthToken(string verb, string resourceType, string resourceId, string date, string key, string keyType, string tokenVersion)  
{  
    var hmacSha256 = new System.Security.Cryptography.HMACSHA256 { Key = Convert.FromBase64String(key) };  
    
    verb = verb ?? "";  
    resourceType = resourceType ?? "";
    resourceId = resourceId ?? "";
  
    string payLoad = string.Format(System.Globalization.CultureInfo.InvariantCulture, "{0}\n{1}\n{2}\n{3}\n{4}\n",  
            verb.ToLowerInvariant(),  
            resourceType.ToLowerInvariant(),  
            resourceId,  
            date.ToLowerInvariant(),  
            ""  
    );  
  
    byte[] hashPayLoad = hmacSha256.ComputeHash(System.Text.Encoding.UTF8.GetBytes(payLoad));  
    string signature = Convert.ToBase64String(hashPayLoad);  
  
    return System.Web.HttpUtility.UrlEncode(String.Format(System.Globalization.CultureInfo.InvariantCulture, "type={0}&ver={1}&sig={2}",  
        keyType,  
        tokenVersion,  
        signature));  
}  
  

Örnek [Node.js]: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);  
}  
  

Örnek kodlama:Example Encoding:

Bağımsız DeğişkenArgument DeğerValue
FiilVerb GETGET
Kaynak TürüResource Type veritabanları"dbs"
Kaynak bağlantısıResource Link "DBS/ToDoList""dbs/ToDoList"
TarihDate Per, 27 Nis 2017 00:51:12 GMTThu, 27 Apr 2017 00:51:12 GMT
AnahtarKey dsZQi3KtZmCv1ljt3VNWNm7sQUF1y5rJfC6kv5JiwvdsZQi3KtZmCv1ljt3VNWNm7sQUF1y5rJfC6kv5Jiwv
W0EndXdDku/dkKBp8/ufDToSxLzR4y + O/0H/t4bQtVNw = =W0EndXdDku/dkKBp8/ufDToSxLzR4y+O/0H/t4bQtVNw==
Anahtar türüKey Type anamaster
Belirteç sürümüToken Version 1,01.0
Çıkış yetkilendirme dizesiOutput Authorization String tür% 3dmaster% 26ver% 3B 1.0% 26sıg% 3dc09PEVJrtype%3dmaster%26ver%3d1.0%26sig%3dc09PEVJr
gp2uQRkr934kFbTqhByc7TVr3OHyqlu% 2BC% 2BC% 3Bgp2uQRkr934kFbTqhByc7TVr3OHyqlu%2bc%2bc%3d

Kaynak belirteci için karma imza oluşturmaConstructing the hash signature for a resource token

Kaynak belirteçlerinin bir ara sunucu tarafından oluşturulması gerekir.Resource tokens must be generated by an intermediate server. Sunucu, ana anahtar koruyucu görevi görür ve Web tarayıcıları gibi güvenilmeyen istemciler için zaman kısıtlı belirteçler oluşturur.The server serves as the master-key guardian and generates time-constrained tokens for untrusted clients, such as web browsers.

Bu sunucu aşağıdaki adımları gerçekleştirir:This server performs the following steps:

  1. Yeni belirteçler için gelen istemci isteklerini işler.Handles incoming client requests for new tokens.

  2. İstemci kimliğini uygulamaya özgü bir şekilde doğrular.Verifies client identity in an application-specific way.

  3. İstemci başarıyla kimlik doğrulaması gerçekleştiriyorsa, yeni zamana sınırlı bir belirteç oluşturmak ve istemciye geri döndürmek için Cosmos DB arabirimlerini (SDK veya REST) kullanır.If the client authenticates successfully, it uses the Cosmos DB interfaces (SDK or REST) to generate a new time-limited token and returns it to the client.

Ayrıca Bkz.See Also