Protezione dell'accesso ai dati in Azure Cosmos DBSecuring access to Azure Cosmos DB data

Questo articolo offre una panoramica della protezione dell'accesso ai dati archiviati in Microsoft Azure Cosmos DB.This article provides an overview of securing access to data stored in Microsoft Azure Cosmos DB.

Azure Cosmos DB usa due tipi di chiavi per autenticare gli utenti e fornire accesso ai dati e alle risorse.Azure Cosmos DB uses two types of keys to authenticate users and provide access to its data and resources.

Tipo di chiaveKey type RisorseResources
Chiavi masterMaster keys Usate per risorse amministrative, ovvero account di database, database, utenti e autorizzazioniUsed for administrative resources: database accounts, databases, users, and permissions
Token delle risorseResource tokens Usati per le risorse dell'applicazione, ovvero raccolte, documenti, allegati, stored procedure, trigger e funzioni definite dall'utenteUsed for application resources: collections, documents, attachments, stored procedures, triggers, and UDFs

Chiavi masterMaster keys

Le chiavi master consentono di accedere a tutte le risorse amministrative per l'account del database.Master keys provide access to the all the administrative resources for the database account. Chiavi master:Master keys:

  • Consentono di accedere ad account, database, utenti e autorizzazioni.Provide access to accounts, databases, users, and permissions.
  • Non possono essere usate per fornire l'accesso granulare a raccolte e documenti.Cannot be used to provide granular access to collections and documents.
  • Vengono create durante la creazione di un account.Are created during the creation of an account.
  • Possono essere rigenerate in qualsiasi momento.Can be regenerated at any time.

Ogni account è costituito da due chiavi master: una chiave primaria e una chiave secondaria.Each account consists of two Master keys: a primary key and secondary key. Lo scopo delle due chiavi è consentire la rigenerazione o la rotazione delle chiavi mantenendo l'accesso continuo ai dati e all'account.The purpose of dual keys is so that you can regenerate, or roll keys, providing continuous access to your account and data.

Oltre alle due chiavi master per l'account Cosmos DB, sono disponibili due chiavi di sola lettura.In addition to the two master keys for the Cosmos DB account, there are two read-only keys. Queste chiavi consentono solo operazioni di lettura per l'account.These read-only keys only allow read operations on the account. Le chiavi di sola lettura non forniscono l'accesso in lettura alle risorse di autorizzazione.Read-only keys do not provide access to read permissions resources.

Le chiavi master primaria, secondaria, di sola lettura e di lettura/scrittura possono essere recuperate e rigenerate nel portale di Azure.Primary, secondary, read only, and read-write master keys can be retrieved and regenerated using the Azure portal. Per istruzioni, vedere Visualizzare, copiare e rigenerare le chiavi di accesso.For instructions, see View, copy, and regenerate access keys.

Controllo di accesso (IAM) nel portale di Azure: dimostrazione della sicurezza del database NoSQL

Il processo di rotazione della chiave master è semplice.The process of rotating your master key is simple. Passare al portale di Azure per recuperare la chiave secondaria, quindi sostituire la chiave primaria con la chiave secondaria nell'applicazione e ruotare la chiave primaria nel portale di Azure.Navigate to the Azure portal to retrieve your secondary key, then replace your primary key with your secondary key in your application, then rotate the primary key in the Azure portal.

Rotazione delle chiavi master nel portale di Azure: dimostrazione della sicurezza del database NoSQL

Esempio di codice per l'uso di una chiave masterCode sample to use a master key

L'esempio di codice seguente illustra come usare un endpoint dell'account Cosmos DB e la chiave master per creare un'istanza di DocumentClient e un database.The following code sample illustrates how to use a Cosmos DB account endpoint and master 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".
//NB > Keep these values in a safe and secure location. Together they provide Administrative access to your DocDB account.

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

client = new DocumentClient(new Uri(endpointUrl), authorizationKey);

// Create Database
Database database = await client.CreateDatabaseAsync(
    new Database
    {
        Id = databaseName
    });

Token delle risorseResource tokens

