Integrar o Azure Key Vault com a criptografia em nível de campo no lado do cliente do MongoDB

Adrienne Tacke9 min read • Published Aug 27, 2021 • Updated May 24, 2022

Azure MongoDB Segurança C#

Avalie esse Tutorial

Ao implementar a criptografia em nível de campodo MongoDBno lado do cliente (CSFLE), você se verá fazendo uma decisão importante: onde armazeno minha chave mestra do cliente? Em outro tutorial, oriento os leitores sobre os fundamentos do CSFLE usando uma chave mestra gerada e armazenada localmente. Embora isso funcione para fins informativos e de desenvolvimento local, não é adequado para produção! Neste tutorial, vamos ver como usar o Azure Key Vault para gerar e armazenar com segurança nossa chave mestra.

Pré-requisitos

Um cluster do MongoDB Atlas executando o MongoDB 4.2 (ou posterior) OU MongoDB 4.2 Enterprise Server (ou posterior) — necessário para criptografia automática
Driver MongoDB .NET 2.13.0 (ou posterior)
mongocryptd
Uma Conta Azure com uma assinatura ativa e as mesmas permissões que as encontradas em qualquer uma dessas roles do Azure AD (somente uma é necessária):
Um locatário do Azure AD (você pode usar um existente, supondo que tenha as permissões apropriadas)
Azure CLI
Aplicativo de amostra clonado

Salto rápido

Prepare a infraestrutura do Azure

Registrar aplicativo no Azure Active Directory
Crie um segredo do cliente
Criar um Azure Key Vault
Criar e adicionar uma chave ao seu Key Vault
Conceder permissões de aplicativo para o Key Vault

Configure seu aplicativo cliente para usar o Azure Key Vault e o CSFLE

Integrar o Azure Key Vault ao seu aplicativo cliente
Os resultados - O que você obtém após integrar o Azure Key Vault com o MongoDB CSFLE

Registrar aplicativo no Azure Active Directory

Para estabelecer uma relação de confiança entre nosso aplicativo e a plataforma de identidade da Microsoft, primeiro precisamos registrá-lo.

Inicie sessão no portal do Azure.
Se você tiver acesso a vários inquilinos, no menu superior, use o “Directory + subscription filter” para selecionar o inquilino no qual você deseja registrar um aplicativo.
Na barra de pesquisa principal, pesquise e selecione “Azure Active Directory.”
No menu de navegação à esquerda, encontre a seção Gerenciar e selecione "App registrations," e depois "+ New registration."
Insira um nome de exibição para seu aplicativo. Você pode alterar o nome de exibição a qualquer momento e vários registros de aplicativos podem compartilhar o mesmo nome. O ID do aplicativo (cliente) gerado automaticamente pelo registro do aplicativo, não seu nome de exibição, identifica seu aplicativo de forma exclusiva na plataforma de identidade.
Especifique quem pode usar o aplicativo, às vezes chamado de público-alvo de login. Para este tutorial, selecionei "Accounts in this organizational directory only (Default Directory only - Single tenant)." Isso só permite que os usuários que estão no meu locatário atual acessem meu aplicativo.
Clique em “Register.” Assim que o registro inicial do aplicativo for concluído, copie o ID do diretório (locatário) e o ID do aplicativo (cliente), pois precisaremos deles mais tarde.
Encontre o aplicativo vinculado em "Managed application in local directory " e clique nele.
Uma vez levado para a página “Properties”, copie também o “Object ID”, pois precisaremos dele também.

Crie um segredo do cliente

Depois que seu aplicativo for registrado, precisaremos criar um segredo do cliente para ele. Isso será necessário ao autenticar no Key Vault que criaremos em breve.

Na visão geral do seu aplicativo recém-registrado, clique em “Add a certificate or secret”:
Em “Client secrets,”, clique em “+ New client secret.”
Insira uma breve descrição para este segredo do cliente e deixe a configuração padrão "Expires " de 6 meses.
Clique em "Ad." Once the client secret is created, be sure to copy the secret’s “Value", pois precisaremos dele mais tarde. Também vale a pena mencionar que, depois de sair desta página, o valor secreto nunca mais será exibido, portanto, certifique-se de registrá-lo pelo menos uma vez!

Criar um Azure Key Vault

Em seguida, um Azure Key Vault! Criaremos uma para que possamos armazenar com segurança a chave mestra do cliente. Estaremos concluindo estas etapas por meio da CLI do Azure, então abra seu terminal favorito e acompanhe:

Entre no Azure CLI utilizando o comandoaz login . Conclua as etapas de autenticação seguindo as etapas exibidas no seu terminal.
Crie um grupo de recursos:
Trecho de códigoaz group create --name "YOUR-RESOURCE-GROUP-NAME" --location <YOUR-AZURE-REGION>
Crie um cofre de chaves:
Trecho de códigoaz keyvault create --name "YOUR-KEYVAULT-NAME" --resource-group "YOUR-RESOURCE-GROUP-NAME" --location <YOUR-AZURE-REGION>

Crie e adicione uma chave ao seu Key Vault

Com um cofre de chaves, agora podemos criar nossa chave mestra do cliente! Isso será armazenado, gerenciado e protegido pelo Azure Key Vault.

Criar uma chave e adicionar ao nosso cofre de chaves:

Trecho de código

O parâmetro --protectiondesigna otipo de proteção de chave. Por enquanto, usaremos o tiposoftware. Quando o comando for concluído, anote o "nome" da sua chave, pois precisaremos dela mais tarde!

Conceder permissões de aplicativo para o Key Vault

Para habilitar o acesso do aplicativo do cliente ao cofre de chaves, algumas permissões precisam ser concedidas:

Dê ao seu aplicativo as permissõeswrapKey e unwrapKey para o keyvault. (Para o parâmetro--object-id, cole o ID do objeto do aplicativo que registramos anteriormente. Esse é o ID do objeto que copiamos na última etapa "Registrar aplicativo no Azure Active Directory".)
Trecho de códigoaz keyvault set-policy --name "YOUR-KEYVAULT-NAME" --key-permissions wrapKey unwrapKey --object-id <YOUR-APP-OBJECT-ID>
Após o sucesso, você receberá um objeto JSON. Encontre e copie o valor da chave "vaultUri ". Por exemplo, o meu é https://csfle-mdb-demo-vault.vault.azure.net.

Integrar o Azure Key Vault ao seu aplicativo cliente

Agora que nossa infraestrutura em nuvem está configurada, podemos começar a integrá-la ao nosso aplicativo. Faremos referência ao repositório de amostraa partir de nossos pré-requisitos para essas etapas, mas fique à vontade para usar as partes necessárias em um aplicativoexistente.

Se você ainda não clonou o repositório, faça isso agora!
Trecho de códigogit clone https://github.com/adriennetacke/mongodb-csfle-csharp-demo-azure.git
Navegue até o diretório raiz mongodb-csfle-csharp-demo-azure e abra o aplicativo de amostraEnvoyMedSysno Visual Studio.
No Solution Explorer, localize e abra o arquivolaunchSettings.json(Properties > launchSettings.json).
Aqui, você verá alguns andaimes para algumas variáveis. Vamos Go rapidamente o que são:
- MDB_ATLAS_URIA string de conexão para o seu cluster do MongoDB Atlas. Isso nos permite armazenar nossa chave de encriptação de dados, criptografada pelo Azure Key Vault.
- AZURE_TENANT_IDIdentifica a organização da conta do Azure.
- AZURE_CLIENT_ID: Identifica o clientId para autenticar seu aplicativo registrado.
- AZURE_CLIENT_SECRETUsado para autenticar seu aplicativo registrado.
- AZURE_KEY_NAMENome da Chave Mestra do Cliente armazenada no Azure Key Vault.
- AZURE_KEYVAULT_ENDPOINT: URL do Key Vault. Por exemplo, yourVaultName.vault.azure.net.
Substitua todos os espaços reservados no arquivo launchSettings.jsonporsuas próprias informações. Cada variável corresponde a um valor que você foi solicitado para copiar e acompanhar:
- MDB_ATLAS_URI: o URI do seu Atlas.
- AZURE_TENANT_ID: ID do diretório (locatário).
- AZURE_CLIENT_ID: ID do aplicativo (cliente).
- AZURE_CLIENT_SECRET:valorsecreto do segredo do cliente.
- AZURE_KEY_NAME:Nomeda Chave.
- AZURE_KEYVAULT_ENDPOINT : vaultUrido nosso Key Vault.
Salve todos os seus arquivos!

Antes de executarmos o aplicativo, vamos analisar o que está acontecendo: quando executamos nosso programa principal, definimos a conexão com o cluster Atlas e o namespace da collection do cofre de chaves. Em seguida, instanciamos duas classes auxiliares:KmsKeyHelper e AutoEncryptHelper. O KmsKeyHelper CreateKeyWithAzureKmsProvider() método do é chamado para gerar nossa chave de criptografia de dados criptografados. Em seguida, isso é passado para o AutoEncryptHelper EncryptedWriteAndReadAsync() método do para inserir um documento de amostra com campos criptografados e descriptografá-lo adequadamente quando precisarmos buscá-lo. Tudo isso está em nosso Program.cs arquivo :

Program.cs

Trecho de código

Dando uma olhada na classeKmsKeyHelper, há alguns métodos importantes: os métodos CreateKeyWithAzureKmsProvider() e GetClientEncryption(). Optou por incluir comentários no código para facilitar o acompanhamento:
KmsKeyHelper.cs / CreateKeyWithAzureKmsProvider()

Trecho de código

public async Task<string> CreateKeyWithAzureKmsProvider()
{
    var kmsProviders = new Dictionary<string, IReadOnlyDictionary<string, object>>();

// Pull Azure Key Vault settings from environment variables
    var azureTenantId = Environment.GetEnvironmentVariable("AZURE_TENANT_ID");
    var azureClientId = Environment.GetEnvironmentVariable("AZURE_CLIENT_ID");
    var azureClientSecret = Environment.GetEnvironmentVariable("AZURE_CLIENT_SECRET");
    var azureIdentityPlatformEndpoint = Environment.GetEnvironmentVariable("AZURE_IDENTIFY_PLATFORM_ENPDOINT"); // Optional, only needed if user is using a non-commercial Azure instance

// Configure our registered application settings
   var azureKmsOptions = new Dictionary<string, object>
    {
        { "tenantId", azureTenantId },
        { "clientId", azureClientId },
        { "clientSecret", azureClientSecret },
    };

if (azureIdentityPlatformEndpoint != null)
    {
        azureKmsOptions.Add("identityPlatformEndpoint", azureIdentityPlatformEndpoint);
    }
	
    // Specify remote key location; in this case, Azure
    kmsProviders.Add("azure", azureKmsOptions);
	
    // Constructs our client encryption settings which
    // specify which key vault client, key vault namespace,
    // and KMS providers to use. 
    var clientEncryption = GetClientEncryption(kmsProviders);

// Set KMS Provider Settings
    // Client uses these settings to discover the master key
    var azureKeyName = Environment.GetEnvironmentVariable("AZURE_KEY_NAME");
    var azureKeyVaultEndpoint = Environment.GetEnvironmentVariable("AZURE_KEYVAULT_ENDPOINT"); // typically <azureKeyName>.vault.azure.net
    var azureKeyVersion = Environment.GetEnvironmentVariable("AZURE_KEY_VERSION"); // Optional
    var dataKeyOptions = new DataKeyOptions(
        masterKey: new BsonDocument
        {
            { "keyName", azureKeyName },
            { "keyVaultEndpoint", azureKeyVaultEndpoint },
            { "keyVersion", () => azureKeyVersion, azureKeyVersion != null }
        });
	
    // Create Data Encryption Key
    var dataKeyId = clientEncryption.CreateDataKey("azure", dataKeyOptions, CancellationToken.None);
    Console.WriteLine($"Azure DataKeyId [UUID]: {dataKeyId}");

var dataKeyIdBase64 = Convert.ToBase64String(GuidConverter.ToBytes(dataKeyId, GuidRepresentation.Standard));
    Console.WriteLine($"Azure DataKeyId [base64]: {dataKeyIdBase64}");
	
    // Optional validation; checks that key was created successfully
    await ValidateKeyAsync(dataKeyId);

return dataKeyIdBase64;
}

KmsKeyHelper.cs / GetClientEncryption()

Trecho de código

Com o Azure Key Vault conectado e a chave de encriptação de dados criptografada, estamos prontos para inserir alguns dados em nosso Atlas cluster! É aqui que entra a classe AutoEncryptHelper . O método importante a ser observado aqui é o métodoEncryptedReadAndWrite():

AutoEncryptHelper.cs / EncryptedReadAndWrite()

Trecho de código

public async Task EncryptedWriteAndReadAsync(string keyIdBase64, KmsKeyLocation kmsKeyLocation)
{
    // Construct a JSON Schema
    var schema = JsonSchemaCreator.CreateJsonSchema(keyIdBase64);

// Construct an auto-encrypting client
    var autoEncryptingClient = CreateAutoEncryptingClient(
        kmsKeyLocation,
        _keyVaultNamespace,
        schema);

// Set our working database and collection to medicalRecords.patientData
    var collection = autoEncryptingClient
        .GetDatabase(_medicalRecordsNamespace.DatabaseNamespace.DatabaseName)
        .GetCollection<BsonDocument>(_medicalRecordsNamespace.CollectionName);

var ssnQuery = Builders<BsonDocument>.Filter.Eq("ssn", __sampleSsnValue);

// Upsert (update if found, otherwise create it) a document into the collection
    var medicalRecordUpdateResult = await collection
        .UpdateOneAsync(ssnQuery, new BsonDocument("$set", __sampleDocFields), new UpdateOptions() { IsUpsert = true });

if (!medicalRecordUpdateResult.UpsertedId.IsBsonNull)
    {
        Console.WriteLine("Successfully upserted the sample document!");
    }

// Query by SSN field with auto-encrypting client
    var result = await collection.Find(ssnQuery).SingleAsync();
	
    // Proper result in console should show decrypted, human-readable document
    Console.WriteLine($"Encrypted client query by the SSN (deterministically-encrypted) field:\n {result}\n");
}

Agora que sabemos o que está rolando, execute seu aplicativo!

Os resultados: o que você obtém após integrar o Azure Key Vault com o MongoDB CSFLE

Se tudo correr bem, seu console imprimirá dois DataKeyIds (UUID e64 base ) e um documento semelhante ao seguinte:

Sample Result Document (using my information)

Trecho de código

Veja como é a saída do meu console, para referência:

Ver isso é uma ótima notícia! Muitas coisas acabaram de acontecer, e todas elas são boas:

Nosso aplicativo foi autenticado corretamente em nosso Azure Key Vault.
Uma chave de criptografia de dados gerada corretamente foi criada pelo nosso aplicativo cliente.
A chave de criptografia de dados foi criptografada corretamente pela chave mestra do cliente que está armazenada com segurança no Azure Key Vault.
A chave de encriptação de dados criptografada foi retornada ao nosso aplicativo e armazenada em nosso MongoDB Atlas cluster.

Aqui está o mesmo processo em um fluxo de trabalho:

Depois de mais alguns instantes, e após o sucesso, você verá uma mensagem "Successfully upserted the sample document!", seguida pelos resultados devidamente descriptografados de uma consulta de teste. Novamente, aqui está a saída do meu console para referência:

Isso significa que nosso documento de amostra foi criptografado corretamente, inserido em nossa coleção patientData, consultado com nosso cliente de criptografia automática por SSN e teve todos os campos relevantes descriptografados corretamente antes de retorná-los ao nosso console. Que legal!

E só por ser um pouco paranóia, podemos verificar se nossos dados foram realmente criptografados. Se você fizer login em seu Atlas cluster e navegar até a coleçãopatientData, verá que os campos confidenciais de nossos documentos estão todos ilegíveis:

Vamos resumir

Isso não foi tão ruim, certo? Vamos ver o que conseguimos! Este tutorial mostrou a você:

Registrando um aplicativo no Azure Active Directory.
Criando um segredo do cliente.
Criando um Azure Key Vault.
Criar e adicionar uma chave ao seu Key Vault.
Concedendo permissões de aplicativo para o Key Vault.
Integrando o Azure Key Vault ao seu aplicativo cliente.
Os resultados: o que você obtém após integrar o Azure Key Vault com o MongoDB CSFLE.

Ao usar um sistema de gerenciamento de chaves remoto como o Azure Key Vault, você obtém acesso a muitos benefícios em relação ao uso de um sistema de arquivos local. O mais importante deles é o armazenamento seguro da chave, risco reduzido de problemas de permissão de acesso e portabilidade mais fácil!

Para obter mais informações, confira esta lista útil de recursos que usei ao preparar este tutorial:

E se você tiver alguma dúvida ou precisar de ajuda adicional, não deixe de nos consultar nos fóruns daMongoDB Community e iniciar um tópico!

Uma comunidade inteira de engenheiros do MongoDB (incluindo a equipe DevRel) e outros desenvolvedores com certeza ajudarão!

Avalie esse Tutorial

Relacionado

Tutorial

Integrating MongoDB with TensorFlow and C#

Sep 05, 2024 | 8 min read

Tutorial

Introdução ao MongoDB Atlas e ao Azure Functions usando .NET e C#

Apr 02, 2024 | 8 min read

Tutorial

Introdução ao Unity para criar um jogo 2D

Apr 02, 2024 | 9 min read

Tutorial

Aplicativos multiplataforma com capacidade de dados online/offline com o MongoDB Atlas, SDKs para dispositivos Atlas e .NET MAUI

Nov 14, 2023 | 6 min read

Sumário

Pré-requisitos
Salto rápido
Registrar aplicativo no Azure Active Directory
Crie um segredo do cliente
Criar um Azure Key Vault
Crie e adicione uma chave ao seu Key Vault
Conceder permissões de aplicativo para o Key Vault
Integrar o Azure Key Vault ao seu aplicativo cliente
Os resultados: o que você obtém após integrar o Azure Key Vault com o MongoDB CSFLE
Vamos resumir