Uso di Microsoft Entra ID con il driver ODBC

Scaricare il driver ODBC

Scopo

Microsoft ODBC Driver for SQL Server versione 13.1 o successiva consente alle applicazioni ODBC di connettersi al database SQL di Azure o a un'istanza gestita di SQL Azure usando identità di Microsoft Entra ID. L'autenticazione può essere eseguita con un nome utente e una password, un token di accesso Microsoft Entra, un'identità gestita di Microsoft Entra (17.3+) oppure con l'autenticazione integrata di Windows in un ambiente federato aggiunto a un dominio (17.6+ in Linux/macOS). Per la versione 13.1 del Driver ODBC, l'autenticazione tramite token di accesso di Microsoft Entra è solo su Windows. Il driver ODBC versione 17 e successive supporta questa autenticazione in tutte le piattaforme (Windows, Linux e macOS). Un nuovo metodo di autenticazione interattiva di Microsoft Entra, che supporta l'autenticazione a più fattori, è stato introdotto nella versione 17.1 del Driver ODBC per Windows. Un nuovo metodo di autenticazione dell'identità gestita di Microsoft Entra è stato aggiunto nella versione del driver ODBC 17.3.1.1 per le identità assegnate dall'utente e dal sistema. Tutte queste opzioni sono realizzate usando le nuove parole chiave DSN e per la stringa di connessione, nonché gli attributi di connessione.

Per usare l'autenticazione di Microsoft Entra, è necessario configurare l'origine dati Azure SQL. Per altre informazioni, vedere Configurare e gestire l'autenticazione di Microsoft Entra con Azure SQL.

Parole chiave della stringa di connessione e DSN nuovi e/o modificati

È possibile usare la parola chiave Authentication quando ci si connette con un DSN o una stringa di connessione per controllare la modalità di autenticazione. Il valore impostato nella stringa di connessione sostituisce il valore nel DSN, se specificato. Il valore pre-attributo dell'impostazione Authentication è il valore calcolato in base ai valori della stringa di connessione e del DSN.

Attributi di connessione nuovi e/o modificati

Per supportare l'autenticazione di Microsoft Entra sono stati introdotti o modificati i seguenti attributi di preconnessione. Quando un attributo di connessione ha una parola chiave della stringa di connessione o del DSN corrispondente e viene impostato, l'attributo di connessione ha la precedenza.

La funzionalità ActiveDirectoryPassword è 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. Nella maggior parte degli scenari sono disponibili alternative più sicure e consigliate. 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.

Aggiunte dell'interfaccia utente per Microsoft Entra ID (solo driver di Windows)

La configurazione del DSN e le interfacce utente di connessione del driver sono state migliorate con le opzioni aggiuntive necessarie per l'eseguire l'autenticazione con Microsoft Entra ID.

Creazione e modifica dei DSN nell'interfaccia utente

È possibile usare le nuove opzioni di autenticazione di Microsoft Entra quando si crea o si modifica un DSN esistente usando l'interfaccia utente di installazione del driver:

Authentication=ActiveDirectoryIntegrated per l'autenticazione integrata di Microsoft Entra con Azure SQL

Authentication=ActiveDirectoryPassword per l’autenticazione con nome utente/password di Microsoft Entra in Azure SQL

Authentication=ActiveDirectoryInteractive per l’autenticazione interattiva di Microsoft Entra in Azure SQL

Authentication=SqlPassword per l'autenticazione con nome utente/password in SQL Server e Azure SQL

Trusted_Connection=Yes per l'autenticazione integrata SSPI di tipo legacy su Windows

Authentication=ActiveDirectoryMsi per l’autenticazione dell’identità gestita di Microsoft Entra

Authentication=ActiveDirectoryServicePrincipal per l'autenticazione del principale del servizio di Microsoft Entra

Le sette opzioni corrispondono a Trusted_Connection=Yes (autenticazione integrata con solo SSPI di Windows legacy esistente) e Authentication=, ActiveDirectoryIntegrated, SqlPassword, ActiveDirectoryPassword, ActiveDirectoryInteractive, ActiveDirectoryMsi e ActiveDirectoryServicePrincipal, rispettivamente.

Prompt di SQLDriverConnect (solo per driver Windows)

La finestra di dialogo di richiesta visualizzata da SQLDriverConnect quando richiede le informazioni necessarie per completare la connessione contiene quattro nuove opzioni per l'autenticazione di Azure AD:

Queste opzioni corrispondono alle sei opzioni disponibili nell'interfaccia utente di configurazione del DSN descritta in precedenza.

Esempi di stringhe di connessione

1. Autenticazione di SQL Server - sintassi legacy. Il certificato del server non viene convalidato e la crittografia viene usata solo se viene imposta dal server. Nome utente e password vengono passati nella stringa di connessione.

   server=Server;database=Database;UID=UserName;PWD=<password>;Encrypt=no;TrustServerCertificate=yes;

2. Autenticazione SQL - nuova sintassi. Utilizzando Authentication=SqlPassword e omettendo la crittografia come mostrato, i driver 17 e 18 richiedono automaticamente la crittografia a sessione completa. Il driver valida il certificato server con l'impostazione predefinita TrustServerCertificate=no. Il nome utente e la password sono nella stringa di connessione.

   server=Server;database=Database;UID=UserName;PWD=<password>;Authentication=SqlPassword;

3. Autenticazione integrata di Windows (Kerberos in Linux e macOS) tramite SSPI (in SQL Server o SQL IaaS) - sintassi corrente. Con Encrypt=no, la crittografia a sessione completa viene utilizzata solo se il server la richiede. Per quella richiesta solo per il server, il Driver 17 non seleziona la normale validazione del certificato; Il Driver 18 valida con il valore TrustServerCertificate=nopredefinito .

   server=Server;database=Database;Trusted_Connection=yes;Encrypt=no;

4. (Solo per driver di Windows.) Autenticazione integrata di Windows tramite SSPI (se il database di destinazione è in SQL Server o SQL Server in Azure VM) - nuova sintassi. Utilizzando Authentication=ActiveDirectoryIntegrated e omettendo la crittografia come mostrato, i driver 17 e 18 richiedono automaticamente la crittografia a sessione completa. Il driver valida il certificato server con l'impostazione predefinita TrustServerCertificate=no.

   server=Server;database=Database;Authentication=ActiveDirectoryIntegrated;

5. Autenticazione di nome utente e password Microsoft Entra (se il database target si trova in database SQL di Azure o Istanza gestita di SQL di Azure). La richiesta esplicita Encrypt=yes richiede la crittografia dell'intera sessione. Il driver valida il certificato del server con l'impostazione predefinita TrustServerCertificate=no. Il nome utente e la password sono nella stringa di connessione.

   Nota

   "ActiveDirectoryPassword" è obsoleto. Per ulteriori informazioni, vedere ActiveDirectoryPassword è deprecato.

   server=Server;database=Database;UID=UserName;PWD=<password>;Authentication=ActiveDirectoryPassword;Encrypt=yes;

6. (Windows, e versioni Linux/macOS 17.6 e successive, solo driver.) Autenticazione Windows integrata tramite ADAL o Kerberos, che consiste nel riscattare le credenziali dell'account Windows per un token di accesso Microsoft Entra, supponendo che il database di destinazione sia in Azure SQL. La richiesta esplicita Encrypt=yes richiede la crittografia per l'intera sessione. Il driver valida il certificato del server con l'impostazione predefinita TrustServerCertificate=no. In Linux/macOS è necessario che sia disponibile un ticket Kerberos appropriato. Per maggiori informazioni, vedi Considerazioni per l'uso degli account federati ADFS su Linux/macOS e Utilizzo dell'Autenticazione Integrata.

   server=Server;database=Database;Authentication=ActiveDirectoryIntegrated;Encrypt=yes;

7. (Solo driver Windows.) Microsoft Entra Interactive Authentication utilizza la tecnologia di autenticazione multifattore Microsoft Entra per stabilire una connessione. Puoi omettere UID con il driver 17.8 e versioni successive, oppure impostarlo sull'account utente per l'autenticazione. Quando fornisci UID, la finestra di accesso potrebbe non offrire un modo per selezionare un altro account. Per usare un altro account, modifica UID prima di connetterti, oppure omettilo con Driver 17.8 e versioni successive. Il driver apre una finestra di dialogo di Autenticazione Azure affinché l'utente possa completare eventuali verifiche aggiuntive.

   server=Server;database=Database;UID=UserName;Authentication=ActiveDirectoryInteractive;Encrypt=yes;

   

