Conectar-se usando a autenticação do Microsoft Entra

Baixar driver JDBC

Este artigo fornece informações sobre como desenvolver aplicativos Java que usam o recurso de autenticação Microsoft Entra com o Microsoft JDBC Driver para SQL Server.

Você pode usar a autenticação do Microsoft Entra, que é um mecanismo para se conectar ao Banco de Dados SQL do Azure, à Instância Gerenciada do SQL do Azure e ao Azure Synapse Analytics usando identidades na ID do Microsoft Entra. Use a autenticação do Microsoft Entra para gerenciar centralmente identidades de usuários de banco de dados e como uma alternativa à autenticação do SQL Server. O driver JDBC permite que você especifique suas credenciais do Microsoft Entra na cadeia de conexão JDBC para se conectar ao Azure SQL. Para obter informações sobre como configurar a autenticação do Microsoft Entra, visite Conectando-se ao SQL do Azure usando a autenticação do Microsoft Entra.

As propriedades de conexão para dar suporte à autenticação do Microsoft Entra no Microsoft JDBC Driver for SQL Server são:

• autenticação: Use esta propriedade para indicar qual método de autenticação SQL usar para a conexão. Os valores possíveis são:

  • Identidade Gerida do Active Directory

    • Desde a versão 8.3.1 do driver, authentication=ActiveDirectoryMSI pode ser usado para se conectar a um Banco de Dados SQL do Azure/Synapse Analytics a partir de um Recurso do Azure com suporte a "Identidade" habilitado. Opcionalmente, msiClientId pode ser especificado nas propriedades Connection/DataSource junto com esse modo de autenticação. msiClientId deve conter a ID do Cliente de uma Identidade Gerenciada a ser usada para adquirir o accessToken para estabelecer a conexão. Desde a versão do driver v12.2, authentication=ActiveDirectoryManagedIdentity também pode ser usado para se conectar a um Banco de Dados SQL do Azure/Synapse Analytics a partir de um Recurso do Azure com suporte a "Identidade" habilitado. Opcionalmente, a ID do Cliente de uma Identidade Gerenciada agora também pode ser definida na propriedade user. Para obter mais informações, consulte conectar usando o modo de autenticação ActiveDirectoryManagedIdentity.

  • ActiveDirectoryDefault

    • Desde a versão 12.2 do driver, authentication=ActiveDirectoryDefault pode ser usado para se conectar ao Azure SQL/Synapse Analytics por meio do DefaultAzureCredential da biblioteca de cliente do Azure Identity. Para obter mais informações, consulte o conectando-se usando o modo de autenticação ActiveDirectoryDefault.

  • Active Directory integrado

    • Desde a versão 6.0 do driver, authentication=ActiveDirectoryIntegrated pode ser usado para se conectar ao Azure SQL/Synapse Analytics por meio da autenticação integrada. Para usar este modo de autenticação, deve-se federar os Serviços de Federação do Active Directory (ADFS) locais com o Microsoft Entra ID na nuvem. Depois de configurá-lo, você pode se conectar adicionando o mssql-jdbc_auth-<version>-<arch>.dll da biblioteca nativa ao caminho da classe do aplicativo no Windows ou configurando um tíquete Kerberos para suporte à autenticação entre plataformas. Você pode acessar o Azure SQL/Azure Synapse Analytics sem ser solicitado a fornecer credenciais quando estiver conectado a uma máquina associada a um domínio. Para obter mais informações, consulte conectar usando o modo de autenticação integrado do ActiveDirectory.

  • ActiveDirectoryPassword

    • Desde a versão 6.0 do driver, authentication=ActiveDirectoryPassword pode ser usado para se conectar ao Azure SQL/Synapse Analytics com nome de usuário e senha do Microsoft Entra. Para obter mais informações, consulte conectar-se utilizando o modo de autenticação "ActiveDirectoryPassword".

  • ActiveDirectoryInteractive

    • Desde a versão 9.2 do driver, authentication=ActiveDirectoryInteractive pode ser usado para se conectar a um Azure SQL/Synapse Analytics por meio do fluxo de autenticação interativo (autenticação multifator). Para obter mais informações, consulte Conectar usando a autenticação Interactive do Active Directory.

  • ActiveDirectoryServicePrincipal

    • Desde a versão 9.2 do driver, authentication=ActiveDirectoryServicePrincipal pode ser usado para se conectar a um Azure SQL/Synapse Analytics, especificando a ID do aplicativo/cliente na propriedade userName e o segredo de uma identidade principal do serviço na propriedade password. Para obter mais informações, consulte conectar usando o modo de autenticação ActiveDirectoryServicePrincipal.

  • ActiveDirectoryServicePrincipalCertificate

    • Desde a versão 12.4 do driver, authentication=ActiveDirectoryServicePrincipalCertificate pode ser usado para se conectar a um Banco de Dados SQL do Azure/Synapse Analytics especificando a ID do aplicativo/cliente na propriedade userName e o local do certificado da Entidade de Serviço na propriedade clientCertificate. Para obter mais informações, consulte Conectar usando o modo de autenticação ActiveDirectoryServicePrincipalCertificate.

  • SqlPassword

    • Use authentication=SqlPassword para se conectar a um SQL Server usando as propriedades userName/user e password.

  • NotSpecified

    • Use authentication=NotSpecified ou deixe-o como padrão quando nenhum desses métodos de autenticação for necessário.

  • accessToken: Use esta propriedade de conexão para se conectar a um Banco de dados SQL com token de acesso. accessToken só pode ser definido usando o parâmetro Properties do método getConnection() na classe DriverManager. Ele não pode ser usado no URL de conexão.

