Azure Cosmos DB'de verilere erişimin güvenliğini sağlamaSecure access to data in Azure Cosmos DB

Uygulama hedefı: SQL API

Bu makalede, Microsoft Azure Cosmos DBdepolanan verilere erişimin güvenliğini sağlamaya yönelik bir genel bakış sunulmaktadır.This article provides an overview of securing access to data stored in Microsoft Azure Cosmos DB.

Azure Cosmos DB, kullanıcıların kimliğini doğrulamak ve veri ve kaynaklarına erişim sağlamak için iki tür anahtar kullanır.Azure Cosmos DB uses two types of keys to authenticate users and provide access to its data and resources.

Anahtar türüKey type KaynaklarResources
Birincil anahtarlarPrimary keys Yönetim kaynakları için kullanılır: veritabanı hesapları, veritabanları, kullanıcılar ve izinlerUsed for administrative resources: database accounts, databases, users, and permissions
Kaynak belirteçleriResource tokens Uygulama kaynakları için kullanılır: kapsayıcılar, belgeler, ekler, saklı yordamlar, Tetikleyiciler ve UDF 'lerUsed for application resources: containers, documents, attachments, stored procedures, triggers, and UDFs

Birincil anahtarlarPrimary keys

Birincil anahtarlar, veritabanı hesabının tüm yönetim kaynaklarına erişim sağlar.Primary keys provide access to all the administrative resources for the database account. Her hesap iki birincil anahtardan oluşur: birincil anahtar ve ikincil anahtar.Each account consists of two primary keys: a primary key and secondary key. Çift anahtarların amacı, hesap ve verilerinize sürekli erişim sağlamak için, anahtarları yeniden oluşturmak veya almak için kullanılır.The purpose of dual keys is so that you can regenerate, or roll keys, providing continuous access to your account and data. Birincil anahtarlar hakkında daha fazla bilgi için bkz. veritabanı güvenlik makalesi.To learn more about primary keys, see the Database security article.

Anahtar döndürmeKey rotation

Birincil anahtarınızı döndürme işlemi basittir.The process of rotating your primary key is simple.

  1. İkincil anahtarınızı almak için Azure portal gidin.Navigate to the Azure portal to retrieve your secondary key.
  2. Birincil anahtarınızı uygulamanızdaki ikincil anahtarınızla değiştirin.Replace your primary key with your secondary key in your application. Tüm dağıtımlardaki tüm Cosmos DB istemcilerinin hemen yeniden başlatıldığından ve güncelleştirilmiş anahtarın kullanılmasına başlayadığınızdan emin olun.Make sure that all the Cosmos DB clients across all the deployments are promptly restarted and will start using the updated key.
  3. Azure portal birincil anahtarı döndürün.Rotate the primary key in the Azure portal.
  4. Yeni birincil anahtarın tüm kaynaklara karşı çalışıp çalışmadığını doğrulayın.Validate the new primary key works against all resource. Anahtar döndürme işlemi, Cosmos DB hesabının boyutuna bağlı olarak bir dakikadan daha kısa bir sürede bir zaman alabilir.Key rotation process can take anywhere from less than a minute to hours depending on the size of the Cosmos DB account.
  5. İkincil anahtarı yeni birincil anahtarla değiştirin.Replace the secondary key with the new primary key.

Azure portal-gösteren NoSQL veritabanı güvenliğine birincil anahtar döndürme

Birincil anahtar kullanmak için kod örneğiCode sample to use a primary key

Aşağıdaki kod örneği, bir DocumentClient örneği oluşturmak ve veritabanı oluşturmak için Cosmos DB hesap uç noktası ve birincil anahtarın nasıl kullanılacağını göstermektedir:The following code sample illustrates how to use a Cosmos DB account endpoint and primary key to instantiate a DocumentClient and create a database:

//Read the Azure Cosmos DB endpointUrl and authorization keys from config.
//These values are available from the Azure portal on the Azure Cosmos DB account blade under "Keys".
//Keep these values in a safe and secure location. Together they provide Administrative access to your Azure Cosmos DB account.

private static readonly string endpointUrl = ConfigurationManager.AppSettings["EndPointUrl"];
private static readonly string authorizationKey = ConfigurationManager.AppSettings["AuthorizationKey"];

CosmosClient client = new CosmosClient(endpointUrl, authorizationKey);

