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 deò Driver ODBC, l'autenticazione del token di accesso di Microsoft Entra è solo 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 disponibili usando le nuove parole chiave per la stringa di connessione e DSN, 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.

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 in 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 con SSPI legacy di Windows

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

Authentication=ActiveDirectoryServicePrincipal per l’autenticazione dell’entità di sicurezza 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 SQLDriverConnect (solo 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. Il client richiede la crittografia (il valore predefinito di Encrypt è true) e il certificato del server viene convalidato, indipendentemente dall'impostazione della crittografia (a meno che il valore di TrustServerCertificate non sia impostato su true). Nome utente e password vengono passati 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. Il certificato del server non viene convalidato, a meno che la crittografia non sia richiesta dal server.

   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. Il client richiede la crittografia (il valore predefinito di Encrypt è true) e il certificato del server viene convalidato, indipendentemente dall'impostazione della crittografia (a meno che il valore di TrustServerCertificate non sia impostato su true).

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

5. Autenticazione con nome utente/password di Microsoft Entra (se il database di destinazione si trova nel database SQL di Azure o nell’Istanza gestita di SQL di Azure). Il certificato del server viene convalidato, indipendentemente dall'impostazione della crittografia (a meno che il valore di TrustServerCertificate non sia impostato su true). Nome utente e password vengono passati nella stringa di connessione.

   server=Server;database=Database;UID=UserName;PWD=Password;Authentication=ActiveDirectoryPassword;Encrypt=yes;

6. (Solo driver Windows, e Linux/macOS 17.6+.) Autenticazione integrata di Windows tramite ADAL o Kerberos, che prevede il riscatto delle credenziali dell'account di Windows per un token di accesso emesso da Microsoft Entra, presupponendo che il database di destinazione si trovi in Azure SQL. Il certificato del server viene convalidato, indipendentemente dall'impostazione della crittografia (a meno che il valore di TrustServerCertificate non sia impostato su true). In Linux/macOS è necessario che sia disponibile un ticket Kerberos appropriato. Per altre informazioni, vedere la sezione seguente sugli account federati e sull'uso dell'autenticazione integrata.

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

7. (Solo driver di Windows.) L’autenticazione interattiva di Microsoft Entra usa la tecnologia di autenticazione a più fattori di Microsoft Entra per configurare la connessione. In questo modo, specificando l'ID di accesso, viene attivata una finestra di dialogo di autenticazione di Azure che consente all'utente di eseguire una verifica aggiuntiva per completare la connessione. Il nome utente viene passato nella stringa di connessione.

   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 il servizio app di Azure o l’istanza di Azure Container. 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 dell’entità servizio di Microsoft Entra

server=Server;database=Database;UID=clientId;PWD=clientSecret;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.

• 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 connettersi usando l'autenticazione interattiva di Microsoft Entra (solo con driver Windows), è necessario specificare UID. Per le versioni del driver 17.7 o precedenti, non specificare 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 la versione del driver ODBC installata facendo 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. 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=myPass;Authentication=ActiveDirectoryPassword;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'area di autenticazione Kerberos e al suffisso UPN, il nome dell'entità di sicurezza avrà il formato user@realm. Se è diverso, il nome dell'entità di sicurezza deve essere nel formato user@federated-domain@realm.

Linux

In SUSE 11, la versione predefinita della libreria Kerberos 1.6.x non supporta l'opzione di entità di sicurezza 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 l'entità di sicurezza aziendale con l'opzione --enterprise, ma esegue anche in modo implicito la canonizzazione 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