Para obter mais informações, consulte a propriedade authentication na página Definir as Propriedades da Conexão.

Requisitos de configuração do cliente

Além do driver básico Requisitos do sistema, os seguintes modos de autenticação têm mais requisitos.

A tabela a seguir lista as dependências de biblioteca necessárias para cada modo de autenticação e versão do driver. Dependências de dependências também são necessárias.

Observação

Nos casos em que o hotfix para uma versão principal tem uma versão de dependência diferente de sua versão principal, o hotfix também é listado.

Opção de autenticação	Versões do driver	Dependências da biblioteca
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
ActiveDirectoryPassword ActiveDirectoryIntegrated ActiveDirectoryInteractive ActiveDirectoryServicePrincipal ActiveDirectoryServicePrincipalCertificate ActiveDirectoryManagedIdentity ActiveDirectoryMSI ActiveDirectoryDefault	12.10	azure-identity 1.15.3

Use o modo de autenticação ActiveDirectoryManagedIdentity para se conectar

Este modo de autenticação é suportado a partir da versão 7.2. Para usá-lo, especifique authentication=ActiveDirectoryMSI. A partir da versão 12.2, authentication=ActiveDirectoryManagedIdentity também pode ser especificado.

Além dos requisitos de dependência de biblioteca listados em de requisitos de configuração do cliente, esse recurso tem os seguintes requisitos:

• O banco de dados de destino deve ter um usuário de banco de dados contido, com permissão CONNECT. O usuário contido deve representar a Identidade Gerenciada Atribuída pelo Sistema do Recurso do Azure ou a Identidade Gerenciada Atribuída pelo Usuário ou um dos grupos aos quais sua Identidade Gerenciada pertence.

• O ambiente do cliente deve ser um recurso do Azure e deve ter o suporte ao recurso "Identidade" habilitado. A tabela a seguir lista os serviços do Azure suportados por cada versão do driver JDBC:

  Versão do driver	Dependências necessárias	Serviços do Azure suportados
  7.2 - 11.2	Nenhum	Serviço de Aplicativo do Azure e Azure Functions Máquinas Virtuais do Azure
  12.2 12.4 12.6 12.8 12.10	azure-identity 1.7.0 azure-identity 1.9.0 azure-identity 1.11.1 azure-identity 1.12.2 azure-identity 1.15.3	Serviço de Aplicativo do Azure e Azure Functions Azure Arc Azure Cloud Shell Serviço Kubernetes do Azure Azure Service Fabric Máquinas Virtuais do Azure Conjuntos de Dimensionamento de Máquinas Virtuais do Azure

O exemplo a seguir mostra como usar o modo authentication=ActiveDirectoryManagedIdentity. Execute este exemplo de dentro de um Recurso do Azure configurado para Identidade Gerenciada.

Para executar o exemplo, substitua o nome do servidor/banco de dados pelo nome correspondente nas seguintes linhas:

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

O exemplo de uso do modo de autenticação 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));
            }
        }
    }
}

O exemplo a seguir demonstra como usar o modo 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));
            }
        }
    }
}