Aşağıdaki kod örneği, bir nesneyi başlatmak için Azure Cosmos DB hesap uç noktası ve birincil anahtarın nasıl kullanılacağını göstermektedir CosmosClient :The following code sample illustrates how to use the Azure Cosmos DB account endpoint and primary key to instantiate a CosmosClient object:

HOST = config.settings["host"]
MASTER_KEY = config.settings["master_key"]

DATABASE_ID = config.settings["database_id"]
CONTAINER_ID = config.settings["container_id"]
PARTITION_KEY = PartitionKey(path="/username")


# User that you want to give access to
USERNAME, USERNAME_2 = "user", "user2"

CONTAINER_ALL_PERMISSION = "CONTAINER_ALL_PERMISSION"
PARTITION_READ_PERMISSION = "PARTITION_READ_PERMISSION"
DOCUMENT_ALL_PERMISSION = "DOCUMENT_ALL_PERMISSION"


def create_user_if_not_exists(db, username):
    try:
        user = db.create_user(body={"id": username})
    except exceptions.CosmosResourceExistsError:
        user = db.get_user_client(username)

    return user


def create_permission_if_not_exists(user, permission_definition):
    try:
        permission = user.create_permission(permission_definition)
    except exceptions.CosmosResourceExistsError:
        permission = user.get_permission(permission_definition["id"])

    return permission


def token_client_upsert(container, username, item_id):
    try:
        container.upsert_item(
            {
                "id": item_id,
                "username": username,
                "msg": "This is a message for " + username,
            }
        )
    except exceptions.CosmosHttpResponseError:
        print("Error in upserting item with id '{0}'.".format(item_id))


def token_client_read_all(container):
    try:
        items = list(container.read_all_items())
        for i in items:
            print(i)
    except exceptions.CosmosResourceNotFoundError:
        print("Cannot read items--container '{0}' not found.".format(container.id))
    except exceptions.CosmosHttpResponseError:
        print("Error in reading items in container '{0}'.".format(container.id))


def token_client_read_item(container, username, item_id):
    try:
        item = container.read_item(item=item_id, partition_key=username)
        print(item)
    except exceptions.CosmosResourceNotFoundError:
        print("Cannot read--item with id '{0}' not found.".format(item_id))
    except exceptions.CosmosHttpResponseError:
        print("Error in reading item with id '{0}'.".format(item_id))


def token_client_delete(container, username, item_id):
    try:
        container.delete_item(item=item_id, partition_key=username)
    except exceptions.CosmosResourceNotFoundError:
        print("Cannot delete--item with id '{0}' not found.".format(item_id))
    except exceptions.CosmosHttpResponseError:
        print("Error in deleting item with id '{0}'.".format(item_id))


def token_client_query(container, username):
    try:
        for item in container.query_items(
            query="SELECT * FROM my_container c WHERE c.username=@username",
            parameters=[{"name": "@username", "value": username}],
            partition_key=username,
        ):
            print(json.dumps(item, indent=True))
    except exceptions.CosmosHttpResponseError:
        print("Error in querying item(s)")


def run_sample():
    client = cosmos_client.CosmosClient(HOST, {"masterKey": MASTER_KEY})

Kaynak belirteçleri Resource tokens

Kaynak belirteçleri, bir veritabanı içindeki uygulama kaynaklarına erişim sağlar.Resource tokens provide access to the application resources within a database. Kaynak belirteçleri:Resource tokens:

  • Belirli kapsayıcılara, Bölüm anahtarlarına, belgelere, eklere, saklı yordamlara, tetikleyicilere ve UDF erişimine erişim sağlar.Provide access to specific containers, partition keys, documents, attachments, stored procedures, triggers, and UDFs.
  • , Bir kullanıcıya belirli bir kaynağa izin verildiğinde oluşturulur.Are created when a user is granted permissions to a specific resource.
  • , Bir izin kaynağı GÖNDERI, al veya koy çağrısıyla üzerinde işlem yapıldığında yeniden oluşturulur.Are recreated when a permission resource is acted upon on by POST, GET, or PUT call.
  • Kullanıcı, kaynak ve izin için özel olarak oluşturulan bir karma kaynak belirteci kullanın.Use a hash resource token specifically constructed for the user, resource, and permission.
  • , Özelleştirilebilir bir geçerlilik süresi ile zaman bağlalardır.Are time bound with a customizable validity period. Varsayılan geçerli zaman aralığı bir saattir.The default valid time span is one hour. Ancak, belirteç ömrü, en fazla beş saate kadar açıkça belirtilebilir.Token lifetime, however, may be explicitly specified, up to a maximum of five hours.
  • Birincil anahtarı vermek için güvenli bir alternatif sağlayın.Provide a safe alternative to giving out the primary key.
  • İstemcilerin, izin verilen izinlere göre Cosmos DB hesabındaki kaynakları okumasını, yazmasını ve silmesini sağlar.Enable clients to read, write, and delete resources in the Cosmos DB account according to the permissions they've been granted.

