Autenticazione Microsoft Entra con mssql-python

Microsoft Entra ID fornisce autenticazione basata sull'identità per database SQL di Azure, Istanza gestita di SQL di Azure e database SQL in Microsoft Fabric tramite il driver mssql-python. L'autenticazione Microsoft Entra offre queste funzionalità rispetto all'autenticazione SQL:

• Gestione centralizzata dell'identità tramite Microsoft Entra ID.
• Autenticazione basata su token che elimina la necessità di password.
• Supporto per politiche di accesso condizionato.
• Identità gestite per applicazioni ospitate su Azure.

Il driver mssql-python supporta sette modalità di autenticazione Microsoft Entra, tutte configurate tramite la Authentication parola chiave stringa di connessione.

Modalità di autenticazione

Imposta la Authentication parola chiave nella tua stringa di connessione su uno dei seguenti valori:

DefaultAzureCredential (Credenziali Predefinite di Azure)

La ActiveDirectoryDefault modalità utilizza DefaultAzureCredential dall'Azure Identity SDK, che prova questi metodi di autenticazione in ordine:

1. variabili di ambiente.
2. Identità del carico di lavoro per Kubernetes.
3. Identità gestita.
4. Credenziali di interfaccia della riga di comando di Azure.
5. Credenziali di Azure PowerShell
6. Credenziali di Azure Developer CLI
7. Browser interattivo, se abilitato.

Esempio: autenticazione predefinita

Il seguente esempio si collega a ActiveDirectoryDefault, che utilizza la DefaultAzureCredential catena per trovare automaticamente una credenziale valida:

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()}")

Usa questa modalità per lo sviluppo locale perché rileva automaticamente le credenziali interfaccia della riga di comando di Azure. Per la produzione, si utilizza invece una specifica modalità di autenticazione (ActiveDirectoryMSI, ActiveDirectoryServicePrincipal). DefaultAzureCredential Passa attraverso più fornitori di credenziali su ogni prima connessione, aggiungendo latenza che i carichi di lavoro in produzione non hanno bisogno.

Autenticazione interattiva

Per applicazioni interattive, si utilizza l'autenticazione basata su browser. L'utente deve avere un account database creato con CREATE USER [user@domain.com] FROM EXTERNAL PROVIDER. Per tutti i prerequisiti, vedi Configura l'autenticazione Microsoft Entra.

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

Su Windows, questa modalità delega al flusso interattivo nativo del driver ODBC. Su altre piattaforme, utilizza l'autenticazione basata su browser dell'Azure Identity SDK.

Autenticazione con codice del dispositivo

Usa l'autenticazione tramite codice dispositivo per ambienti senza browser, come sessioni SSH o container. L'utente deve avere un account database creato con CREATE USER [user@domain.com] FROM EXTERNAL PROVIDER. Per i prerequisiti, vedi Configurare l'autenticazione 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.

Segui il prompt per autenticarti in un browser su un altro dispositivo.

Autenticazione del service principal

Usa l'autenticazione del principale di servizio per applicazioni automatizzate che non richiedono l'interazione dell'utente:

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;"
)

Creare un principale servizio

1. Registra una candidatura in Microsoft Entra ID.
2. Creare un segreto del client.
3. Concedere al service principal l'accesso al database:

-- 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>';

Identità gestita

Usa l'autenticazione dell'identità gestita per applicazioni ospitate su Azure, come App Service, Funzioni di Azure e VM:

Identità gestita assegnata dal sistema

Connettiti usando l'identità assegnata direttamente alla risorsa Azure:

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

Identità gestita assegnata dall'utente

Specifica l'ID client di un'identità gestita assegnata dall'utente UID nel campo:

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

Configurare l'accesso al database

Concedi all'identità gestita l'accesso nel tuo database. Un amministratore Microsoft Entra deve essere configurato sul server prima di poter creare utenti esterni. Per abilitare l'identità gestita sulla tua risorsa Azure, vedi Identità gestite per le risorse 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];

Autenticazione tramite password (obsoleta)

L'autenticazione tramite password di Microsoft Entra ID si basa sul flusso di concessione Resource Owner Password Credentials (ROPC) di OAuth 2.0, che consente a un'applicazione di eseguire l'accesso dell'utente gestendone direttamente la password.

Microsoft consiglia di non usare il flusso ROPC perché non è compatibile con MFA. Per la maggior parte degli scenari sono disponibili e consigliate alternative più sicure. Questo flusso richiede un elevato livello di attendibilità nell'applicazione e comporta rischi che non sono presenti in altri flussi. Usare questo flusso solo quando non sono validi flussi più sicuri. Microsoft si sta allontanando da questo flusso di autenticazione ad alto rischio per proteggere gli utenti da attacchi dannosi. Per altre informazioni, vedere Pianificazione dell'autenticazione a più fattori obbligatoria per Azure.

Quando un utente è presente durante l'accesso, usare l'autenticazione ActiveDirectoryInteractive o ActiveDirectoryIntegrated in modo che la traccia di controllo venga attribuita all'utente che ha effettuato l'accesso e si applichino i criteri di Accesso Condizionale.

Per gli scenari non presidiati servizio-servizio, seguire le linee guida sugli account di servizio Microsoft Entra:

• Se l'applicazione viene eseguita nell'infrastruttura Azure, usare ActiveDirectoryMSI (o ActiveDirectoryManagedIdentity in alcuni driver). Le identità gestite eliminano il sovraccarico di gestione e rotazione di segreti e certificati.
• Se l'identità gestita non è disponibile( ad esempio, l'applicazione viene eseguita all'esterno di Azure), usare ActiveDirectoryServicePrincipal. Se il driver lo supporta, preferire un certificato client anziché un segreto del client. Con un certificato, la chiave privata rimane sul client e solo un'asserzione firmata viene inviata a Microsoft Entra per autenticare il client. Se la chiave viene archiviata nell'hardware (ad esempio un TPM o un modulo di protezione hardware) o contrassegnata come non esportabile, non può essere copiata come stringa nel modo in cui un segreto client può.
• Non usare un account utente Microsoft Entra come account del servizio.

Usa l'autenticazione tramite password quando hai bisogno di un nome utente e una password con un account Microsoft Entra. L'utente deve avere un account database creato 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;"
)

Autenticazione integrata Windows

Usa l'autenticazione Windows Integrated per ambienti Windows a dominio con Kerberos. Questa modalità richiede che il tuo Active Directory locale sia federato con Microsoft Entra ID e un amministratore Microsoft Entra configurato sul server:

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

Questa modalità utilizza le credenziali Kerberos dell'utente Windows attuale. Su Linux e macOS, devi configurare Kerberos manualmente (krb5.conf e un keytab o ticket valido). Vedi Usa l'autenticazione Active Directory con SQL Server in Linux per la configurazione lato client di Kerberos.

Autenticazione del token di accesso

Potresti acquisire token esternamente, ad esempio, tramite un provider di token personalizzato o una cache di token condivisa. In questi casi, usa SQL_COPT_SS_ACCESS_TOKEN con il attrs_before parametro per passare direttamente il token. Questo approccio bypassa il flusso di acquisizione dei token integrato dal driver.

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()}
)

Scegliere una modalità di autenticazione

Troubleshoot

Accesso non riuscito per l'utente 'NT AUTHORITY\ANONYMOUS LOGON'

Verifica che l'utente o l'identità gestita esista nel database:

CREATE USER [identity-name] FROM EXTERNAL PROVIDER;

AADSTS700016: Applicazione non trovata

Il principale del servizio o l'ID dell'applicazione è errato. Verifica l'ID client e che l'app sia registrata nel tuo tenant Microsoft Entra.

Endpoint dell'identità gestita non raggiungibile

• Verifica che l'identità gestita sia abilitata sulla risorsa Azure.
• Per l'identità assegnata dall'utente, verifica che l'ID client sia corretto.
• Controlla che la risorsa abbia accesso alla rete dell'endpoint di identità.

Timeout per l'acquisizione dei token

ActiveDirectoryDefault usa DefaultAzureCredential, che percorre una catena di fornitori di credenziali in sequenza fino a quando uno ha successo. Questa chain walk aggiunge secondi di latenza sulla prima connessione, specialmente quando i provider precedenti nella catena (variabili ambientali, identità del carico di lavoro) falliscono prima di raggiungere quello che funziona. In produzione, specifica direttamente il tipo di credenziale per saltare la catena:

# 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")

Contenuti correlati

• Stringhe di connessione
• Risoluzione dei problemi
• Azure SQL migrazione senza password
• Autenticazione di Microsoft Entra tramite Azure SQL