8. L'autenticazione con identità gestita di Microsoft Entra può usare un'identità gestita assegnata dal sistema o assegnata dall'utente. Per un'identità assegnata dall'utente, impostare UID sull'ID client dell'identità per Servizio app di Azure o Azure Container Instance; in caso contrario, usare il relativo ID oggetto. Per l'identità assegnata dal sistema, non è obbligatorio l’UID.

   Per l'identità assegnata dal sistema:

   server=Server;database=Database;Authentication=ActiveDirectoryMsi;Encrypt=yes;

   Per l'identità assegnata dall'utente con ID oggetto uguale a myObjectId:

   server=Server;database=Database;UID=myObjectId;Authentication=ActiveDirectoryMsi;Encrypt=yes;

9. Autenticazione del principale di servizio di Microsoft Entra

   server=Server;database=Database;UID=clientId;PWD=<password>;Authentication=ActiveDirectoryServicePrincipal;Encrypt=yes;

Osservazioni:

• Quando si usano le opzioni di Microsoft Entra con il driver ODBC di Windows con una versione precedente alla 17.4.2, assicurarsi che sia stata eseguita l'installazione di Active Directory Authentication Library per SQL Server. Quando si usano i driver Linux e macOS, assicurarsi che libcurl sia stato installato. Per la versione del driver 17.2 e versioni successive, questa non è una dipendenza esplicita poiché non è necessaria per gli altri metodi di autenticazione o per le operazioni ODBC.

• Quando la configurazione di Microsoft Entra include criteri di accesso condizionale e il client è Windows 10 o Server 2016 o versione successiva, l'autenticazione integrata o tramite nome utente/password potrebbe non riuscire. I criteri di accesso condizionale richiedono l'uso del servizio Gestione account Web (WAM, Web Account Manager), supportato nella versione 17.6 del driver o successiva per Windows. Per usare WAM, creare un nuovo valore stringa denominato ADALuseWAM in HKLM\Software\ODBC\ODBCINST.INI\ODBC Driver 17 for SQL Server, HKCU\Software\ODBC\ODBC.INI\<your-user-DSN-name> o HKLM\Software\ODBC\ODBC.INI\<your-system-DSN-name> per la configurazione globale, DSN utente o con ambito DSN di sistema rispettivamente e impostarlo su un valore pari a 1. Si noti che l'autenticazione con WAM non supporta l'esecuzione dell'applicazione come utente diverso con runas. Gli scenari che richiedono criteri di accesso condizionale non sono supportati per Linux o macOS.

• Per connettersi usando il nome utente e la password di un account SQL Server, è ora possibile usare la nuova opzione SqlPassword, che è consigliata in particolare per Azure SQL poiché abilita impostazioni predefinite della connessione più sicure.

• Per connettersi usando il nome utente e la password di un account Microsoft Entra, specificare Authentication=ActiveDirectoryPassword nella stringa di connessione e le parole chiave UID e PWD rispettivamente con nome utente e password.

  Nota

  "ActiveDirectoryPassword" è obsoleto. Per ulteriori informazioni, vedere ActiveDirectoryPassword è deprecato.

• Per connettersi usando l'autenticazione integrata di Windows o di Microsoft Entra (solo con driver Windows e Linux/macOS 17.6+), specificare Authentication=ActiveDirectoryIntegrated nella stringa di connessione. Il driver sceglierà automaticamente la modalità di autenticazione corretta. Per le versioni del driver 17.7 o precedenti, non specificare UID e PWD. A partire dal driver versione 17.8, gli elementi UID e PWD vengono ignorati.

• Per connetterti usando l'autenticazione interattiva Microsoft Entra (solo driver Windows), puoi omettere il parametro UID con il driver 17.8 e versioni successive, oppure impostarlo sull'account utente per l'autenticazione. La finestra di accesso potrebbe non permetterti di cambiare account quando fornisci UID. Per usare un altro account, modifica il valore di UID prima di connetterti, oppure omettilo con Driver 17.8 e versioni successive. Le versioni del driver 17.7 e precedenti richiedono UID e vietano PWD. A partire dal driver versione 17.8, l'elemento PWD viene ignorato.

• A partire dalla versione 18.1, Trusted_Connection=Yes non usa più come impostazione predefinita l'autenticazione federata di Microsoft Entra ID, bensì l'autenticazione integrata con SSPI. Per usare Microsoft Entra ID per questa opzione, è necessario configurare TrustedConnection_UseAAD=Yes.

• Le versioni del driver ODBC 17.7 e precedenti presentano un problema noto con il timeout della connessione quando in un'istanza di SQL Server sono abilitate l'autenticazione di Microsoft Entra e la crittografia forzata. Il log degli errori di SQL Server può contenere messaggi di errore, come: "Errore: 33155, gravità: 20, stato: 1. È stato generato un evento di disconnessione mentre il server è in attesa del token di autenticazione federata. Ciò potrebbe essere dovuto alla chiusura del client o al timeout scaduto del server”. Se si usano soluzioni a disponibilità elevata, ad esempio gruppi di disponibilità Always On o istanze del cluster di failover, la comunicazione interna del cluster per SQL Server può essere influenzata da questo comportamento, che può influire sulla disponibilità delle risorse. Nel log del cluster potrebbero essere visualizzati messaggi di errore, come: [hadrag] Connect to SQL Server ...ODBC Error: [HY000] [Microsoft][ODBC Driver 17 for SQL Server]An unknown error has occurred. Detailed error information is not available. (0). Le versioni del driver ODBC 17.10 e successive risolvono questo problema e con SQL Server 2022 GDR KB5021522 /CU1 KB5022375, con l'installazione di SQL Server viene installato il driver più recente che contiene questa correzione. È possibile verificare quale versione del driver ODBC hai installato consultando l'amministratore origine dati ODBC.

• A partire dalla versione 18.3 del driver ODBC, l'autenticazione dell'identità gestita (ActiveDirectoryMSI) è supportata in Azure Arc e Azure Cloud Shell.

Autenticazione con un token di accesso

L'attributo di preconnessione SQL_COPT_SS_ACCESS_TOKEN consente di usare un token di accesso ottenuto da Microsoft Entra ID per l'autenticazione anziché nome utente e password e ignora anche la negoziazione e il recupero di un token di accesso da parte del driver. Per usare un token di accesso, impostare l'attributo di connessione SQL_COPT_SS_ACCESS_TOKEN su un puntatore a una struttura ACCESSTOKEN:

typedef struct AccessToken
{
    DWORD dataSize;
    BYTE data[];
} ACCESSTOKEN;

ACCESSTOKEN è una struttura a lunghezza variabile costituita da una lunghezza di 4 byte seguita da byte lunghezza di dati opachi che formano il token di accesso. A causa del modo in cui SQL Server gestisce i token di accesso, un token ottenuto tramite una risposta JSON OAuth 2.0 deve essere espanso in modo che ogni byte sia seguito da un byte di aggiunta di zero prima del numero, analogamente a una stringa UCS-2 contenente solo caratteri ASCII. Il token, tuttavia, è un valore opaco e la lunghezza specificata, in byte, NON deve includere alcun carattere di terminazione Null. A causa dei vincoli di lunghezza e di formato considerevoli, questo metodo di autenticazione è disponibile solo a livello di codice tramite l'attributo di connessione SQL_COPT_SS_ACCESS_TOKEN.

Devi mantenere ACCESSTOKEN assegnato per tutto il tempo che l'handle di connessione sarà assegnato. Altrimenti, potrebbero verificarsi violazioni di accesso. Quando usi il Windows ODBC Driver Manager, il puntatore del token fa parte della chiave del pool di connessione, quindi un puntatore diverso seleziona un pool diverso. Mantieni il buffer associato alla stessa identità quando sostituisci un token scaduto. Aggiornare il buffer non cambia l'identità di una connessione già autenticata.

Non è disponibile alcuna parola chiave per la stringa di connessione o DSN corrispondente. La stringa di connessione non deve contenere le parole chiave UID, PWD, Authentication o Trusted_Connection.

Codice di esempio di autenticazione in Microsoft Entra

L'esempio seguente mostra il codice necessario per connettersi a SQL Server usando Microsoft Entra ID con le parole chiave di connessione. Non è necessario modificare il codice dell'applicazione. La stringa di connessione o il DSN, se usato, è l'unica modifica necessaria per usare Microsoft Entra ID per l'autenticazione:

    ...
    SQLCHAR connString[] = "Driver={ODBC Driver 18 for SQL Server};Server={server};UID=myuser;PWD=<password>;Authentication=ActiveDirectoryInteractive;Encrypt=yes;"
    ...
    SQLDriverConnect(hDbc, NULL, connString, SQL_NTS, NULL, 0, NULL, SQL_DRIVER_NOPROMPT);
    ...

