Autenticación de Microsoft Entra con mssql-python

Microsoft Entra ID proporciona autenticación basada en identidad para Azure SQL Database, Azure SQL Managed Instance y base de datos SQL en Microsoft Fabric a través del controlador mssql-python. La autenticación Microsoft Entra ofrece estas capacidades sobre la autenticación SQL:

• Gestión centralizada de identidades a través de Microsoft Entra ID.
• Autenticación basada en tokens que elimina la necesidad de contraseñas.
• Soporte para políticas de acceso condicional.
• Identidades gestionadas para aplicaciones alojadas en Azure.

El controlador mssql-python admite siete modos de autenticación de Microsoft Entra, todos configurados mediante la palabra clave Authentication de la cadena de conexión.

Modos de autenticación

Establece la Authentication palabra clave en tu cadena de conexión en uno de los siguientes valores:

DefaultAzureCredential

El modo ActiveDirectoryDefault usa DefaultAzureCredential del SDK Azure Identity, que intenta los siguientes métodos de autenticación en este orden:

1. Variables de entorno.
2. Identidad de carga de trabajo para Kubernetes.
3. Identidad administrada.
4. Credenciales de CLI de Azure
5. Credenciales de Azure PowerShell.
6. Credenciales CLI de Azure Developer.
7. Navegador interactivo, si está habilitado.

Ejemplo: Autenticación por defecto

El siguiente ejemplo se relaciona con ActiveDirectoryDefault, que utiliza la DefaultAzureCredential cadena para encontrar automáticamente una credencial válida:

import mssql_python

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryDefault;"
    "Encrypt=yes;"
)

cursor = conn.cursor()
cursor.execute("SELECT USER_NAME()")
print(f"Connected as: {cursor.fetchval()}")

Utiliza este modo para desarrollo local porque recoge automáticamente las credenciales de CLI de Azure. Para producción, utiliza un modo de autenticación específico (ActiveDirectoryMSI, ActiveDirectoryServicePrincipal) en su lugar. DefaultAzureCredential Revisa varios proveedores de credenciales en cada primera conexión, lo que añade latencia que las cargas de trabajo en producción no necesitan.

Autenticación interactiva

Para aplicaciones interactivas, utiliza autenticación basada en navegador. El usuario debe tener una cuenta de base de datos creada con CREATE USER [user@domain.com] FROM EXTERNAL PROVIDER. Para todos los requisitos previos, consulte Configurar autenticación de Microsoft Entra.

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryInteractive;"
    "Encrypt=yes;"
)

En Windows, este modo delega al flujo interactivo nativo del controlador ODBC. En otras plataformas, utiliza la autenticación basada en navegador del SDK de Identidad de Azure.

Autenticación con código de dispositivo

Utiliza autenticación por código de dispositivo para entornos sin navegador, como sesiones SSH o contenedores. El usuario debe tener una cuenta de base de datos creada con CREATE USER [user@domain.com] FROM EXTERNAL PROVIDER. Para los requisitos previos, consulte Configurar autenticación de Microsoft Entra.

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryDeviceCode;"
    "Encrypt=yes;"
)
# Output: To sign in, use a web browser to open https://microsoft.com/devicelogin
# and enter the code XXXXXXX to authenticate.

Sigue la indicación para autenticarte en un navegador en otro dispositivo.

Autenticación de la entidad de servicio

Utiliza la autenticación del principal de servicio para aplicaciones automatizadas que no requieren interacción del usuario:

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryServicePrincipal;"
    "UID=<client-id>;"       # Application (client) ID
    "PWD=<client-secret>;"   # Client secret
    "Encrypt=yes;"
)

Crear un servicio principal

1. Registra una solicitud en Microsoft Entra ID.
2. Crear un secreto de cliente.
3. Concede al principal del servicio acceso a tu base de datos:

-- In Azure SQL
CREATE USER [app-name] FROM EXTERNAL PROVIDER;
ALTER ROLE db_datareader ADD MEMBER [app-name];
ALTER ROLE db_datawriter ADD MEMBER [app-name];

CREATE USER [app-name] FROM EXTERNAL PROVIDER
    WITH OBJECT_ID = '<enterprise-app-object-id>';

Identidad administrada

Utiliza la autenticación de identidad gestionada para aplicaciones alojadas en Azure, como App Service, Azure Functions y máquinas virtuales:

Identidad administrada asignada por el sistema

Conéctate usando la identidad asignada directamente al recurso de Azure:

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryMSI;"
    "Encrypt=yes;"
)

Identidad administrada asignada por el usuario

Especifica el ID de cliente de una identidad gestionada asignada por el usuario en el UID campo:

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryMSI;"
    "UID=<managed-identity-client-id>;"
    "Encrypt=yes;"
)

Configurar el acceso a la base de datos

Concede acceso a la identidad gestionada en tu base de datos. Un administrador de Microsoft Entra debe estar configurado en el servidor antes de poder crear usuarios externos. Para habilitar la identidad gestionada en tu recurso de Azure, consulta Identidades gestionadas para recursos de Azure.

-- Replace 'my-app-service' with your Azure resource name
CREATE USER [my-app-service] FROM EXTERNAL PROVIDER;
ALTER ROLE db_datareader ADD MEMBER [my-app-service];
ALTER ROLE db_datawriter ADD MEMBER [my-app-service];

Autenticación por contraseña (obsoleta)

La autenticación mediante contraseña de Microsoft Entra ID se basa en la concesión de credenciales de contraseña del propietario del recurso (ROPC) de OAuth 2.0, que permite a una aplicación iniciar la sesión del usuario mediante la administración directa de su contraseña.