Esses exemplos em uma Máquina Virtual do Azure buscam um token de acesso de de Identidade Gerenciada Atribuída ao Sistema ou de Identidade Gerenciada Atribuída pelo Usuário (se msiClientId ou user for especificado com uma ID de Cliente de uma Identidade Gerenciada) e estabelecem uma conexão usando o token de acesso buscado. Se uma conexão for estabelecida, você verá a seguinte mensagem:

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

Conectar-se usando o modo de autenticação ActiveDirectoryDefault

A opção de autenticação ActiveDirectoryDefault usa a implementação encadeada DefaultAzureCredentialTokenCredential da biblioteca de cliente Azure Identity. A credencial combina métodos de autenticação comumente usados encadeados.

ActiveDirectoryDefault autenticação requer uma dependência de tempo de execução na biblioteca de cliente do Azure Identity para Identidade Gerenciada. Para obter detalhes da versão da biblioteca, consulte Requisitos de configuração do cliente.

A tabela a seguir lista a cadeia de credenciais DefaultAzureCredential para cada versão do driver JDBC.

Versão do driver	Versão do azure-identity	DefaultAzureCredential cadeia
12.2	azure-identity 1.7.0	Meio Ambiente Identidade gerenciada IntelliJ Azure CLI Azure PowerShell
12.4	azure-identity 1.9.0	Meio Ambiente Identidade da carga de trabalho Identidade gerenciada CLI do desenvolvedor do Azure IntelliJ Azure CLI Azure PowerShell
12.6	azure-identity 1.11.1	Meio Ambiente Identidade da carga de trabalho Identidade gerenciada CLI do desenvolvedor do Azure IntelliJ Azure CLI Azure PowerShell
12.8	azure-identity 1.12.2	Meio Ambiente Identidade da carga de trabalho Identidade gerenciada CLI do desenvolvedor do Azure IntelliJ Azure CLI Azure PowerShell
12.10	azure-identity 1.15.3	Meio Ambiente Identidade da carga de trabalho Identidade gerenciada CLI do desenvolvedor do Azure IntelliJ Azure CLI Azure PowerShell

Há muitas variáveis que podem ser definidas para configurar a credencial Environment. Para obter detalhes sobre como configurar a cadeia de DefaultAzureCredential, incluindo a credencial Environment, consulte a versão relevante dos documentos azure-identity vinculados na tabela anterior.

Para usar o IntellijCredential no Windows, defina a variável de ambiente INTELLIJ_KEEPASS_PATH para o local do arquivo keepass. Por exemplo, INTELLIJ_KEEPASS_PATH=C:\user\your\path\to\the\keepass\file.

Para fornecer mais locatários ao DefaultAzureCredential, use a variável de ambiente ADDITIONALLY_ALLOWED_TENANTS. Esta variável usa uma lista delimitada por vírgula. Por exemplo, ADDITIONALLY_ALLOWED_TENANTS=<your-tenant-id-0>,<your-tenant-id-1>,<your-tenant-id-2>,...

O exemplo a seguir demonstra como usar authentication=ActiveDirectoryDefault modo com o AzureCliCredential dentro do DefaultAzureCredential.

1. Primeiro, entre na CLI do Azure com o seguinte comando.

   az login
   

2. Depois de iniciar sessão com êxito na CLI do Azure, execute o seguinte código.

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

Conectar-se usando o modo de autenticação integrado do ActiveDirectory

Há duas maneiras de usar a autenticação ActiveDirectoryIntegrated no Microsoft JDBC Driver para SQL Server:

• No Windows, mssql-jdbc_auth-<version>-<arch>.dll do pacote baixado pode ser copiado para um local no caminho do sistema.
• Se não for possível usar a DLL, a partir da versão 6.4 poderá configurar um tíquete Kerberos. Este método é suportado em todas as plataformas (Windows, Linux e macOS). Para obter mais informações, consulte Definir bilhete Kerberos no Windows, Linux e macOS.

Certifique-se de que possui as bibliotecas dependentes necessárias dos requisitos de configuração do cliente .

O exemplo a seguir mostra como usar o modo authentication=ActiveDirectoryIntegrated. Este exemplo é executado em uma máquina associada a um domínio que é federada com o Microsoft Entra ID. Um usuário de banco de dados que representa seu usuário do Windows deve existir no banco de dados e deve ter a permissão CONNECT.

Substitua o nome do servidor/banco de dados pelo correspondente nas linhas a seguir antes de executar o exemplo:

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

Este é o exemplo para utilizar o modo de autenticação ActiveDirectoryIntegrado:

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

A execução deste exemplo usa automaticamente seu tíquete Kerberos da plataforma cliente e nenhuma senha é necessária. Se uma conexão for estabelecida, você verá a seguinte mensagem:

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

Configurar bilhete Kerberos no Windows, Linux e macOS

Você deve criar um tíquete Kerberos para vincular seu usuário atual a uma conta de domínio do Windows. Segue-se um resumo dos principais passos.

Windows

Observação

No sistema Windows, mssql-jdbc_auth-<version>-<arch>.dll baixado do pacote pode ser usado em vez desses passos de configuração do Kerberos. Essas etapas só são necessárias se você não puder usar a DLL.

O JDK vem com kinit, que pode utilizar para obter um TGT do Centro de Distribuição de Chaves (KDC) em uma máquina associada ao domínio que está federada com o Microsoft Entra ID.

Etapa 1: Recuperação de Ticket de Concessão

• Executar em: Windows

• Ação:

  • Use o comando kinit username@DOMAIN.COMPANY.COM para obter um TGT do KDC e, em seguida, ele solicita sua senha de domínio.
  • Use klist para ver os ingressos disponíveis. Se o kinit foi bem-sucedido, você deve ver um bilhete de krbtgt/DOMAIN.COMPANY.COM@ DOMAIN.COMPANY.COM.

  Observação

  Talvez seja necessário especificar um arquivo .ini com -Djava.security.krb5.conf para seu aplicativo localizar o KDC.

Linux e macOS

Requerimentos

Acesso a uma máquina associada a um domínio do Windows para consultar o Controlador de Domínio Kerberos.

Etapa 1: Encontrar Kerberos KDC

• Executar em: Linha de comando do Windows

• Action: nltest /dsgetdc:DOMAIN.COMPANY.COM (onde DOMAIN.COMPANY.COM mapeia para o nome do seu domínio)

• Exemplo de saída

  DC: \\co1-red-dc-33.domain.company.com
  Address: \\2111:4444:2111:33:1111:ecff:ffff:3333
  ...
  The command completed successfully
  

• Informações para extrair Nome DC, neste caso co1-red-dc-33.domain.company.com

Etapa 2: Configurando o KDC no krb5.conf

• Executa em: Linux/macOS

• Ação: Edite o /etc/krb5.conf em um editor de sua escolha. Configure as seguintes chaves

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

  Em seguida, salve o arquivo krb5.conf e saia

  Observação

  O domínio deve estar em MAIÚSCULAS.

Etapa 3: Testar a recuperação do bilhete de concessão de acesso

• Executar em: Linux/macOS
• Ação:
  • Use o comando kinit username@DOMAIN.COMPANY.COM para obter um TGT do KDC e, em seguida, ele solicita sua senha de domínio.
  • Use klist para ver os ingressos disponíveis. Se o kinit foi bem-sucedido, você deve ver um bilhete de krbtgt/DOMAIN.COMPANY.COM@ DOMAIN.COMPANY.COM.

Conectar-se usando o modo de autenticação ActiveDirectoryPassword

O exemplo a seguir mostra como usar o modo authentication=ActiveDirectoryPassword.

Para criar e executar o exemplo:

1. Certifique-se de ter as bibliotecas dependentes necessárias conforme os requisitos de configuração do cliente .

2. Localize as seguintes linhas de código e substitua o nome do servidor/nome do banco de dados pelo seu servidor/nome do banco de dados.

   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. Localize as seguintes linhas de código. Substitua o nome de usuário pelo nome do usuário do Microsoft Entra ao qual você deseja se conectar.

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

O exemplo de uso do modo de autenticação 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 a conexão for estabelecida, você verá a seguinte mensagem como saída:

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

Conectar-se usando o modo de autenticação ActiveDirectoryInteractive

O exemplo a seguir mostra como usar o modo authentication=ActiveDirectoryInteractive.

Para criar e executar o exemplo:

1. Certifique-se de ter as bibliotecas dependentes necessárias dos requisitos de configuração do Client.

2. Encontre as seguintes linhas de código e substitua o nome do servidor/base de dados pelo nome do seu servidor/base de dados.

   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. Localize as seguintes linhas de código. Substitua username pelo nome do usuário do Microsoft Entra ao qual você deseja se conectar.

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

O exemplo para usar o modo de autenticação 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 você executa o programa, um navegador é exibido para autenticar o usuário. Exatamente o que você vê depende de como você configura sua ID do Microsoft Entra. Pode ou não incluir pedidos de autenticação multifator para autenticação de nome de utilizador, palavra-passe, PIN ou segundo dispositivo através de um telefone. Se várias solicitações de autenticação interativas forem feitas no mesmo programa, solicitações posteriores podem nem mesmo avisar se a biblioteca de autenticação pode reutilizar um token de autenticação previamente armazenado em cache.

Para obter informações sobre como configurar o Microsoft Entra ID para exigir autenticação multifator, consulte Introdução à autenticação multifator do Microsoft Entra na nuvem.

Para obter capturas de tela dessas caixas de diálogo, consulte Usando a autenticação multifator do Microsoft Entra.

Se a autenticação do usuário for concluída com êxito, você verá a seguinte mensagem no navegador:

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

Essa mensagem indica apenas que a autenticação do usuário foi bem-sucedida, mas não necessariamente uma conexão bem-sucedida com o servidor. Ao retornar ao aplicativo, se uma conexão for estabelecida com o servidor, você verá a seguinte mensagem como saída:

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

Conectar-se usando o modo de autenticação ActiveDirectoryServicePrincipal

O exemplo a seguir mostra como usar o modo authentication=ActiveDirectoryServicePrincipal.

Para criar e executar o exemplo:

1. Certifique-se de ter as bibliotecas dependentes necessárias dos requisitos de configuração do Client.

2. Localize as seguintes linhas de código e substitua o nome do servidor/base de dados pelo nome do seu servidor/base de dados.

   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. Localize as seguintes linhas de código. Substitua o valor de principalId pela ID do Aplicativo / ID do Cliente da entidade de serviço do Microsoft Entra com a qual você deseja se conectar. Substitua o valor de principalSecret pelo segredo.

   String principalId = "<service_principal_guid>"; // Replace with your Microsoft Entra service principal ID.
   String principalSecret = "..."; // Replace with your Microsoft Entra principal secret.
   

4. Defina o ID principal e o segredo principal usando setUser e setPassword na versão 10.2 e superior, e setAADSecurePrincipalId e setAADSecurePrincipalSecret na versão 9.4 e inferior.

O exemplo de como usar o modo de autenticação 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 uma conexão for estabelecida, você verá a seguinte mensagem como saída:

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

Conectar-se usando o modo de autenticação por certificado ActiveDirectoryServicePrincipal

O exemplo a seguir mostra como usar o modo authentication=ActiveDirectoryServicePrincipalCertificate.

Para criar e executar o exemplo:

1. Certifique-se de ter as bibliotecas dependentes necessárias especificadas nos requisitos de configuração do cliente .

2. Encontre as seguintes linhas de código e substitua o nome do servidor ou banco de dados pelo nome do seu servidor ou banco de dados.

   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. Localize as seguintes linhas de código. Substitua o valor de principalId pela ID do Aplicativo / ID do Cliente da entidade de serviço do Microsoft Entra com a qual você deseja se conectar. Substitua o valor de clientCertificate pelo local do certificado da entidade de serviço.

   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 o certificado mencionado anteriormente precisar de uma senha, defina o segredo principal usando setPassword na versão 10.2 e superior ou setAADSecurePrincipalSecret na versão 9.4 e abaixo.

5. Se o certificado tiver uma chave privada associada, defina a chave privada usando setClientKey. Se essa chave exigir uma senha, defina a senha para a chave privada usando setClientKeyPassword.

O exemplo de uso do modo de autenticação 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 uma conexão for estabelecida, você verá a seguinte mensagem como saída:

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

Conectar-se usando o token de acesso

Os aplicativos/serviços podem recuperar um token de acesso da ID do Microsoft Entra e usá-lo para se conectar ao Banco de Dados SQL do Azure, à Instância Gerenciada SQL do Azure e ao Azure Synapse Analytics.

Observação

accessToken só pode ser definido usando o parâmetro Properties do método getConnection() na classe DriverManager. Ele não pode ser usado na cadeia de conexão. A partir da versão 12.2 do driver, os utilizadores podem implementar e fornecer um retorno de chamada accessToken ao driver para renovação de token em cenários de agrupamento de conexões. Os cenários de pool de conexões requerem que a implementação do pool de conexões use as classes de pool de conexões JDBC padrão .

O exemplo a seguir contém um aplicativo Java simples que se conecta ao Azure usando a autenticação baseada em token de acesso.

Para criar e executar o exemplo:

1. Crie uma conta de aplicativo no Microsoft Entra ID para o seu serviço.

   1. Entre no portal do Azure.
   2. Vá para Microsoft Entra ID na navegação à esquerda.
   3. Selecione Registos de aplicações.
   4. Selecione Novo registo.
   5. Digite mytokentest como um nome amigável para o aplicativo.
   6. Deixe a seleção padrão para tipos de conta suportados, que podem usar o aplicativo.
   7. Selecione Registo na parte inferior.
   8. Não é necessário SIGN-ON URL. Forneça qualquer coisa: https://mytokentest.
   9. Selecione Create na parte inferior.
   10. Ao selecionar Registrar, o aplicativo é criado imediatamente e você é direcionado para sua página de recursos.
   11. Na caixa do Essentials, localize o de ID do aplicativo (cliente) e copie-o. Você precisará desse valor posteriormente para configurar seu aplicativo.
   12. Selecione Certificados & segredos no painel de navegação. Na guia Segredos de Cliente (0), selecione Novo Segredo de Cliente. Insira uma descrição para o segredo e selecione uma expiração (o padrão é bom). Selecione Adicionar na parte inferior. Importante antes de sair desta página, copie o valor gerado para o segredo do cliente. Esse valor não pode ser visualizado depois de sair da página. Este valor é o segredo do cliente.
   13. Regresse ao painel registos de aplicações para o ID do Microsoft Entra e localize o separador Pontos de Extremidade. Copie o URL em OAuth 2.0 token endpoint. Este URL é o seu URL STS.

2. Conecte-se ao seu banco de dados como um administrador do Microsoft Entra e use um comando T-SQL para provisionar um utilizador de base de dados isolado para o seu principal de aplicação. Para obter mais informações sobre como criar um administrador do Microsoft Entra e um usuário de banco de dados contido, consulte o Conectando usando a autenticação do Microsoft Entra.

   CREATE USER [mytokentest] FROM EXTERNAL PROVIDER
   

3. Na máquina cliente onde você executa o exemplo, baixe a biblioteca Microsoft Authentication Library (MSAL) para Java e suas dependências. O MSAL só é necessário para executar este exemplo específico. O exemplo usa as APIs dessa biblioteca para recuperar o token de acesso do Microsoft Entra ID. Se você já tiver um token de acesso, poderá ignorar esta etapa e remover a seção no exemplo que recupera um token de acesso.

No exemplo a seguir, substitua a URL do STS, a ID do Cliente, o Segredo do Cliente, o nome do servidor e do banco de dados pelos seus valores.

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 a conexão for bem-sucedida, você verá a seguinte mensagem como saída:

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

Conectar-se usando o callback do token de acesso

Assim como a propriedade do token de acesso, o retorno de chamada do token de acesso permite registar um método que fornece um token de acesso ao driver. O benefício deste callback em relação à propriedade é que ele permite ao driver solicitar um novo token de acesso quando o token estiver expirado. Por exemplo, um pool de conexões que cria uma nova conexão pode solicitar um novo token com uma nova data de validade. Para obter mais informações, consulte Usando o pool de conexões.

O exemplo a seguir demonstra a implementação e configuração do callback 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 a conexão for bem-sucedida, você verá a seguinte mensagem como saída:

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

A partir da versão 12.4, o retorno de chamada accessToken pode ser definido através da propriedade de string de conexão accessTokenCallbackClass. O exemplo a seguir mostra como definir a chamada de retorno accessToken usando esta propriedade:

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 a conexão for bem-sucedida, você verá a seguinte mensagem como saída:

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

Próximos passos

Saiba mais sobre conceitos relacionados nos seguintes artigos:

• Ligar-se ao Azure SQL por usar a autenticação do Microsoft Entra
• Microsoft Authentication Library (MSAL) para Java
• Microsoft Azure Active Directory Authentication Library (ADAL) para Java
• Solucionar problemas de conexão com o Banco de Dados SQL do Azure