Condividi tramite


Connettersi usando l'autenticazione di Microsoft Entra

Scaricare il driver JDBC

Questo articolo offre informazioni su come sviluppare applicazioni Java che usano la funzionalità di autenticazione di Microsoft Entra con Microsoft JDBC Driver per SQL Server.

L'autenticazione di Microsoft Entra è un meccanismo di connessione al database SQL di Azure,all'Istanza gestita di SQL di Azure e ad Azure Synapse Analytics usando le identità in Microsoft Entra ID. Usare l'autenticazione di Microsoft Entra per gestire centralmente le identità degli utenti del database e come alternativa all'autenticazione di SQL Server. Il driver JDBC consente di specificare le credenziali di Microsoft Entra nella stringa di connessione JDBC per connettersi ad Azure SQL. Per informazioni su come configurare l'autenticazione di Microsoft Entra, vedere Connessione ad Azure SQL tramite l'autenticazione di Microsoft Entra.

Le proprietà di connessione per supportare l'autenticazione di Microsoft Entra in Microsoft JDBC Driver per SQL Server sono le seguenti:

  • authentication: usare questa proprietà per specificare il metodo di autenticazione SQL da usare per la connessione. I valori possibili sono:
    • ActiveDirectoryManagedIdentity

      • A partire dalla versione del driver 8.3.1, authentication=ActiveDirectoryMSI consente di connettersi a un database SQL di Azure o a Synapse Analytics da una risorsa di Azure con il supporto per le identità abilitato. Facoltativamente, nelle proprietà Connection/DataSource è possibile specificare msiClientId insieme a questa modalità di autenticazione. msiClientId deve contenere l'ID del client di un'identità gestita da usare per acquisire il valore di accessToken per stabilire la connessione. A partire dalla versione del driver v12.2, authentication=ActiveDirectoryManagedIdentity consente di connettersi a un database SQL di Azure o a Synapse Analytics da una risorsa di Azure con il supporto per le identità abilitato. Facoltativamente, anche l'ID client di un'identità gestita può essere impostato nella proprietà user. Per altre informazioni, vedere Connettersi tramite la modalità di autenticazione ActiveDirectoryManagedIdentity.
    • ActiveDirectoryDefault

    • ActiveDirectoryIntegrated

      • A partire dalla versione del driver 6.0, authentication=ActiveDirectoryIntegrated consente di connettersi ad Azure SQL o a Synapse Analytics tramite l'autenticazione integrata. Per usare questa modalità di autenticazione, è necessaria la federazione di Active Directory Federation Services (ADFS) locale con Microsoft Entra ID nel cloud. Al termine della configurazione, è possibile connettersi aggiungendo la libreria nativa mssql-jdbc_auth-<version>-<arch>.dll al percorso della classe dell'applicazione su Windows o impostando un ticket Kerberos per il supporto dell'autenticazione multipiattaforma. È possibile accedere ad Azure SQL/Azure Synapse Analytics senza che vengano richieste le credenziali quando si è connessi a un computer aggiunto al dominio. Per altre informazioni, vedere la sezione Connettersi tramite la modalità di autenticazione ActiveDirectoryIntegrated.
    • ActiveDirectoryPassword

    • ActiveDirectoryInteractive

    • ActiveDirectoryServicePrincipal

      • A partire dalla versione del driver 9.2, authentication=ActiveDirectoryServicePrincipal consente di connettersi ad Azure SQL o a Synapse Analytics specificando l'ID dell'applicazione o del client nella proprietà userName e il segreto di un'identità dell'entità servizio nella proprietà password. Per altre informazioni, vedere la sezione Connettersi tramite la modalità di autenticazione ActiveDirectoryServicePrincipal.
    • ActiveDirectoryServicePrincipalCertificate

      • A partire dalla versione del driver 12.4, authentication=ActiveDirectoryServicePrincipalCertificate consente di connettersi a un database SQL di Azure o a Synapse Analytics specificando l'ID dell'applicazione o del client nella proprietà userName e il percorso del certificato dell'entità servizio nella proprietà clientCertificate. Per altre informazioni, vedere la sezione Connettersi tramite la modalità di autenticazione ActiveDirectoryServicePrincipalCertificate.
    • SqlPassword

      • Usare authentication=SqlPassword per connettersi a SQL Server usando le proprietà userName/user e password.
    • NotSpecified

      • Usare authentication=NotSpecified o lasciare l'impostazione predefinita quando nessuno di questi metodi di autenticazione è necessario.
    • accessToken: usare questa proprietà di connessione per connettersi a un database SQL con un token di accesso. accessToken può essere impostato solo usando il parametro Proprietà del metodo getConnection() nella classe DriverManager. Non può essere usata nell'URL della connessione.

Per altre informazioni, vedere la proprietà di autenticazione nella pagina Impostazione delle proprietà delle connessioni.

Requisiti di installazione del client

Oltre ai requisiti di sistema del driver di base, le seguenti modalità di autenticazione hanno più requisiti.

Nella tabella seguente sono elencate le dipendenze della libreria necessarie per ogni modalità di autenticazione e versione del driver. Sono necessarie anche le dipendenze delle dipendenze.

Nota

Nei casi in cui l'aggiornamento rapido per una versione principale ha una versione di dipendenza diversa rispetto alla versione principale, viene elencato anche l'aggiornamento rapido.