Cosmos DB hesabınızdaki kaynaklara, birincil anahtarla güvenilmeyen bir istemciye erişim sağlamak istediğinizde, bir kaynak belirteci (Cosmos DB kullanıcılar ve izinler oluşturarak) kullanabilirsiniz.You can use a resource token (by creating Cosmos DB users and permissions) when you want to provide access to resources in your Cosmos DB account to a client that cannot be trusted with the primary key.

Cosmos DB kaynak belirteçleri, istemcilerin verdiğiniz izinlere göre Cosmos DB hesabınızdaki kaynakları okumasını, yazmasına ve silmesine olanak tanıyan güvenli bir alternatif sağlar ve birincil ya da salt okuma anahtarına gerek kalmadan.Cosmos DB resource tokens provide a safe alternative that enables clients to read, write, and delete resources in your Cosmos DB account according to the permissions you've granted, and without need for either a primary or read only key.

Kaynak belirteçlerinin istendiği, üretibildiği ve istemcilere teslim edileceği tipik bir tasarım deseninin olması aşağıda verilmiştir:Here is a typical design pattern whereby resource tokens may be requested, generated, and delivered to clients:

  1. Orta katman hizmeti, Kullanıcı fotoğraflarını paylaşmak üzere bir mobil uygulama sunacak şekilde ayarlanır.A mid-tier service is set up to serve a mobile application to share user photos.

  2. Orta katman hizmeti Cosmos DB hesabının birincil anahtarına sahiptir.The mid-tier service possesses the primary key of the Cosmos DB account.

  3. Fotoğraf uygulaması, Son Kullanıcı mobil cihazlarına yüklenir.The photo app is installed on end-user mobile devices.

  4. Oturum açıldığında, fotoğraf uygulaması, orta katman hizmeti ile kullanıcının kimliğini belirler.On login, the photo app establishes the identity of the user with the mid-tier service. Bu kimlik kurulumu mekanizması, uygulamaya tamamen sahiptir.This mechanism of identity establishment is purely up to the application.

  5. Kimlik kurulduktan sonra, orta katman hizmeti kimlik temelinde izinleri ister.Once the identity is established, the mid-tier service requests permissions based on the identity.

  6. Orta katman hizmeti, bir kaynak belirtecini telefon uygulamasına geri gönderir.The mid-tier service sends a resource token back to the phone app.

  7. Telefon uygulaması, kaynak belirteci tarafından tanımlanan izinlerle ve kaynak belirtecinin izin verdiği aralığa göre Cosmos DB kaynaklarına doğrudan erişmek için kaynak belirtecini kullanmaya devam edebilir.The phone app can continue to use the resource token to directly access Cosmos DB resources with the permissions defined by the resource token and for the interval allowed by the resource token.

  8. Kaynak belirtecinin süresi dolmuşsa, sonraki istekler 401 Yetkisiz bir özel durum alır.When the resource token expires, subsequent requests receive a 401 unauthorized exception. Bu noktada, telefon uygulaması kimliği yeniden oluşturur ve yeni bir kaynak belirteci ister.At this point, the phone app re-establishes the identity and requests a new resource token.

    Kaynak belirteçleri Azure Cosmos DB iş akışı

Kaynak belirteci oluşturma ve yönetimi, yerel Cosmos DB istemci kitaplıkları tarafından işlenir; Ancak REST kullanırsanız istek/kimlik doğrulama üst bilgilerini oluşturmanız gerekir.Resource token generation and management are handled by the native Cosmos DB client libraries; however, if you use REST you must construct the request/authentication headers. REST için kimlik doğrulama üstbilgileri oluşturma hakkında daha fazla bilgi için, bkz. Access Control Cosmos DB kaynakları veya .net SDK veya Node.js SDK'mız için kaynak kodu.For more information on creating authentication headers for REST, see Access Control on Cosmos DB Resources or the source code for our .NET SDK or Node.js SDK.

Kaynak belirteçleri oluşturmak için kullanılan bir orta katman hizmeti örneği için, bkz. Resourcetokenbroker uygulaması.For an example of a middle tier service used to generate or broker resource tokens, see the ResourceTokenBroker app.

KullanıcılarUsers

Azure Cosmos DB kullanıcılar bir Cosmos veritabanıyla ilişkilendirilir.Azure Cosmos DB users are associated with a Cosmos database. Her veritabanı sıfır veya daha fazla Kullanıcı Cosmos DB içerebilir.Each database can contain zero or more Cosmos DB users. Aşağıdaki kod örneği, .NET SDK v3 Azure Cosmos DBkullanarak Cosmos DB bir kullanıcının nasıl oluşturulacağını göstermektedir.The following code sample shows how to create a Cosmos DB user using the Azure Cosmos DB .NET SDK v3.

//Create a user.
Database database = benchmark.client.GetDatabase("SalesDatabase");

User user = await database.CreateUserAsync("User 1");

Not

Her Cosmos DB kullanıcının, kullanıcıyla ilişkili izin listesini almak için kullanılabilecek bir ReadAsync () yöntemi vardır.Each Cosmos DB user has a ReadAsync() method that can be used to retrieve the list of permissions associated with the user.

İzinlerPermissions

Bir izin kaynağı, bir kullanıcıyla ilişkilendirilir ve bölüm anahtarı düzeyi olarak kapsayıcıda atanır.A permission resource is associated with a user and assigned at the container as well as partition key level. Her Kullanıcı sıfır veya daha fazla izin içerebilir.Each user may contain zero or more permissions. Bir izin kaynağı, belirli bir bölüm anahtarındaki belirli bir kapsayıcıya veya verilere erişmeyi denerken kullanıcının ihtiyacı olan bir güvenlik belirtecine erişim sağlar.A permission resource provides access to a security token that the user needs when trying to access a specific container or data in a specific partition key. Bir izin kaynağı tarafından sağlanarak kullanılabilecek iki erişim düzeyi vardır:There are two available access levels that may be provided by a permission resource:

  • Tümü: kullanıcının kaynakta tam izni vardır.All: The user has full permission on the resource.
  • Okuma: Kullanıcı yalnızca kaynağın içeriğini okuyabilir, ancak kaynakta yazma, güncelleştirme veya silme işlemlerini gerçekleştiremez.Read: The user can only read the contents of the resource but cannot perform write, update, or delete operations on the resource.

Not

Saklı yordamları çalıştırmak için kullanıcının saklı yordamın çalıştırılacağı kapsayıcıda tüm izne sahip olması gerekir.In order to run stored procedures the user must have the All permission on the container in which the stored procedure will be run.

Veri düzlemi isteklerinde tanılama günlüklerinietkinleştirirseniz, izne karşılık gelen aşağıdaki iki özellik günlüğe kaydedilir:If you enable the diagnostic logs on data-plane requests, the following two properties corresponding to the permission are logged:

  • Resourcetokenpermissionıd -bu özellik belirttiğiniz kaynak belirteci izin kimliğini gösterir.resourceTokenPermissionId - This property indicates the resource token permission Id that you have specified.

  • Resourcetokenpermissionmode -bu özellik, kaynak belirtecini oluştururken ayarlamış olduğunuz izin modunu gösterir.resourceTokenPermissionMode - This property indicates the permission mode that you have set when creating the resource token. İzin modunun "All" veya "Read" gibi değerleri olabilir.The permission mode can have values such as "all" or "read".

İzin oluşturmak için kod örneğiCode sample to create permission

Aşağıdaki kod örneği, bir izin kaynağı oluşturmayı, izin kaynağının kaynak belirtecini okumayı ve izinleri yukarıda oluşturulan kullanıcıyla ilişkilendirmeyi gösterir.The following code sample shows how to create a permission resource, read the resource token of the permission resource, and associate the permissions with the user created above.

// Create a permission on a container and specific partition key value
Container container = client.GetContainer("SalesDatabase", "OrdersContainer");
user.CreatePermissionAsync(
    new PermissionProperties(
        id: "permissionUser1Orders",
        permissionMode: PermissionMode.All,
        container: benchmark.container,
        resourcePartitionKey: new PartitionKey("012345")));

Kullanıcı için okuma izni için kod örneğiCode sample to read permission for user

Aşağıdaki kod parçacığı, yukarıda oluşturulan kullanıcıyla ilişkili iznin nasıl alınacağını gösterir ve tek bir bölüm anahtarı kapsamındaki Kullanıcı adına yeni bir CosmosClient örneği oluşturur.The following code snippet shows how to retrieve the permission associated with the user created above and instantiate a new CosmosClient on behalf of the user, scoped to a single partition key.

//Read a permission, create user client session.
PermissionProperties permissionProperties = await user.GetPermission("permissionUser1Orders")

CosmosClient client = new CosmosClient(accountEndpoint: "MyEndpoint", authKeyOrResourceToken: permissionProperties.Token);

Kullanıcı ekleme ve rol atamaAdd users and assign roles

Kullanıcı hesabınıza Azure Cosmos DB hesap okuyucusu erişimi eklemek için bir abonelik sahibine Azure portal aşağıdaki adımları uygulayın.To add Azure Cosmos DB account reader access to your user account, have a subscription owner perform the following steps in the Azure portal.

  1. Azure portal açın ve Azure Cosmos DB hesabınızı seçin.Open the Azure portal, and select your Azure Cosmos DB account.
  2. Erişim denetimi (IAM) sekmesine tıklayın ve ardından + rol ataması Ekle' ye tıklayın.Click the Access control (IAM) tab, and then click + Add role assignment.
  3. Rol ataması Ekle bölmesinde, rol kutusunda Cosmos DB hesap okuyucu rolü' nü seçin.In the Add role assignment pane, in the Role box, select Cosmos DB Account Reader Role.
  4. Erişim ata kutusunda Azure AD Kullanıcı, Grup veya uygulama' yı seçin.In the Assign access to box, select Azure AD user, group, or application.
  5. Dizininizde erişim vermek istediğiniz kullanıcı, Grup veya uygulamayı seçin.Select the user, group, or application in your directory to which you wish to grant access. Dizinde görünen ad, e-posta adresi veya nesne tanımlayıcıları ile arama yapabilirsiniz.You can search the directory by display name, email address, or object identifiers. Seçilen Kullanıcı, Grup veya uygulama seçilen Üyeler listesinde görünür.The selected user, group, or application appears in the selected members list.
  6. Kaydet’e tıklayın.Click Save.

Varlık artık Azure Cosmos DB kaynaklarını okuyabilir.The entity can now read Azure Cosmos DB resources.

Kullanıcı verilerini silme veya dışarı aktarmaDelete or export user data

Bir veritabanı hizmeti olarak Azure Cosmos DB, veritabanınızda veya kapsayıcılarınızdaki verileri aramanıza, seçmenize, değiştirmenize ve silmenizi sağlar.As a database service, Azure Cosmos DB enables you to search, select, modify and delete any data located in your database or containers. Bununla birlikte, belirtilen API 'Leri kullanmak ve gerekirse kişisel verileri bulmak ve silmek için gereken mantığı tanımlamak sizin sorumluluğunuzdadır.It is however your responsibility to use the provided APIs and define logic required to find and erase any personal data if needed. Her bir çok modelli API (SQL, MongoDB, Gremlin, Cassandra, tablo), özel koşullara göre verileri aramak ve silmek için yöntemler içeren farklı dil SDK 'leri sağlar.Each multi-model API (SQL, MongoDB, Gremlin, Cassandra, Table) provides different language SDKs that contain methods to search and delete data based on custom predicates. Ayrıca, belirli bir süreden sonra verileri otomatik olarak silmek için yaşam süresi (TTL) özelliğini de etkinleştirebilirsiniz.You can also enable the time to live (TTL) feature to delete data automatically after a specified period, without incurring any additional cost.

Not

Kişisel verileri görüntüleme veya silme hakkında bilgi için bkz. GDPR için Azure Veri Nesnesi İstekleri.For information about viewing or deleting personal data, see Azure Data Subject Requests for the GDPR. GDPR hakkında daha fazla bilgi için bkz. Hizmet Güveni portalının GDPR bölümü.For more information about GDPR, see the GDPR section of the Service Trust portal.

Sonraki adımlarNext steps