L'esempio seguente mostra il codice necessario per connettersi a SQL Server usando Microsoft Entra con l'autenticazione con token di accesso. In questo caso, è necessario modificare il codice dell'applicazione per elaborare il token di accesso e impostare l'attributo di connessione associato.

    SQLCHAR connString[] = "Driver={ODBC Driver 18 for SQL Server};Server={server};Encrypt=yes;"
    SQLCHAR accessToken[] = "eyJ0eXAiOi..."; // In the format extracted from an OAuth JSON response
    ...
    DWORD dataSize = 2 * strlen(accessToken);
    ACCESSTOKEN *pAccToken = malloc(sizeof(ACCESSTOKEN) + dataSize);
    pAccToken->dataSize = dataSize;
    // Expand access token with padding bytes
    for(int i = 0, j = 0; i < dataSize; i += 2, j++) {
        pAccToken->data[i] = accessToken[j];
        pAccToken->data[i+1] = 0;
    }
    ...
    SQLSetConnectAttr(hDbc, SQL_COPT_SS_ACCESS_TOKEN, (SQLPOINTER)pAccToken, SQL_IS_POINTER);
    SQLDriverConnect(hDbc, NULL, connString, SQL_NTS, NULL, 0, NULL, SQL_DRIVER_NOPROMPT);
    ...
    free(pAccToken);

Di seguito è riportata una stringa di connessione di esempio da usare con l'autenticazione interattiva di Microsoft Entra. Non contiene il campo PWD poiché la password viene immessa usando la schermata di autenticazione di Azure.

SQLCHAR connString[] = "Driver={ODBC Driver 18 for SQL Server};Server={server};UID=myuser;Authentication=ActiveDirectoryInteractive;Encrypt=yes;"

Di seguito è riportata una stringa di connessione di esempio da usare con l'autenticazione di identità gestita di Microsoft Entra. UID è l'ID oggetto/client dell'identità utente quando si usa un'identità assegnata dall'utente.

// For system-assigned identity,
SQLCHAR connString[] = "Driver={ODBC Driver 18 for SQL Server};Server={server};Authentication=ActiveDirectoryMsi;Encrypt=yes;"
...
// For user-assigned identity with object ID equals to myObjectId
SQLCHAR connString[] = "Driver={ODBC Driver 18 for SQL Server};Server={server};UID=myObjectId;Authentication=ActiveDirectoryMsi;Encrypt=yes;"

Considerazioni sull'utilizzo di account federati ADFS in Linux/macOS

A partire dalla versione 17.6, i driver per Linux e macOS supportano l'autenticazione con account federati ADFS tramite l'uso di nome utente/password (ActiveDirectoryPassword) o Kerberos (ActiveDirectoryIntegrated). Sono presenti alcune limitazioni che dipendono dalla piattaforma quando si usa la modalità integrata.

Quando si esegue l'autenticazione con un utente il cui suffisso UPN è diverso dall'area di autenticazione Kerberos, ovvero viene usato un suffisso UPN alternativo, è necessario usare l'opzione di entità di sicurezza aziendale (usare l'opzione -E con kinit e specificare il nome dell'entità di sicurezza nel formato user@federated-domain) quando si ottengono i ticket Kerberos. In questo modo, il driver può determinare correttamente sia il dominio federato che l'area di autenticazione Kerberos.

È possibile verificare che sia disponibile un ticket Kerberos appropriato controllando l'output del comando klist. Se il dominio federato corrisponde all'ambito Kerberos e al suffisso UPN, il nome principale avrà il formato user@realm. Se è diverso, il nome principale dovrebbe essere di formato user@federated-domain@realm.

Linux

In SUSE 11, la versione predefinita della libreria Kerberos 1.6.x non supporta l'opzione Principal di Enterprise necessaria per usare suffissi UPN alternativi. Per usare suffissi UPN alternativi con autenticazione integrata di Microsoft Entra, aggiornare la libreria Kerberos a 1.7 o versione successiva.

In Alpine Linux l'elemento libcurl predefinito non supporta l'autenticazione SPNEGO/Kerberos necessaria per l'autenticazione integrata di Microsoft Entra.

macOS

La libreria Kerberos di sistema kinit supporta il Principal enterprise con l'opzione --enterprise, ma esegue anche in modo implicito la canonicalizzazione dei nomi, che impedisce l'uso di suffissi UPN alternativi. Per usare suffissi UPN alternativi con l'autenticazione integrata di Microsoft Entra, installare una libreria Kerberos più recente tramite brew install krb5 e usare il relativo kinit con l'opzione -E come descritto in precedenza.

Contenuto correlato

• Supporto dell'autenticazione basata su token per il database SQL di Azure tramite l'autenticazione di Microsoft Entra
• Uso dell'autenticazione integrata