Microsoft recomienda no usar el flujo ROPC porque no es compatible con MFA. En la mayoría de los escenarios, hay alternativas más seguras disponibles y recomendadas. Este flujo requiere un alto grado de confianza en la aplicación y conlleva riesgos que no están presentes en otros flujos. Use este flujo solo cuando los flujos más seguros no sean viables. Microsoft se aleja de este flujo de autenticación de alto riesgo para proteger a los usuarios frente a ataques malintencionados. Para obtener más información, consulte Planificación para la autenticación multifactor obligatoria en Azure.

Cuando un usuario está presente al iniciar sesión, use la autenticación ActiveDirectoryInteractive o ActiveDirectoryIntegrated para que el registro de auditoría se atribuya al usuario que ha iniciado sesión y se apliquen las directivas de Acceso condicional.

Para escenarios de servicio a servicio sin supervisión, siga las directrices sobre cuentas de servicio de Microsoft Entra:

• Si la aplicación se ejecuta en la infraestructura de Azure, use ActiveDirectoryMSI (o ActiveDirectoryManagedIdentity en algunos controladores). Las identidades administradas eliminan la sobrecarga de mantener y rotar secretos y certificados.
• Si la identidad administrada no está disponible (por ejemplo, la aplicación se ejecuta fuera de Azure), use ActiveDirectoryServicePrincipal. Cuando el controlador lo admita, prefiera un certificado de cliente sobre un secreto de cliente. Con un certificado, la clave privada permanece en el cliente y solo se envía una aserción firmada a Microsoft Entra para autenticar al cliente. Si la clave se almacena en hardware (como un TPM o un HSM) o está marcada como no exportable, no puede extraerse como una cadena, como sí puede hacerse con un secreto de cliente.
• No use una cuenta de usuario de Microsoft Entra como cuenta de servicio.

Utiliza autenticación por contraseña cuando necesites un nombre de usuario y una contraseña con una cuenta de Microsoft Entra. El usuario debe tener una cuenta de base de datos creada con CREATE USER [user@domain.com] FROM EXTERNAL PROVIDER:

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryPassword;"
    "UID=<login@domain.com>;"
    "PWD=<password>;"
    "Encrypt=yes;"
)

Autenticación integrada de Windows

Utiliza la autenticación integrada de Windows para entornos de Windows unidos a dominio con Kerberos. Este modo requiere que tu Active Directory local esté federado con Microsoft Entra ID y un administrador de Microsoft Entra configurado en el servidor:

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryIntegrated;"
    "Encrypt=yes;"
)

Este modo utiliza las credenciales Kerberos del usuario actual de Windows. En Linux y macOS, debes configurar Kerberos manualmente (krb5.conf y una keytab o ticket válido). Consulta Uso de la autenticación de Active Directory con SQL Server en Linux para configurar Kerberos en el cliente.

Autenticación de token de acceso

Podrías adquirir tokens externamente, por ejemplo, a través de un proveedor personalizado de tokens o una caché compartida de tokens. En estos casos, utiliza SQL_COPT_SS_ACCESS_TOKEN con el parámetro attrs_before para pasar el token directamente. Este enfoque evita el flujo de adquisición de tokens incorporado por el controlador.

import mssql_python
from azure.identity import DefaultAzureCredential
import struct

def get_token():
    credential = DefaultAzureCredential(
        exclude_interactive_browser_credential=False
    )
    token_bytes = credential.get_token(
        "https://database.windows.net/.default"
    ).token.encode("utf-16le")
    token_struct = struct.pack(
        f'<I{len(token_bytes)}s', len(token_bytes), token_bytes
    )
    return token_struct

SQL_COPT_SS_ACCESS_TOKEN = 1256

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;",
    attrs_before={SQL_COPT_SS_ACCESS_TOKEN: get_token()}
)

Elección de un modo de autenticación

Troubleshoot

"Error de inicio de sesión para el usuario 'NT AUTHORITY\ANONYMOUS LOGON'"

Verifica que el usuario o la identidad gestionada exista en la base de datos:

CREATE USER [identity-name] FROM EXTERNAL PROVIDER;

"AADSTS700016: Solicitud no encontrada"

El principal del servicio o el ID de la aplicación son incorrectos. Verifica el ID del cliente y que la aplicación está registrada en tu tenant de Microsoft Entra.

"Endpoint de Identidad Gestionada no accesible"

• Verifica que la identidad gestionada esté habilitada en el recurso de Azure.
• Para la identidad asignada por el usuario, verifica que el ID del cliente sea correcto.
• Comprueba que el recurso tenga acceso de red al endpoint de identidad.

Tiempo límite para la adquisición de tokens

ActiveDirectoryDefault utiliza DefaultAzureCredential, que recorre una cadena de proveedores de credenciales en secuencia hasta que uno tiene éxito. Esta caminata en cadena añade segundos de latencia en la primera conexión, especialmente cuando los proveedores anteriores en la cadena (variables de entorno, identidad de carga de trabajo) fallan antes de llegar al que funciona. En producción, especifica directamente el tipo de credencial para saltar la cadena:

# Slow: DefaultAzureCredential tries multiple providers
conn = mssql_python.connect(connection_string, authentication="ActiveDirectoryDefault")

# Fast: Skip directly to managed identity
conn = mssql_python.connect(connection_string, authentication="ActiveDirectoryMSI")

Contenido relacionado

• Cadenas de conexión
• Solución de problemas
• Migración sin contraseña de Azure SQL
• Autenticación de Microsoft Entra con Azure SQL