Opzione di autenticazione Versioni dei driver Dipendenze libreria
ActiveDirectoryPassword
ActiveDirectoryIntegrated
6.0 Adal4j 1.3.0
ActiveDirectoryPassword
ActiveDirectoryIntegrated
6.2.2 - 6.4 Adal4j 1.4.0
ActiveDirectoryPassword
ActiveDirectoryIntegrated
7.0 Adal4j 1.6.0
ActiveDirectoryPassword
ActiveDirectoryIntegrated
7.2 Adal4j 1.6.3
Client-Runtime-for-AutoRest 1.6.5
ActiveDirectoryPassword
ActiveDirectoryIntegrated
7.4 - 8.2 Adal4jl4j 1.6.4
Client-Runtime-for-AutoRest 1.7.0
ActiveDirectoryPassword
ActiveDirectoryIntegrated
8.4 Adal4j 1.6.5
Client-Runtime-for-AutoRest 1.7.4
ActiveDirectoryPassword
ActiveDirectoryIntegrated
ActiveDirectoryInteractive
ActiveDirectoryServicePrincipal
9.2 msal4j 1.7.1
ActiveDirectoryPassword
ActiveDirectoryIntegrated
ActiveDirectoryInteractive
ActiveDirectoryServicePrincipal
9.4 msal4j 1.10.1
ActiveDirectoryPassword
ActiveDirectoryIntegrated
ActiveDirectoryInteractive
ActiveDirectoryServicePrincipal
10,2 msal4j 1.11.0
ActiveDirectoryPassword
ActiveDirectoryIntegrated
ActiveDirectoryInteractive
ActiveDirectoryServicePrincipal
11.2 msal4j 1.11.3
ActiveDirectoryPassword
ActiveDirectoryIntegrated
ActiveDirectoryInteractive
ActiveDirectoryServicePrincipal
11.2.3 msal4j 1.13.0
ActiveDirectoryPassword
ActiveDirectoryIntegrated
ActiveDirectoryInteractive
ActiveDirectoryServicePrincipal
12,2 msal4j 1.13.3
ActiveDirectoryManagedIdentity
ActiveDirectoryMSI
ActiveDirectoryDefault
12,2 azure-identity 1.7.0
ActiveDirectoryPassword
ActiveDirectoryIntegrated
ActiveDirectoryInteractive
ActiveDirectoryServicePrincipal
ActiveDirectoryServicePrincipalCertificate
12.4 msal4j 1.13.8
ActiveDirectoryManagedIdentity
ActiveDirectoryMSI
ActiveDirectoryDefault
12.4 azure-identity 1.9.0
ActiveDirectoryPassword
ActiveDirectoryIntegrated
ActiveDirectoryInteractive
ActiveDirectoryServicePrincipal
ActiveDirectoryServicePrincipalCertificate
12.6 msal4j 1.14.1
ActiveDirectoryManagedIdentity
ActiveDirectoryMSI
ActiveDirectoryDefault
12.6 azure-identity 1.11.1
ActiveDirectoryPassword
ActiveDirectoryIntegrated
ActiveDirectoryInteractive
ActiveDirectoryServicePrincipal
ActiveDirectoryServicePrincipalCertificate
12.6.3 msal4j 1.15.1
ActiveDirectoryManagedIdentity
ActiveDirectoryMSI
ActiveDirectoryDefault
12.6.3 azure-identity 1.12.2
ActiveDirectoryPassword
ActiveDirectoryIntegrated
ActiveDirectoryInteractive
ActiveDirectoryServicePrincipal
ActiveDirectoryServicePrincipalCertificate
12.6.4 msal4j 1.15.1
ActiveDirectoryManagedIdentity
ActiveDirectoryMSI
ActiveDirectoryDefault
12.6.4 azure-identity 1.12.2
ActiveDirectoryPassword
ActiveDirectoryIntegrated
ActiveDirectoryInteractive
ActiveDirectoryServicePrincipal
ActiveDirectoryServicePrincipalCertificate
12.8 msal4j 1.15.1
ActiveDirectoryManagedIdentity
ActiveDirectoryMSI
ActiveDirectoryDefault
12.8 azure-identity 1.12.2

Connettersi tramite la modalità di autenticazione ActiveDirectoryManagedIdentity

Questa modalità di autenticazione è supportata a partire dalla versione 7.2. Per usarla, specificare authentication=ActiveDirectoryMSI. A partire dalla versione 12.2, è possibile specificare anche authentication=ActiveDirectoryManagedIdentity.

Oltre ai requisiti di dipendenza della libreria elencati in Requisiti di configurazione del client, questa funzionalità presenta i seguenti requisiti:

L'esempio seguente illustra come usare la modalità authentication=ActiveDirectoryManagedIdentity. Eseguire questo esempio dall'interno di una risorsa di Azure configurata per l'identità gestita.

Per eseguire l'esempio, sostituire il nome del server o del database con il nome del proprio server o del database nelle righe seguenti:

ds.setServerName("msentra-managed-demo.database.windows.net"); // replace 'msentra-managed-demo' with your server name
ds.setDatabaseName("demo"); // replace with your database name
//Optional
ds.setMSIClientId("<managed_identity_client>"); // Replace with Client ID of user-assigned managed identity to be used

Esempio di utilizzo della modalità di autenticazione ActiveDirectoryMSI:

import java.sql.Connection;
import java.sql.ResultSet;
import java.sql.Statement;

import com.microsoft.sqlserver.jdbc.SQLServerDataSource;

public class MsEntraMSI {
    public static void main(String[] args) throws Exception {

        SQLServerDataSource ds = new SQLServerDataSource();
        ds.setServerName("msentra-managed-demo.database.windows.net"); // Replace with your server name
        ds.setDatabaseName("demo"); // Replace with your database name
        ds.setAuthentication("ActiveDirectoryMSI");
        // Optional
        ds.setMSIClientId("<managed_identity_client_guid>"); // Replace with Client ID of user-assigned managed identity to be used

        try (Connection connection = ds.getConnection();
                Statement stmt = connection.createStatement();
                ResultSet rs = stmt.executeQuery("SELECT SUSER_SNAME()")) {
            if (rs.next()) {
                System.out.println("You have successfully logged on as: " + rs.getString(1));
            }
        }
    }
}