I token delle risorse consentono di accedere alle risorse dell'applicazione all'interno di un database.Resource tokens provide access to the application resources within a database. Token delle risorse:Resource tokens:

  • Consentono di accedere a raccolte, chiavi di partizioni, documenti, allegati, stored procedure, trigger e funzioni definite dall'utente.Provide access to specific collections, partition keys, documents, attachments, stored procedures, triggers, and UDFs.
  • Vengono creati quando a un utente vengono concesse autorizzazioni per una risorsa specifica.Are created when a user is granted permissions to a specific resource.
  • Vengono ricreati quando si interviene su una risorsa di autorizzazione tramite chiamata POST, GET o PUT.Are recreated when a permission resource is acted upon on by POST, GET, or PUT call.
  • Usano un token di risorsa hash costruito specificamente per l'utente, la risorsa e l'autorizzazione.Use a hash resource token specifically constructed for the user, resource, and permission.
  • Hanno un limite di tempo con un periodo di validità personalizzabile.Are time bound with a customizable validity period. L'intervallo di tempo valido predefinito è un'ora.The default valid timespan is one hour. La durata del token può essere tuttavia specificata in modo esplicito, fino a un massimo di cinque ore.Token lifetime, however, may be explicitly specified, up to a maximum of five hours.
  • Rappresentano un'alternativa sicura alla divulgazione della chiave master.Provide a safe alternative to giving out the master key.
  • Consentono ai client di leggere, scrivere ed eliminare risorse nell'account Cosmos DB in base alle autorizzazioni concesse.Enable clients to read, write, and delete resources in the Cosmos DB account according to the permissions they've been granted.

È possibile usare un token delle risorse (creando utenti e autorizzazioni di Cosmos DB) quando si vuole fornire l'accesso alle risorse dell'account Cosmos DB a un client non attendibile con la chiave master.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 master key.

I token delle risorse di Cosmos DB costituiscono un'alternativa sicura che consente ai client di leggere, scrivere ed eliminare risorse nell'account Cosmos DB sulla base delle autorizzazioni concesse e senza richiedere la chiave master o di sola lettura.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 master or read only key.

Di seguito è riportato un tipico schema progettuale in cui i token delle risorse possono essere richiesti, generati e forniti ai client:Here is a typical design pattern whereby resource tokens may be requested, generated, and delivered to clients:

  1. Un servizio di livello intermedio viene configurato per gestire un'applicazione per dispositivi mobili per condividere le foto dell'utente.A mid-tier service is set up to serve a mobile application to share user photos.
  2. Il servizio di livello intermedio ha la chiave master dell'account Cosmos DB.The mid-tier service possesses the master key of the Cosmos DB account.
  3. L'app per le foto viene installata nei dispositivi mobili dell'utente finale.The photo app is installed on end-user mobile devices.
  4. All'accesso, l'app per le foto stabilisce l'identità dell'utente con il servizio di livello intermedio.On login, the photo app establishes the identity of the user with the mid-tier service. Questo meccanismo per stabilire l'identità dipende completamente dall'applicazione.This mechanism of identity establishment is purely up to the application.
  5. Una volta stabilita l'identità, il servizio di livello intermedio richiede le autorizzazioni in base all'identità.Once the identity is established, the mid-tier service requests permissions based on the identity.
  6. Il servizio di livello intermedio invia di nuovo un token delle risorse all'app per il telefono.The mid-tier service sends a resource token back to the phone app.
  7. L'app per il telefono può continuare a usare il token delle risorse per accedere direttamente alle risorse di Cosmos DB con le autorizzazioni definite dal token delle risorse e per l'intervallo consentito dal token delle risorse.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. Quando il token delle risorse scade, le richieste successive ricevono un'eccezione 401 Non autorizzato.When the resource token expires, subsequent requests receive a 401 unauthorized exception. A questo punto, l'app per il telefono ristabilisce l'identità e richiede un nuovo token delle risorse.At this point, the phone app re-establishes the identity and requests a new resource token.

    Flusso di lavoro dei token delle risorse di Azure Cosmos DB

La generazione e la gestione dei token delle risorse vengono gestite dalle librerie client di Cosmos DB native. Se tuttavia si usa REST, è necessario creare le intestazioni di richiesta/autenticazione.Resource token generation and management is handled by the native Cosmos DB client libraries; however, if you use REST you must construct the request/authentication headers. Per altre informazioni sulla creazione di intestazioni di autenticazione per REST, vedere Access Control on Cosmos DB Resources (Controllo di accesso per le risorse di Cosmos DB) oppure il codice sorgente per gli SDK.For more information on creating authentication headers for REST, see Access Control on Cosmos DB Resources or the source code for our SDKs.

Per un esempio di servizio di livello intermedio usato per generare o negoziare i token delle risorse, vedere l'app ResourceTokenBroker.For an example of a middle tier service used to generate or broker resource tokens, see the ResourceTokenBroker app.

UtentiUsers

Gli utenti di Cosmos DB sono associati a un database Cosmos DB.Cosmos DB users are associated with a Cosmos DB database. Ogni database può contenere zero o più utenti di Cosmos DB.Each database can contain zero or more Cosmos DB users. L'esempio di codice seguente illustra come creare una risorsa utente di Cosmos DB.The following code sample shows how to create a Cosmos DB user resource.

//Create a user.
User docUser = new User
{
    Id = "mobileuser"
};

docUser = await client.CreateUserAsync(UriFactory.CreateDatabaseUri("db"), docUser);

Nota

Ogni utente di Cosmos DB ha una proprietà PermissionsLink che può essere usata per recuperare l'elenco di autorizzazioni associate all'utente.Each Cosmos DB user has a PermissionsLink property that can be used to retrieve the list of permissions associated with the user.

autorizzazioniPermissions

Una risorsa autorizzazione di Cosmos DB è associata a un utente di Cosmos DB.A Cosmos DB permission resource is associated with a Cosmos DB user. Ogni utente può contenere zero o più autorizzazioni di Cosmos DB.Each user may contain zero or more Cosmos DB permissions. Una risorsa autorizzazione fornisce l'accesso a un token di sicurezza di cui l'utente ha bisogno quando deve accedere a una risorsa applicazione specifica.A permission resource provides access to a security token that the user needs when trying to access a specific application resource. Sono disponibili due livelli di accesso che possono essere forniti da una risorsa di autorizzazione:There are two available access levels that may be provided by a permission resource:

  • Tutto: l'utente ha l'autorizzazione completa per la risorsa.All: The user has full permission on the resource.
  • Lettura: l'utente può solo leggere i contenuti della risorsa, ma non può eseguire operazioni di scrittura, aggiornamento o eliminazione sulla risorsa.Read: The user can only read the contents of the resource but cannot perform write, update, or delete operations on the resource.

Nota

Per eseguire le stored procedure di Cosmos DB, l'utente deve avere l'autorizzazione All per la raccolta in cui verrà eseguita la stored procedure.In order to run Cosmos DB stored procedures the user must have the All permission on the collection in which the stored procedure will be run.

Esempio di codice per la creazione dell'autorizzazioneCode sample to create permission

L'esempio di codice seguente illustra come creare una risorsa di autorizzazione, leggere il token delle risorse della risorsa di autorizzazione e associare le autorizzazioni all'utente creato in precedenza.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.
Permission docPermission = new Permission
{
    PermissionMode = PermissionMode.Read,
    ResourceLink = documentCollection.SelfLink,
    Id = "readperm"
};

docPermission = await client.CreatePermissionAsync(UriFactory.CreateUserUri("db", "user"), docPermission);
Console.WriteLine(docPermission.Id + " has token of: " + docPermission.Token);

Se è stato specificata una chiave di partizione per la raccolta, l'autorizzazione per le risorse di raccolta, documenti e allegati deve includere anche ResourcePartitionKey oltre a ResourceLink.If you have specified a partition key for your collection, then the permission for collection, document, and attachment resources must also include the ResourcePartitionKey in addition to the ResourceLink.

Codice di esempio per la lettura di autorizzazioni dell'utenteCode sample to read permissions for user

Per ottenere facilmente tutte le risorse autorizzazione associate a un particolare utente, Cosmos DB rende disponibile un feed di autorizzazioni per ogni oggetto utente.To easily obtain all permission resources associated with a particular user, Cosmos DB makes available a permission feed for each user object. Il frammento di codice seguente illustra come recuperare l'autorizzazione associata all'utente creato in precedenza, costruire un elenco di autorizzazioni e creare un'istanza di un nuovo DocumentClient per conto dell'utente.The following code snippet shows how to retrieve the permission associated with the user created above, construct a permission list, and instantiate a new DocumentClient on behalf of the user.

//Read a permission feed.
FeedResponse<Permission> permFeed = await client.ReadPermissionFeedAsync(
  UriFactory.CreateUserUri("db", "myUser"));
 List<Permission> permList = new List<Permission>();

foreach (Permission perm in permFeed)
{
    permList.Add(perm);
}

DocumentClient userClient = new DocumentClient(new Uri(endpointUrl), permList);

Passaggi successiviNext steps