Join us at MongoDB.local London on 7 May to unlock new possibilities for your data. Use WEB50 to save 50%.
Register now >
Docs Menu
Docs Home
/ /
Backend de Django MongoDB
Docs Home
/
Librerías de clientes
/
Python
/
Backend de Django MongoDB
Docs Home
/
Librerías de clientes
/
Python
/
Backend de Django MongoDB

Tutorial: Queryable Encryption con Django MongoDB Backend

Overview

En este tutorial, puede aprender a usar Queryable Encryption (QE) en una aplicación Django.

La funcionalidad de Queryable Encryption de MongoDB ayuda a proteger los datos sensibles cifrándolos automáticamente, al tiempo que permite que tu aplicación interactúe con los datos cifrados. En este tutorial, puedes aprender cómo usar Queryable Encryption con Django MongoDB Backend habilitando el cifrado en la configuración de tu aplicación y eligiendo los campos del modelo a cifrar.

Requisitos previos

Antes de comenzar este tutorial, completa las siguientes tareas previas:

  • Crea una cuenta de MongoDB Atlas y configura un clúster. Asegúrate de que tu clúster se ejecute en MongoDB Server versión 7.0 o posterior. Para obtener más información, consulte la MongoDB Get Started guía.

  • Descargue la biblioteca compartida de cifrado automático. Para ver las instrucciones, consulte la guía "Instalar y configurar un componente de análisis de consultas". Estas instrucciones muestran cómo acceder al Centro de descargas de MongoDB y completar el formulario para descargar la biblioteca.

  • Instalar Python 3.10 o posterior.

Tutorial

En este tutorial, creas una aplicación de Queryable Encryption que utiliza Django MongoDB backend. La aplicación gestiona los registros médicos de forma segura: cifra, descifra y query información médica sensible.

Tip

Aplicación completa

Para consultar la aplicación de muestra completa de este tutorial, consulta la carpeta django_qe en GitHub.

Configurar el proyecto

Sigue los pasos de esta sección para instalar las dependencias del proyecto, configurar tu entorno y crear la estructura de la aplicación.

1

Instala Django MongoDB Backend con las dependencias QE.

Seleccione la pestaña correspondiente a su sistema operativo y ejecute los siguientes comandos para activar un entorno virtual, instalar Django MongoDB Backend e instalar las dependencias de Queryable Encryption:

python -m venv venv
source venv/bin/activate
pip install 'django-mongodb-backend[encryption]'
python -m venv venv
. venv\Scripts\activate
pip install 'django-mongodb-backend[encryption]'

La pip install 'django-mongodb-backend[encryption]' El comando instala Django MongoDB Backend, la última versión de PyMongo y las dependencias de Python necesarias.

Nota

Disponible en la versión6.0.1

Queryable Encryption requiere Django MongoDB Backend v6.0.1 o posterior. El comando anterior instala la versión requerida.

2

Crea el directorio de tu proyecto.

Desde tu shell, ejecuta el siguiente comando para crear un nuevo proyecto de Django llamado django_qe basado en una plantilla personalizada:

django-admin startproject django_qe --template https://github.com/mongodb-labs/django-mongodb-project/archive/refs/heads/6.0.x.zip

Este comando crea un directorio de proyecto django_qe y agrega la estructura inicial de archivos.

3

Cree sus archivos de aplicación.

Desde tu directorio django_qe, ejecuta el siguiente comando para crear una aplicación llamada medical_records:

python manage.py startapp medical_records

Este comando crea un directorio de aplicación medical_records en tu proyecto y agrega archivos de aplicación por defecto, incluidos archivos para tus modelos y configuraciones.

4

Incluye tu aplicación en tu proyecto.

Navegue al archivo settings.py en su directorio django_qe y edite su configuración INSTALLED_APPS para que se asemeje al siguiente código:

INSTALLED_APPS = [
    'medical_records.apps.MedicalRecordsConfig',
    'django_qe.apps.MongoAdminConfig',
    'django_qe.apps.MongoAuthConfig',
    'django_qe.apps.MongoContentTypesConfig',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'django_mongodb_backend',
]

Esta configuración garantiza que su aplicación medical_records esté habilitada en su proyecto.

Conectar y habilitar el cifrado

Después de configurar su proyecto, siga los pasos de esta sección para conectarse a MongoDB y crear modelos que almacenen datos cifrados.

1

Connect to MongoDB.

En tu directorio django_qe, navega al archivo settings.py. Reemplaza la configuración DATABASES con el siguiente código:

DATABASES = {
    'default': {
        'ENGINE': 'django_mongodb_backend',
        'HOST': '<connection string>',
        'NAME': 'db',
    },
}

Reemplace el marcador de posición <connection string> con la cadena de conexión que se conecta a su clúster.

Este código configura tu aplicación Django para conectarse a MongoDB y acceder a una base de datos llamada db por defecto. Esta configuración se aplica a tus modelos no cifrados.

2

Configura Queryable Encryption.

En tu archivo settings.py, puedes especificar la clave encrypted en tu configuración de DATABASES para habilitar el Queryable Encryption y configurar a tu proveedor de sistema de gestión de claves (KMS). El backend de Django MongoDB es compatible con los proveedores AWS, Azure, GCP, KMIP y KMS locales.

Advertencia

Almacenamiento local de llave maestra de cliente

Si almacenas tu llave maestra de cliente (CMK) localmente, no utilices esta aplicación en producción. Sin un KMS remoto, corres el riesgo de que haya un acceso no autorizado a la llave de cifrado o la pérdida de la clave necesaria para descifrar tus datos.

Tip

Sistemas de gestión de claves

Para obtener más información sobre KMS, consulta la entrada de Wikipedia sobre Gestión de claves.

Seleccione la pestaña correspondiente a su KMS y modifique su configuración DATABASES para que se parezca al siguiente ejemplo:

DATABASES = {
    'default': {
        # ... Your default configuration
    },
    'encrypted': {
        'ENGINE': 'django_mongodb_backend',
        'HOST': '<connection string>',
        'NAME': 'medical_records',
        # ...
        'OPTIONS': {
            'auto_encryption_opts': AutoEncryptionOpts(
                key_vault_namespace='medical_records.__keyVault',
                kms_providers={
                    'local': {
                        # Generated by os.urandom(96)
                        'key': (
                            b'-\xc3\x0c\xe3\x93\xc3\x8b\xc0\xf8\x12\xc5#b'
                            b'\x19\xf3\xbc\xccR\xc8\xedI\xda\\ \xfb\x9cB'
                            b'\x7f\xab5\xe7\xb5\xc9x\xb8\xd4d\xba\xdc\x9c'
                            b'\x9a\xdb9J]\xe6\xce\x104p\x079q.=\xeb\x9dK*'
                            b'\x97\xea\xf8\x1e\xc3\xd49K\x18\x81\xc3\x1a"'
                            b'\xdc\x00U\xc4u"X\xe7xy\xa5\xb2\x0e\xbc\xd6+-'
                            b'\x80\x03\xef\xc2\xc4\x9bU'
                        )
                    },
                },
                crypt_shared_lib_path='<Automatic Encryption Shared Library path>',
                crypt_shared_lib_required=True,
            )
        },
    },
}

Reemplace los siguientes valores de marcador de posición:

  • <connection string>: La misma cadena de conexión que especificaste en la clave default

  • <Automatic Encryption Shared Library path>La ruta completa a su librería Compartida de Cifrado Automático

DATABASES = {
    'default': {
        # ... Your default configuration
    },
    'encrypted': {
        'ENGINE': 'django_mongodb_backend',
        'HOST': '<connection string>',
        'NAME': 'medical_records',
        # ...
        'OPTIONS': {
            'auto_encryption_opts': AutoEncryptionOpts(
                key_vault_namespace='medical_records.__keyVault',
                kms_providers={
                    'aws': {
                        'accessKeyId': '<AWS Access Key ID>',
                        'secretAccessKey': '<AWS Secret Access Key>',
                    },
                },
                crypt_shared_lib_path='<Automatic Encryption Shared Library path>',
                crypt_shared_lib_required=True,
            )
        },
        'KMS_CREDENTIALS': {
            'aws': {
                'key': '<AWS Key ARN>', 
                'region': '<AWS Key Region>', 
            },
        },
    },
}

Reemplace los siguientes valores de marcador de posición:

  • <connection string>: La misma cadena de conexión que especificaste en la clave default

  • <AWS Access Key ID>: Su clave de acceso de AWS ID

  • <AWS Secret Access Key>Tu clave secreta de acceso de AWS

  • <Automatic Encryption Shared Library path>La ruta completa a su librería Compartida de Cifrado Automático

  • <AWS Key ARN>: El nombre del recurso de Amazon para el cliente de AWS.

  • <AWS Key Region>: Tu región de AWS, por ejemplo 'us-east-1'

DATABASES = {
    'default': {
        # ... Your default configuration
    },
    'encrypted': {
        'ENGINE': 'django_mongodb_backend',
        'HOST': '<connection string>',
        'NAME': 'medical_records',
        # ...
        'OPTIONS': {
            'auto_encryption_opts': AutoEncryptionOpts(
                key_vault_namespace='medical_records.__keyVault',
                kms_providers={
                    'azure': {
                        'tenantId': '<Azure Tenant ID>',
                        'clientId': '<Azure Client ID>',
                        'clientSecret': '<Azure Client Secret>',
                    },
                },
                crypt_shared_lib_path='<Automatic Encryption Shared Library path>',
                crypt_shared_lib_required=True,
            )
        },
        'KMS_CREDENTIALS': {
            'azure': {
                'keyVaultEndpoint': '<Azure Key Vault Endpoint>',
                'keyName': '<Azure Key Name>',
                # Optional: 'keyVersion': '<Azure Key Version>',
            },
        },
    },
}

Reemplace los siguientes valores de marcador de posición:

  • <connection string>: La misma cadena de conexión que especificaste en la clave default

  • <Azure Tenant ID>ID del inquilino de Azure Active Directory

  • <Azure Client ID>ID de cliente de su aplicación de Azure:

  • <Azure Client Secret>: El secreto de cliente de tu aplicación de Azure

  • <Automatic Encryption Shared Library path>La ruta completa a su librería Compartida de Cifrado Automático

  • <Azure Key Vault Endpoint>:La URL del punto de conexión de Azure Key Vault.

  • <Azure Key Name>: El nombre de su clave en Azure Key Vault

  • <Azure Key Version>: (Opcional) La versión de la clave a utilizar

DATABASES = {
    'default': {
        # ... Your default configuration
    },
    'encrypted': {
        'ENGINE': 'django_mongodb_backend',
        'HOST': '<connection string>',
        'NAME': 'medical_records',
        # ...
        'OPTIONS': {
            'auto_encryption_opts': AutoEncryptionOpts(
                key_vault_namespace='medical_records.__keyVault',
                kms_providers={
                    'gcp': {
                        'email': '<GCP Service Account Email>',
                        'privateKey': '<GCP Service Account Private Key>',
                    },
                },
                crypt_shared_lib_path='<Automatic Encryption Shared Library path>',
                crypt_shared_lib_required=True,
            )
        },
        'KMS_CREDENTIALS': {
            'gcp': {
                'projectId': '<GCP Project ID>',
                'location': '<GCP Key Ring Location>',
                'keyRing': '<GCP Key Ring Name>',
                'keyName': '<GCP Key Name>',
            },
        },
    },
}

Reemplace los siguientes valores de marcador de posición:

  • <connection string>: La misma cadena de conexión que especificaste en la clave default

  • <GCP Service Account Email>:El correo electrónico de su cuenta de servicio de Google Cloud

  • <GCP Service Account Private Key>: Tu llave privada de cuenta de servicio de Google Cloud

  • <Automatic Encryption Shared Library path>La ruta completa a su librería Compartida de Cifrado Automático

  • <GCP Project ID>: El ID de tu proyecto de Google Cloud

  • <GCP Key Ring Location>:La ubicación de su llavero, como por ejemplo 'global'

  • <GCP Key Ring Name>: El nombre de su llavero

  • <GCP Key Name>:El nombre de tu clave

DATABASES = {
    'default': {
        # ... Your default configuration
    },
    'encrypted': {
        'ENGINE': 'django_mongodb_backend',
        'HOST': '<connection string>',
        'NAME': 'medical_records',
        # ...
        'OPTIONS': {
            'auto_encryption_opts': AutoEncryptionOpts(
                key_vault_namespace='medical_records.__keyVault',
                kms_providers={
                    'kmip': {
                        'endpoint': '<KMIP Server Endpoint>',
                    },
                },
                crypt_shared_lib_path='<Automatic Encryption Shared Library path>',
                crypt_shared_lib_required=True,
            )
        },
        'KMS_CREDENTIALS': {
            'kmip': {
                # Optional: 'keyId': '<KMIP Key Identifier>',
            },
        },
    },
}

Reemplace los siguientes valores de marcador de posición:

  • <connection string>:La misma cadena de conexión que especificó en la clave default.

  • <KMIP Server Endpoint>: Tu endpoint del servidor KMIP con su puerto, como 'example.com:443'.

  • <Automatic Encryption Shared Library path>: La ruta completa a su librería Compartida de cifrado automático.

  • <KMIP Key Identifier>Opcional) El Identificador único KMIP para un objeto gestionado de datos secretos KMIP de 96bytes. Si se omite este valor, Django MongoDB Backend crea un objeto aleatorio de 96bytes.

Este código se conecta a la base de datos cifrada medical_records, almacena sus claves de datos en la colección medical_records.__keyVault y configura su proveedor KMS.

3

Dirija las operaciones a la base de datos cifrada.

En tu directorio medical_records, crea un archivo llamado routers.py y pega el siguiente código en él:

class EncryptedRouter:
    def allow_migrate(self, db, app_label, model_name=None, **hints):
        # Create medical_records models only in the encrypted database.
        if app_label == "medical_records":
            return db == "encrypted"
        # Don't create collections for other apps in the encrypted db.
        if db == "encrypted":
            return False
        return None
    def db_for_read(self, model, **hints):
        # All reads and writes for medical_records models go to the encrypted db.
        if model._meta.app_label == "medical_records":
            return "encrypted"
        return None
    db_for_write = db_for_read

Este archivo enruta las operaciones de base de datos en todos los modelos de tu aplicación medical_records hacia la base de datos cifrada medical_records.

Luego, agregue su enrutador personalizado navegando a su archivo settings.py y reemplazando la configuración DATABASE_ROUTERS con el siguiente código:

DATABASE_ROUTERS = [
    'django_mongodb_backend.routers.MongoRouter',
    'medical_records.routers.EncryptedRouter',
]
4

Cree modelos que almacenen campos cifrados.

En tu directorio medical_records, navega al archivo models.py y pega el siguiente código:

from django.db import models
from django_mongodb_backend.models import EmbeddedModel
from django_mongodb_backend.fields import (
    EmbeddedModelField,
    EncryptedCharField,
    EncryptedEmbeddedModelField,
)
class Patient(models.Model):
    patient_name = models.CharField(max_length=255)
    patient_id = models.BigIntegerField()
    patient_record = EmbeddedModelField("PatientRecord")
    class Meta:
        db_table = "patients"
    def __str__(self):
        return f"{self.patient_name} ({self.patient_id})"
class PatientRecord(EmbeddedModel):
    ssn = EncryptedCharField(max_length=11, queries={"queryType": "equality"})
    billing = EncryptedEmbeddedModelField("Billing")
    bill_amount = models.DecimalField(max_digits=10, decimal_places=2)
class Billing(EmbeddedModel):
    cc_type = models.CharField(max_length=50)
    cc_number = models.CharField(max_length=20)

Este código crea un modelo Patient, que corresponde a la colección patients de la base de datos medical_records. También crea dos modelos incrustados, PatientRecord y Billing, para representar los campos anidados de la colección.

El código configura los siguientes campos cifrados:

  • patient_record.ssn: cifrado y configurado para consultas de igualdad

  • patient_record.billing.cc_type:Encriptado, pero no consultable

  • patient_record.billing.cc_number:Encriptado, pero no consultable

Realizar operaciones cifradas

Después de configurar su aplicación y la conexión de la base de datos, siga los pasos de esta sección para insertar y consultar documentos cifrados.

1

Ejecutar migraciones en la base de datos cifrada.

Ejecute los siguientes comandos desde su directorio django_qe para crear migraciones para sus modelos y aplicarlas a la base de datos:

python manage.py makemigrations medical_records
python manage.py migrate --database encrypted
2

Inicie un shell de Python.

Ejecute el siguiente comando para ingresar a la Python shell:

python manage.py shell

Luego, ejecuta el siguiente comando en la shell para importar los modelos requeridos:

from medical_records.models import Patient, PatientRecord, Billing
3

Insertar datos cifrados.

Desde tu shell, ejecuta los siguientes comandos para crear una instancia Patient e insertar un documento cifrado correspondiente en la base de datos:

billing = Billing(cc_type="Visa", cc_number="4111111111111111")
record = PatientRecord(ssn="987-65-4320", billing=billing, bill_amount=1500)
patient = Patient.objects.create(
   name="John Doe",
   patient_id=12345678,
   patient_record=record
)

Si navega a su colección de medical_records.patients en MongoDB Atlas, se puede ver que los campos patient_record.ssn y patient_record.billing del documento están cifrados.

4

Consultar datos cifrados.

Ejecuta el siguiente comando para realizar una query de igualdad en el campo cifrado patient_record.ssn:

Patient.objects.get(patient_record__ssn="987-65-4320")

Si es exitoso, el comando devuelve los siguientes datos del paciente:

<Patient: John Doe (12345678)>

Próximos pasos

¡Felicidades por completar el tutorial de Queryable Encryption! Ahora tienes una aplicación de muestra de Django que utiliza Queryable Encryption para cifrar y descifrar automáticamente los campos de documento. Tu aplicación cifra los datos sensibles del lado del servidor y query los datos del lado del cliente.

Para aprender más sobre Queryable Encryption y Django MongoDB Backend, visita los siguientes recursos:

Volver

Transacciones y sesiones

Next

Migrar aplicaciones de Djongo ODM

En esta página