L'esempio seguente illustra come usare la modalità authentication=ActiveDirectoryManagedIdentity.

import java.sql.Connection;
import java.sql.ResultSet;
import java.sql.Statement;

import com.microsoft.sqlserver.jdbc.SQLServerDataSource;

public class MSEntraManagedIdentity {
    public static void main(String[] args) throws Exception {

        SQLServerDataSource ds = new SQLServerDataSource();
        ds.setServerName("msentra-managed-demo.database.windows.net"); // Replace with your server name
        ds.setDatabaseName("demo"); // Replace with your database name
        ds.setAuthentication("ActiveDirectoryManagedIdentity"); // ActiveDirectoryManagedIdentity for JDBC driver version v12.2.0+
        // Optional
        ds.setUser("<managed_identity_client>"); // Replace with Client ID of User-Assigned Managed Identity to be used

        try (Connection connection = ds.getConnection();
                Statement stmt = connection.createStatement();
                ResultSet rs = stmt.executeQuery("SELECT SUSER_SNAME()")) {
            if (rs.next()) {
                System.out.println("You have successfully logged on as: " + rs.getString(1));
            }
        }
    }
}

L'esecuzione di questo esempio in una macchina virtuale di Azure consente di recuperare un token di accesso dall'identità gestita assegnata dal sistema o dall'identità gestita assegnata dall'utente (se msiClientId o user è specificato con un ID client di un'identità gestita) e stabilisce una connessione con il token di accesso recuperato. Se viene stabilita una connessione, verrà visualizzato il messaggio seguente:

You have successfully logged on as: <your Managed Identity username>

Connettersi tramite la modalità di autenticazione ActiveDirectoryDefault

L'opzione di autenticazione ActiveDirectoryDefault usa l'implementazione DefaultAzureCredential concatenata TokenCredential della libreria client di Identità di Azure. La credenziale combina i metodi di autenticazione più comuni concatenati tra loro.

L'autenticazione ActiveDirectoryDefault richiede una dipendenza in fase di esecuzione dalla libreria client di Identità di Azure per l'identità gestita. Per informazioni dettagliate sulla versione della libreria, vedere Requisiti di configurazione del client.

La tabella seguente elenca la catena di credenziali DefaultAzureCredential per ogni versione del driver JDBC.

Versione driver Documentazione sulla versione di azure-identity catena DefaultAzureCredential
12,2 azure-identity 1.7.0 Ambiente
Identità gestita
IntelliJ
Interfaccia della riga di comando di Azure
Azure PowerShell
12.4 azure-identity 1.9.0 Ambiente
Identità del carico di lavoro
Identità gestita
Azure Developer CLI
IntelliJ
Interfaccia della riga di comando di Azure
Azure PowerShell
12.6 azure-identity 1.11.1 Ambiente
Identità del carico di lavoro
Identità gestita
Azure Developer CLI
IntelliJ
Interfaccia della riga di comando di Azure
Azure PowerShell
12.8 azure-identity 1.12.2 Ambiente
Identità del carico di lavoro
Identità gestita
Azure Developer CLI
IntelliJ
Interfaccia della riga di comando di Azure
Azure PowerShell

Esistono molte variabili che possono essere impostate per configurare la credenziale Environment. Per informazioni dettagliate sulla configurazione della catenaDefaulAzureCredential, inclusa la credenziale Environment, vedere la versione pertinente della documentazione azure-identity collegata nella tabella precedente.

Per usare IntellijCredential su Windows, impostare la variabile di ambiente INTELLIJ_KEEPASS_PATH sul percorso del file keepass. Ad esempio: INTELLIJ_KEEPASS_PATH=C:\user\your\path\to\the\keepass\file.

Per fornire più tenant a DefaultAzureCredential, usare la variabile di ambiente ADDITIONALLY_ALLOWED_TENANTS. Questa variabile accetta un elenco delimitato da virgole. Ad esempio, ADDITIONALLY_ALLOWED_TENANTS=<your-tenant-id-0>,<your-tenant-id-1>,<your-tenant-id-2>,...

L'esempio seguente illustra come usare la modalità authentication=ActiveDirectoryDefault con AzureCliCredential all'interno di DefaultAzureCredential.

  1. Accedere innanzitutto all'interfaccia della riga di comando di Azure usando il comando seguente.

    az login
    
  2. Dopo aver eseguito correttamente l'accesso all'interfaccia della riga di comando di Azure, eseguire il codice seguente.

    import java.sql.Connection;
    import java.sql.ResultSet;
    import java.sql.Statement;
    
    import com.microsoft.sqlserver.jdbc.SQLServerDataSource;
    
    public class MSEntraDefault {
        public static void main(String[] args) throws Exception {
    
            SQLServerDataSource ds = new SQLServerDataSource();
            ds.setServerName("msentra-managed-demo.database.windows.net"); // Replace with your server name
            ds.setDatabaseName("demo"); // Replace with your database name
            ds.setAuthentication("ActiveDirectoryDefault");
    
            try (Connection connection = ds.getConnection();
                    Statement stmt = connection.createStatement();
                    ResultSet rs = stmt.executeQuery("SELECT SUSER_SNAME()")) {
                if (rs.next()) {
                    System.out.println("You have successfully logged on as: " + rs.getString(1));
                }
            }
        }
    }
    

Connettersi tramite la modalità di autenticazione ActiveDirectoryIntegrated

Esistono due modi per usare l'autenticazione ActiveDirectoryIntegrated in Microsoft JDBC Driver per SQL Server:

  • In Windows è possibile copiare mssql-jdbc_auth-<version>-<arch>.dll dal pacchetto scaricato in una posizione nel percorso di sistema.
  • Se non è possibile usare la DLL, a partire dalla versione 6.4, è possibile configurare un ticket Kerberos. Questo metodo è supportato su tutte le piattaforme (Windows, Linux e macOS). Per altre informazioni, vedere Impostare un ticket Kerberos in Windows, Linux e macOS.

Assicurarsi di disporre delle librerie dipendenti necessarie secondo i Requisiti di configurazione del client.

L'esempio seguente illustra come usare la modalità authentication=ActiveDirectoryIntegrated. Questo esempio viene eseguito su un computer aggiunto a un dominio federato con Microsoft Entra ID. È necessario che nel database sia presente un utente del database che rappresenta l'utente Windows e che questo abbia l'autorizzazione CONNECT.

Prima di eseguire l'esempio, sostituire il nome del server o database con il nome del proprio server o database nelle righe seguenti:

ds.setServerName("msentra-managed-demo.database.windows.net"); // replace 'msentra-managed-demo' with your server name
ds.setDatabaseName("demo"); // replace with your database name

Esempio di utilizzo della modalità di autenticazione ActiveDirectoryIntegrated:

import java.sql.Connection;
import java.sql.ResultSet;
import java.sql.Statement;

import com.microsoft.sqlserver.jdbc.SQLServerDataSource;

public class MSEntraIntegrated {
    public static void main(String[] args) throws Exception {

        SQLServerDataSource ds = new SQLServerDataSource();
        ds.setServerName("msentra-managed-demo.database.windows.net"); // Replace with your server name
        ds.setDatabaseName("demo"); // Replace with your database name
        ds.setAuthentication("ActiveDirectoryIntegrated");

        try (Connection connection = ds.getConnection();
                Statement stmt = connection.createStatement();
                ResultSet rs = stmt.executeQuery("SELECT SUSER_SNAME()")) {
            if (rs.next()) {
                System.out.println("You have successfully logged on as: " + rs.getString(1));
            }
        }
    }
}

L'esecuzione di questo esempio usa automaticamente il ticket Kerberos dalla piattaforma client e non è richiesta alcuna password. Se viene stabilita una connessione, verrà visualizzato il messaggio seguente:

You have successfully logged on as: <your domain user name>

Impostare un ticket Kerberos in Windows, Linux e macOS

È necessario creare un ticket Kerberos che collega l'utente corrente a un account di dominio di Windows. Di seguito è riportato un riepilogo dei passaggi principali.

Finestre

Nota

In Windows è possibile usare mssql-jdbc_auth-<version>-<arch>.dll dal pacchetto scaricato invece di seguire la procedura di configurazione di Kerberos. Questa procedura è necessaria solo se non è possibile usare la DLL.

JDK include kinit che consente di ottenere un TGT dal Centro distribuzione chiavi (KDC) su un computer aggiunto al dominio federato con Microsoft Entra ID.

Passaggio 1: Recupero del ticket-granting ticket
  • Eseguire su: Windows

  • Azione:

    • Usare il comando kinit username@DOMAIN.COMPANY.COM per ottenere un TGT da KDC. Verrà quindi richiesta la password del dominio.
    • Usare klist per visualizzare i ticket disponibili. Se il comando kinit ha avuto esito positivo, verrà visualizzato un ticket da krbtgt/DOMAIN.COMPANY.COM@ DOMAIN.COMPANY.COM.

    Nota

    Potrebbe essere necessario specificare un file .ini con -Djava.security.krb5.conf per consentire all'applicazione di individuare il KDC.

Linux e macOS

Requisiti

Accesso a un computer aggiunto a un dominio di Windows per eseguire una query sul controller di dominio Kerberos.

Passaggio 1: Trovare il KDC Kerberos
  • Eseguire su: riga di comando di Windows

  • Azione: nltest /dsgetdc:DOMAIN.COMPANY.COM (dove DOMAIN.COMPANY.COM esegue il mapping al nome del dominio)

  • Output di esempio

    DC: \\co1-red-dc-33.domain.company.com
    Address: \\2111:4444:2111:33:1111:ecff:ffff:3333
    ...
    The command completed successfully
    
  • Informazioni da estrarre Il nome DC, in questo caso co1-red-dc-33.domain.company.com

Passaggio 2: Configurare il Centro distribuzione chiavi (KDC) in krb5.conf
  • Eseguire su: Linux/macOS

  • Azione: modificare il file /etc/krb5.conf in un editor di propria scelta. Configurare le chiavi seguenti

    [libdefaults]
      default_realm = DOMAIN.COMPANY.COM
    
    [realms]
    DOMAIN.COMPANY.COM = {
       kdc = co1-red-dc-28.domain.company.com
    }
    

    Quindi salvare il file krb5.conf e uscire

    Nota

    Il dominio deve essere in lettere MAIUSCOLE.

Passaggio 3: Testare il recupero del ticket-granting ticket
  • Eseguire su: Linux/macOS
  • Azione:
    • Usare il comando kinit username@DOMAIN.COMPANY.COM per ottenere un TGT da KDC. Verrà quindi richiesta la password del dominio.
    • Usare klist per visualizzare i ticket disponibili. Se il comando kinit ha avuto esito positivo, verrà visualizzato un ticket da krbtgt/DOMAIN.COMPANY.COM@ DOMAIN.COMPANY.COM.

Connettersi tramite la modalità di autenticazione ActiveDirectoryPassword

L'esempio seguente illustra come usare la modalità authentication=ActiveDirectoryPassword.

Per compilare ed eseguire l'esempio:

  1. Assicurarsi di disporre delle librerie dipendenti necessarie secondo i Requisiti di configurazione del client.

  2. Individuare le righe di codice seguenti e sostituire il nome del server o database con il nome del proprio server o database.

    ds.setServerName("msentra-managed-demo.database.windows.net"); // replace 'msentra-managed-demo' with your server name
    ds.setDatabaseName("demo"); // replace with your database name
    
  3. Individuare le righe di codice seguenti. Sostituire il nome utente con il nome dell'utente di Microsoft Entra che si vuole usare per la connessione.

    ds.setUser("bob@example.com"); // replace with your username
    ds.setPassword("password");     // replace with your password
    

Esempio di utilizzo della modalità di autenticazione ActiveDirectoryPassword:

import java.sql.Connection;
import java.sql.ResultSet;
import java.sql.Statement;

import com.microsoft.sqlserver.jdbc.SQLServerDataSource;

public class MSEntraUserPassword {

    public static void main(String[] args) throws Exception{

        SQLServerDataSource ds = new SQLServerDataSource();
        ds.setServerName("msentra-managed-demo.database.windows.net"); // Replace with your server name
        ds.setDatabaseName("demo"); // Replace with your database
        ds.setUser("bob@example.com"); // Replace with your username
        ds.setPassword("password"); // Replace with your password
        ds.setAuthentication("ActiveDirectoryPassword");

        try (Connection connection = ds.getConnection();
                Statement stmt = connection.createStatement();
                ResultSet rs = stmt.executeQuery("SELECT SUSER_SNAME()")) {
            if (rs.next()) {
                System.out.println("You have successfully logged on as: " + rs.getString(1));
            }
        }
    }
}

Se viene stabilita la connessione, verrà visualizzato il seguente messaggio come output:

You have successfully logged on as: <your user name>

Connettersi tramite la modalità di autenticazione ActiveDirectoryInteractive

L'esempio seguente illustra come usare la modalità authentication=ActiveDirectoryInteractive.

Per compilare ed eseguire l'esempio:

  1. Assicurarsi di disporre delle librerie dipendenti necessarie secondo i Requisiti di configurazione del client.

  2. Individuare le righe di codice seguenti e sostituire il nome del server o database con il nome del proprio server o database.

    ds.setServerName("msentra-managed-demo.database.windows.net"); // replace 'msentra-managed-demo' with your server name
    ds.setDatabaseName("demo"); // replace with your database name
    
  3. Individuare le righe di codice seguenti. Sostituire il nome utente con il nome dell'utente di Microsoft Entra che si vuole usare per la connessione.

    ds.setUser("bob@example.com"); // replace with your username
    

Esempio di utilizzo della modalità di autenticazione ActiveDirectoryInteractive:

import java.sql.Connection;
import java.sql.ResultSet;
import java.sql.Statement;

import com.microsoft.sqlserver.jdbc.SQLServerDataSource;

public class MSEntraInteractive {
    public static void main(String[] args) throws Exception{

        SQLServerDataSource ds = new SQLServerDataSource();
        ds.setServerName("msentra-managed-demo.database.windows.net"); // Replace with your server name
        ds.setDatabaseName("demo"); // Replace with your database
        ds.setAuthentication("ActiveDirectoryInteractive");

        // Optional login hint
        ds.setUser("bob@example.com"); // Replace with your user name

        try (Connection connection = ds.getConnection();
                Statement stmt = connection.createStatement();
                ResultSet rs = stmt.executeQuery("SELECT SUSER_SNAME()")) {
            if (rs.next()) {
                System.out.println("You have successfully logged on as: " + rs.getString(1));
            }
        }
    }
}

Quando si esegue il programma, viene visualizzato un browser per eseguire l'autenticazione dell'utente. Ciò che viene visualizzato esattamente dipende dal modo in cui viene configurato Microsoft Entra ID. Potrebbe o meno includere richieste di nome utente, password, PIN per l'autenticazione a più fattori o una seconda autenticazione del dispositivo tramite un telefono. Se nello stesso programma vengono eseguite più richieste di autenticazione interattive, le richieste successive potrebbero non richiedere se la libreria di autenticazione può riutilizzare un token di autenticazione memorizzato precedentemente nella cache.

Per informazioni su come configurare Microsoft Entra ID per richiedere l'autenticazione a più fattori, vedere Introduzione all'autenticazione a più fattori di Microsoft Entra nel cloud.

Per gli screenshot di queste finestre di dialogo, vedere Uso dell'autenticazione a più fattori di Microsoft Entra.

Se l'autenticazione dell'utente viene completata correttamente, verrà visualizzato il messaggio seguente nel browser:

Authentication complete. You can close the browser and return to the application.

Questo messaggio indica solo che l'autenticazione dell'utente è riuscita, ma non indica necessariamente una connessione riuscita al server. Quando si ritorna all'applicazione, se viene stabilita una connessione al server, verrà visualizzato il messaggio seguente come output:

You have successfully logged on as: <your user name>

Connettersi tramite la modalità di autenticazione ActiveDirectoryServicePrincipal

L'esempio seguente illustra come usare la modalità authentication=ActiveDirectoryServicePrincipal.

Per compilare ed eseguire l'esempio:

  1. Assicurarsi di disporre delle librerie dipendenti necessarie secondo i Requisiti di configurazione del client.

  2. Individuare le righe di codice seguenti e sostituire il nome del server o database con il nome del proprio server o database.

    ds.setServerName("msentra-managed-demo.database.windows.net"); // replace 'msentra-managed-demo' with your server name
    ds.setDatabaseName("demo"); // replace with your database name
    
  3. Individuare le righe di codice seguenti. Sostituire il valore di principalId con l'ID dell'applicazione o l'ID del client dell'entità servizio di Microsoft Entra tramite la quale si vuole eseguire la connessione. Sostituire il valore di principalSecret con il segreto.

    String principalId = "<service_principal_guid>"; // Replace with your Microsoft Entra service principal ID.
    String principalSecret = "..."; // Replace with your Microsoft Entra principal secret.
    
  4. Impostare l'ID dell'entità di sicurezza e il segreto dell'entità di sicurezza usando setUser e setPassword nella versione 10.2 e successive e setAADSecurePrincipalId e setAADSecurePrincipalSecret nella versione 9.4 e successive.

Esempio di utilizzo della modalità di autenticazione ActiveDirectoryServicePrincipal:

import java.sql.Connection;
import java.sql.ResultSet;
import java.sql.Statement;

import com.microsoft.sqlserver.jdbc.SQLServerDataSource;

public class MSEntraServicePrincipal {
    public static void main(String[] args) throws Exception{
        String principalId = "<service_principal_guid>"; // Replace with your Microsoft Entra service principal ID.
        String principalSecret = "..."; // Replace with your Microsoft Entra principal secret.

        SQLServerDataSource ds = new SQLServerDataSource();
        ds.setServerName("msentra-managed-demo.database.windows.net"); // Replace with your server name
        ds.setDatabaseName("demo"); // Replace with your database
        ds.setAuthentication("ActiveDirectoryServicePrincipal");
        ds.setUser(principalId); // setAADSecurePrincipalId for JDBC Driver 9.4 and below
        ds.setPassword(principalSecret); // setAADSecurePrincipalSecret for JDBC Driver 9.4 and below 

        try (Connection connection = ds.getConnection();
                Statement stmt = connection.createStatement();
                ResultSet rs = stmt.executeQuery("SELECT SUSER_SNAME()")) {
            if (rs.next()) {
                System.out.println("You have successfully logged on as: " + rs.getString(1));
            }
        }
    }
}

Se viene stabilita la connessione, verrà visualizzato il messaggio seguente:

You have successfully logged on as: <your app/client ID>

Connettersi tramite la modalità di autenticazione ActiveDirectoryServicePrincipalCertificate

L'esempio seguente illustra come usare la modalità authentication=ActiveDirectoryServicePrincipalCertificate.

Per compilare ed eseguire l'esempio:

  1. Assicurarsi di disporre delle librerie dipendenti necessarie secondo i Requisiti di configurazione del client.

  2. Individuare le righe di codice seguenti e sostituire il nome del server o database con il nome del proprio server o database.

    ds.setServerName("msentra-managed-demo.database.windows.net"); // replace 'msentra-managed-demo' with your server name
    ds.setDatabaseName("demo"); // replace with your database name
    
  3. Individuare le righe di codice seguenti. Sostituire il valore di principalId con l'ID dell'applicazione o l'ID del client dell'entità servizio di Microsoft Entra tramite la quale si vuole eseguire la connessione. Sostituire il valore di clientCertificate con il percorso del certificato dell'entità servizio.

    String principalId = "<service_principal_guid>"; // Replace with your Microsoft Entra service principal ID.
    
    String clientCertificate = "..."; // Replace with the location for your Microsoft Entra service principal certificate.
    
  4. Se il certificato menzionato in precedenza richiede una password, impostare il segreto dell'entità di sicurezza usando setPassword nella versione 10.2 e successive o setAADSecurePrincipalSecret nella versione 9.4 e successive.

  5. Se il certificato ha una chiave privata associata, impostare la chiave privata usando setClientKey. Se questa chiave richiede una password, impostare la password per la chiave privata usando setClientKeyPassword.

Esempio di utilizzo della modalità di autenticazione ActiveDirectoryServicePrincipalCertificate:

import java.sql.Connection;
import java.sql.ResultSet;
import java.sql.Statement;

import com.microsoft.sqlserver.jdbc.SQLServerDataSource;

public class MSEntraServicePrincipalCertificate {
    public static void main(String[] args) throws Exception{
        String principalId = "<service_principal_guid>"; // Replace with your Microsoft Entra service principal ID.
        String clientCertificate = "..."; // Replace with the location of your service principal certificate.

        SQLServerDataSource ds = new SQLServerDataSource();
        ds.setServerName("msentra-managed-demo.database.windows.net"); // Replace with your server name
        ds.setDatabaseName("demo"); // Replace with your database
        ds.setAuthentication("ActiveDirectoryServicePrincipalCertificate");
        ds.setUser(principalId); // setAADSecurePrincipalId for JDBC Driver 9.4 and below
        ds.setClientCertificate(clientCertificate);

        try (Connection connection = ds.getConnection();
             Statement stmt = connection.createStatement();
             ResultSet rs = stmt.executeQuery("SELECT SUSER_SNAME()")) {
            if (rs.next()) {
                System.out.println("You have successfully logged on as: " + rs.getString(1));
            }
        }
    }
}

Se viene stabilita la connessione, verrà visualizzato il messaggio seguente:

You have successfully logged on as: <your app/client ID>

Connettersi tramite il token di accesso

Le applicazioni o i servizi possono recuperare un token di accesso da Microsoft Entra ID e usarlo per connettersi al database SQL di Azure, all'Istanza gestita di SQL di Azure o ad Azure Synapse Analytics.

Nota

accessToken può essere impostato solo usando il parametro Proprietà del metodo getConnection() nella classe DriverManager. Non può essere usato nella stringa di connessione. A partire dalla versione 12.2 del driver, gli utenti possono implementare e fornire una richiamata accessToken al driver per il rinnovo del token negli scenari di pool di connessioni. Gli scenari di pool di connessioni richiedono che l'implementazione del pool di connessioni utilizzi le classi di pool di connessioni JDBC standard.

L'esempio seguente contiene un'applicazione Java semplice che si connette ad Azure usando l'autenticazione basata su token di accesso.

Per compilare ed eseguire l'esempio:

  1. Creare un account dell'applicazione in Microsoft Entra ID per il servizio.

    1. Accedere al portale di Azure.
    2. Passare a Microsoft Entra ID nel riquadro di spostamento a sinistra.
    3. Selezionare Registrazioni app.
    4. Seleziona Nuova registrazione.
    5. Nome: immettere mytokentest come nome descrittivo per l'applicazione.
    6. Mantenere la selezione predefinita per i tipi di account supportati che possono usare l'applicazione.
    7. Selezionare Registra in basso.
    8. L'URL di accesso non è necessario. Specificare qualsiasi elemento: https://mytokentest.
    9. Selezionare Create in basso.
    10. Dopo aver selezionato Registra l'app viene creata immediatamente e viene visualizzata la relativa pagina delle risorse.
    11. Nella casella Essentials, trovare l'ID (client) dell'applicazione e copiarlo. Questo valore sarà necessario in seguito per configurare l'applicazione.
    12. Selezionare Certificati e segreti nel riquadro di spostamento. Nella scheda Segreti client (0) selezionare Nuovo segreto client. Immettere una descrizione per il segreto e selezionare una scadenza (il valore predefinito va bene). Selezionare Aggiungi in basso. Importante prima di uscire da questa pagina, copiare il valore generato per il segreto client. Questo valore non può essere visualizzato dopo aver lasciato la pagina. Questo valore è il segreto client.
    13. Tornare al riquadro Registrazioni app per Microsoft Entra ID e trovare la scheda Endpoint. Copiare l'URL in OAuth 2.0 token endpoint. Questo URL è l'URL del servizio token di sicurezza.

    Endpoint di registrazione delle app nel portale di Azure - URL STS

  2. Connettersi al database come amministratore di Microsoft Entra e usare un comando T-SQL per fornire un utente di database indipendente per l'entità di sicurezza dell'applicazione. Per altre informazioni su come creare un amministratore di Microsoft Entra e un utente di database indipendente, vedere Connessione tramite l'autenticazione di Microsoft Entra.

    CREATE USER [mytokentest] FROM EXTERNAL PROVIDER
    
  3. Nel computer client in cui si esegue l'esempio scaricare la libreria Microsoft Authentication Library (MSAL) per Java e le relative dipendenze. MSAL è necessario solo per eseguire questo esempio specifico. L'esempio usa le API di questa libreria per recuperare il token di accesso da Microsoft Entra ID. Se si dispone già di un token di accesso, è possibile ignorare questo passaggio e rimuovere la sezione nell'esempio che recupera un token di accesso.

Nell'esempio seguente sostituire l'URL STS, l'ID client, il segreto client, il nome del server e del database con i propri valori.

import java.sql.Connection;
import java.sql.ResultSet;
import java.sql.Statement;
import java.util.concurrent.Executors;
import java.util.concurrent.Future;
import com.microsoft.sqlserver.jdbc.SQLServerDataSource;

// The microsoft-authentication-library-for-java is needed to retrieve the access token in this example.
import com.microsoft.aad.msal4j.ClientCredentialFactory;
import com.microsoft.aad.msal4j.ClientCredentialParameters;
import com.microsoft.aad.msal4j.ConfidentialClientApplication;
import com.microsoft.aad.msal4j.IAuthenticationResult;
import com.microsoft.aad.msal4j.IClientCredential;

public class MSEntraTokenBased {

    public static void main(String[] args) throws Exception {

        // Retrieve the access token from Microsoft Entra ID.
        String spn = "https://database.windows.net/";
        String stsurl = "https://login.microsoftonline.com/..."; // Replace with your STS URL.
        String clientId = "<service_principal_guid>"; // Replace with your client ID.
        String clientSecret = "..."; // Replace with your client secret.

        String scope = spn +  "/.default";
        Set<String> scopes = new HashSet<>();
        scopes.add(scope);

        ExecutorService executorService = Executors.newSingleThreadExecutor();
        IClientCredential credential = ClientCredentialFactory.createFromSecret(clientSecret);
        ConfidentialClientApplication clientApplication = ConfidentialClientApplication
            .builder(clientId, credential).executorService(executorService).authority(stsurl).build();
        CompletableFuture<IAuthenticationResult> future = clientApplication
            .acquireToken(ClientCredentialParameters.builder(scopes).build());

        IAuthenticationResult authenticationResult = future.get();
        String accessToken = authenticationResult.accessToken();

        System.out.println("Access Token: " + accessToken);

        // Connect with the access token.
        SQLServerDataSource ds = new SQLServerDataSource();

        ds.setServerName("msentra-managed-demo.database.windows.net"); // Replace with your server name.
        ds.setDatabaseName("demo"); // Replace with your database name.
        ds.setAccessToken(accessToken);

        try (Connection connection = ds.getConnection();
                Statement stmt = connection.createStatement();
                ResultSet rs = stmt.executeQuery("SELECT SUSER_SNAME()")) {
            if (rs.next()) {
                System.out.println("You have successfully logged on as: " + rs.getString(1));
            }
        }
    }
}

Se la connessione viene stabilita correttamente, verrà visualizzato il messaggio seguente:

Access Token: <your access token>
You have successfully logged on as: <your client ID>

Connettersi tramite la richiamata del token di accesso

Analogamente alla proprietà del token di accesso, la richiamata del token di accesso consente di registrare un metodo che fornisce un token di accesso al driver. Il vantaggio di questa richiamata rispetto alla proprietà è che la richiamata consente al driver di richiedere un nuovo token di accesso quando il token è scaduto. Ad esempio, un pool di connessioni che crea una nuova connessione può richiedere un nuovo token con una nuova data di scadenza. Per altre informazioni, vedere Uso del pool di connessioni.

Nell'esempio seguente viene illustrata l'implementazione e l'impostazione della richiamata accessToken.

import com.microsoft.aad.msal4j.IClientCredential;
import com.microsoft.aad.msal4j.ClientCredentialFactory;
import com.microsoft.aad.msal4j.ConfidentialClientApplication;
import com.microsoft.aad.msal4j.IAuthenticationResult;
import com.microsoft.aad.msal4j.ClientCredentialParameters;
import java.sql.Connection;
import java.util.HashSet;
import java.util.Set;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;

public class MSEntraAccessTokenCallback {

    public static void main(String[] args) {

        SQLServerAccessTokenCallback callback = new SQLServerAccessTokenCallback() {
            @Override
            public SqlAuthenticationToken getAccessToken(String spn, String stsurl) {

                String clientSecret = "..."; // Replace with your client secret.
                String clientId = "<service_principal_guid>"; // Replace with your client ID.

                String scope = spn + "/.default";
                Set<String> scopes = new HashSet<>();
                scopes.add(scope);

                try {
                    ExecutorService executorService = Executors.newSingleThreadExecutor();
                    IClientCredential credential = ClientCredentialFactory.createFromSecret(clientSecret);
                    ConfidentialClientApplication clientApplication = ConfidentialClientApplication
                            .builder(clientId, credential).executorService(executorService).authority(stsurl).build();
                    CompletableFuture<IAuthenticationResult> future = clientApplication
                            .acquireToken(ClientCredentialParameters.builder(scopes).build());

                    IAuthenticationResult authenticationResult = future.get();
                    String accessToken = authenticationResult.accessToken();

                    return new SqlAuthenticationToken(accessToken, authenticationResult.expiresOnDate().getTime());
                } catch (Exception e) {
                    e.printStackTrace();
                }
                return null;
            }
        };

        SQLServerDataSource ds = new SQLServerDataSource();
        ds.setServerName("msentra-managed-demo.database.windows.net"); // Replaces with your server name.
        ds.setDatabaseName("demo"); // Replace with your database name.
        ds.setAccessTokenCallback(callback);

        try (Connection connection = ds.getConnection();
                Statement stmt = connection.createStatement();
                ResultSet rs = stmt.executeQuery("SELECT SUSER_SNAME()")) {
            if (rs.next()) {
                System.out.println("You have successfully logged on as: " + rs.getString(1));
            }
        }
    }
}

Se la connessione viene stabilita correttamente, verrà visualizzato il messaggio seguente:

You have successfully logged on as: <your client ID>

A partire dalla versione 12.4, la richiamata accessToken può essere impostata tramite la proprietà stringa di connessione accessTokenCallbackClass. Nell'esempio seguente viene illustrato come impostare la richiamata accessToken usando questa proprietà:

import com.microsoft.aad.msal4j.IClientCredential;
import com.microsoft.aad.msal4j.ClientCredentialFactory;
import com.microsoft.aad.msal4j.ConfidentialClientApplication;
import com.microsoft.aad.msal4j.IAuthenticationResult;
import com.microsoft.aad.msal4j.ClientCredentialParameters;
import java.sql.Connection;
import java.util.HashSet;
import java.util.Set;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;

 

public class MSEntraAccessTokenCallbackClass {
    public static class AccessTokenCallbackClass implements SQLServerAccessTokenCallback {
        @Override
        public SqlAuthenticationToken getAccessToken(String spn, String stsurl) {
            String clientSecret = "..."; // Replace with your client secret.
            String clientId = "<service_principal_guid>"; // Replace with your client ID.
            
            String scope = spn + "/.default";
            Set<String> scopes = new HashSet<>();
            scopes.add(scope);
            
            try {
                ExecutorService executorService = Executors.newSingleThreadExecutor();
                IClientCredential credential = ClientCredentialFactory.createFromSecret(clientSecret);
                ConfidentialClientApplication clientApplication = ConfidentialClientApplication

                        .builder(clientId, credential).executorService(executorService).authority(stsurl).build();
                
                CompletableFuture<IAuthenticationResult> future = clientApplication
                        .acquireToken(ClientCredentialParameters.builder(scopes).build());
                
                IAuthenticationResult authenticationResult = future.get();
                String accessToken = authenticationResult.accessToken();
                
                return new SqlAuthenticationToken(accessToken, authenticationResult.expiresOnDate().getTime());
            } catch (Exception e) {
                e.printStackTrace();
            }
            return null;
        }
    }
    
    public static void main(String[] args) throws Exception {
        
        SQLServerDataSource ds = new SQLServerDataSource();
        ds.setServerName("msentra-managed-demo.database.windows.net"); // Replaces with your server name.
        ds.setDatabaseName("demo"); // Replace with your database name.
        ds.setAccessTokenCallbackClass(AccessTokenCallbackClass.class.getName());
        
        try (Connection connection = ds.getConnection();
             Statement stmt = connection.createStatement();
             ResultSet rs = stmt.executeQuery("SELECT SUSER_SNAME()")) {
            if (rs.next()) {
                System.out.println("You have successfully logged on as: " + rs.getString(1));
            }
        }
    }
}

Se la connessione viene stabilita correttamente, verrà visualizzato il messaggio seguente:

You have successfully logged on as: <your client ID>

Passaggi successivi

Altre informazioni sui concetti correlati sono disponibili negli articoli seguenti: