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

Baixar o JDBC Driver

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

Você pode usar a autenticação do Microsoft Entra, que é um mecanismo que se conecta ao banco de dados SQL do Azure, à Instância Gerenciada de SQL do Azure e ao Azure Synapse Analytics usando identidades no Microsoft Entra ID. Use a autenticação do Microsoft Entra para gerenciar centralmente as identidades de usuários do banco de dados e como uma alternativa à autenticação do SQL Server. O JDBC Driver 6.0 permite que você especifique suas credenciais do Microsoft Entra na cadeia de conexão JDBC para se conectar ao SQL do Azure. 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 para SQL Server são:

• authentication: use essa propriedade para indicar o método de autenticação SQL a ser utilizado para a conexão. Os valores possíveis são os seguintes:

  • ActiveDirectoryManagedIdentity

    • Desde a versão 8.3.1 do driver, o authentication=ActiveDirectoryMSI pode ser usado para se conectar a um Banco de Dados SQL do Azure/Synapse Analytics de um Recurso do Azure com suporte a "Identidade" habilitado. Opcionalmente, msiClientId pode ser especificado nas propriedades Connection/DataSource 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 v12.2 do driver, o authentication=ActiveDirectoryManagedIdentity também pode ser usado para se conectar a um Banco de Dados SQL do Azure/ao Synapse Analytics por meio de um recurso do Azure com o suporte à "Identidade" habilitado. Opcionalmente, agora a ID do cliente de uma identidade gerenciada também pode ser definida na propriedade user. Para obter mais informações, confira Conectar-se usando o modo de autenticação ActiveDirectoryManagedIdentity.

  • ActiveDirectoryDefault

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

  • ActiveDirectoryIntegrated

    • Desde a versão 6.0 do driver, o authentication=ActiveDirectoryIntegrated pode ser usado para se conectar ao SQL do Azure/Synapse Analytics por meio de uma autenticação integrada. Para usar esse modo de autenticação, você precisará federar os ADFS (Serviços de Federação do Active Directory) local com o Microsoft Entra ID na nuvem. Quando ele estiver configurado, você poderá se conectar adicionando a biblioteca nativa mssql-jdbc_auth-<version>-<arch>.dll ao caminho da classe de aplicativo no Windows ou configurando um tíquete Kerberos para suporte de autenticação multiplataforma. Você poderá acessar o SQL do Azure/Azure Synapse Analytics sem precisar fornecer credenciais quando estiver conectado a um computador conectado ao domínio. Para obter mais informações, confira Conectar-se usando um modo de autenticação ActiveDirectoryIntegrated.

  • ActiveDirectoryPassword

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

  • ActiveDirectoryInteractive

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

  • ActiveDirectoryServicePrincipal

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

  • ActiveDirectoryServicePrincipalCertificate

    • Desde a versão 12.4 do driver, o 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-se 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 o padrão quando nenhum desses métodos de autenticação for necessário.

  • accessToken: use essa propriedade de conexão para se conectar a um banco de dados SQL com um 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 na URL de conexão.

Para obter mais informações, confira a propriedade de autenticação na página Configuração das propriedades de conexão.

Requisitos de configuração do cliente

Além dos requisitos do sistema básicos do driver, os modos de autenticação a seguir 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.

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

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

Além dos requisitos de dependência de biblioteca listados em 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 ou a Identidade Gerenciada Atribuída pelo Usuário de seu Recurso do Azure, 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 com suporte em cada versão do driver JDBC:

  Versão do driver	Dependências necessárias	Serviços do Azure compatíveis
  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	azure-identity 1.7.0 azure-identity 1.9.0 azure-identity 1.11.1 azure-identity 1.12.2	Serviço de Aplicativo do Azure e Azure Functions Azure Arc Azure Cloud Shell Serviço de 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 em um recurso do Azure configurado para a Identidade Gerenciada.

Para executar o exemplo, substitua o nome do servidor/banco de dados pelo nome do seu servidor/banco de dados 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 para usar o 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));
            }
        }
    }
}

Estes exemplos em uma máquina virtual do Azure buscam um token de acesso da identidade gerenciada atribuída pelo sistema ou da identidade gerenciada atribuída pelo usuário (caso msiClientId ou user seja especificado com uma ID do cliente de uma identidade gerenciada) e estabelece uma conexão por meio do token de acesso obtido. Se uma conexão for estabelecida, você deverá 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 TokenCredential encadeada DefaultAzureCredential da biblioteca de cliente da Identidade Azure. A credencial combina métodos de autenticação encadeados comumente usados.

A autenticação ActiveDirectoryDefault exige uma dependência de tempo de execução na biblioteca de clientes da Identidade do Azure para Identidade Gerenciada. Para obter detalhes sobre a 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.

Há muitas variáveis que podem ser definidas para configurar a credencial Environment. Para obter detalhes sobre como configurar a cadeia DefaulAzureCredential, 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. Essa 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 o modo authentication=ActiveDirectoryDefault com a AzureCliCredential no DefaultAzureCredential.

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

   az login
   

2. Depois de fazer logon com sucesso na CLI do Azure, execute o código a seguir.

   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 ActiveDirectoryIntegrated

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 uma localização no caminho do sistema.
• Se você não puder usar a DLL, a partir da versão 6,4, poderá configurar um tíquete Kerberos. Há suporte para esse método em várias plataformas (Windows, Linux e macOS). Para obter mais informações, confira Definir tíquete Kerberos no Windows, Linux e macOS.

Verifique se você exigiu as bibliotecas dependentes dos Requisitos de configuração do cliente.

O exemplo a seguir mostra como usar o modo authentication=ActiveDirectoryIntegrated. Este exemplo é executado em um computador ingressado no domínio que seja federado 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 precisa ter a permissão CONNECT.

Substitua o nome do servidor/banco de dados pelo nome do servidor/banco de dados nas seguintes linhas 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

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

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

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

Definir tíquete Kerberos no Windows, Linux e macOS

Você precisa configurar um tíquete Kerberos para vincular o usuário atual a uma conta de domínio do Windows. A seguir, há um resumo das principais etapas.

Windows

O JDK vem com o kinit, que você pode usar para obter um TGT do KDC (centro de distribuição de chaves) em um computador ingressado no domínio que seja federado com o Microsoft Entra ID.

Etapa 1: recuperação do tíquete de concessão de tíquete

• Executar em: Windows

• Ação:

  • Use o comando kinit username@DOMAIN.COMPANY.COM para obter um TGT do KDC e, depois, ele solicitará sua senha de domínio.
  • Use klist para ver os tíquetes disponíveis. Se o kinit for bem-sucedido, você deverá ver um tíquete de krbtgt/DOMAIN.COMPANY.COM@ DOMAIN.COMPANY.COM.

  Observação

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

Linux e macOS

Requisitos

Acesso a um computador ingressado no domínio do Windows para consultar o controlador de domínio do Kerberos.

Etapa 1: localizar o KDC do Kerberos

• Executar em: Linha de comando do Windows

• Ação: nltest /dsgetdc:DOMAIN.COMPANY.COM (em que DOMAIN.COMPANY.COM é mapeado para seu nome de domínio)

• Saída de exemplo

  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 O nome do DC, neste caso, co1-red-dc-33.domain.company.com

Etapa 2: configuração do KDC em krb5.conf

• Executar 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
  }
  

  Depois, salve o arquivo krb5.conf e saia.

  Observação

  O domínio precisa estar em MAIÚSCULAS.

Etapa 3: testar a recuperação do tíquete de concessão de tíquete

• Executar em: Linux/MacOS
• Ação:
  • Use o comando kinit username@DOMAIN.COMPANY.COM para obter um TGT do KDC, e em seguida ele solicitará a sua senha de domínio.
  • Use klist para ver os tíquetes disponíveis. Se o kinit for bem-sucedido, você deverá ver um tíquete 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 compilar e executar, veja um exemplo:

1. Verifique se você exigiu as bibliotecas dependentes dos Requisitos de configuração do cliente.

2. Localize as linhas de código a seguir e substitua o nome do servidor/banco de dados pelo nome do seu servidor/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 linhas de código a seguir. Substitua o nome de usuário pelo nome do usuário do Microsoft Entra com o qual você deseja se conectar.

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

O exemplo para usar o 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ê deverá ver a seguinte mensagem como saída:

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

Conectar-se usando modo de autenticação ActiveDirectoryInteractive

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

Para compilar e executar, veja um exemplo:

1. Verifique se você exigiu as bibliotecas dependentes dos Requisitos de configuração do cliente.

2. Localize as linhas de código a seguir e substitua o nome do servidor/banco de dados pelo nome do seu servidor/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 linhas de código a seguir. Substitua o nome de usuário pelo nome do usuário do Microsoft Entra com o 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. O que você vê exatamente depende de como você configura o Microsoft Entra ID. Prompts de autenticação multifator podem ser incluídos ou não para nome de usuário, senha, PIN ou segunda autenticação de dispositivo por meio de um celular. Caso várias solicitações de autenticação interativa sejam executadas no mesmo programa, as solicitações posteriores talvez nem executem uma solicitação ao usuário se a biblioteca de autenticação puder usar novamente um token de autenticação já 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 Usar a autenticação multifator do Microsoft Entra.

Quando a autenticação do usuário é concluída com êxito, a seguinte mensagem é exibida no navegador:

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

Essa mensagem indica somente que a autenticação do usuário foi concluída com êxito, mas não significa que a conexão com o servidor foi bem-sucedida. Ao retornar ao aplicativo, caso uma conexão seja estabelecida com o servidor, a seguinte mensagem será exibida como saída:

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

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

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

Para compilar e executar, veja um exemplo:

1. Verifique se você exigiu as bibliotecas dependentes dos Requisitos de configuração do cliente.

2. Localize as linhas de código a seguir e substitua o nome do servidor/banco de dados pelo nome do seu servidor/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 linhas de código a seguir. Substitua o valor de principalId pelo ID do Aplicativo/Cliente da entidade de serviço do Microsoft Entra com a qual 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 a ID de entidade de segurança e o segredo da entidade de segurança usando setUser e setPassword na versão 10.2 e posteriores e setAADSecurePrincipalId e setAADSecurePrincipalSecret na versão 9.4 e anteriores.

O exemplo para 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));
            }
        }
    }
}

Quando a conexão for estabelecida, a seguinte mensagem será exibida como output:

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

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

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

Para compilar e executar, veja um exemplo:

1. Verifique se você exigiu as bibliotecas dependentes dos Requisitos de configuração do cliente.

2. Localize as linhas de código a seguir e substitua o nome do servidor/banco de dados pelo nome do seu servidor/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 linhas de código a seguir. Substitua o valor de principalId pelo ID do Aplicativo/Cliente da entidade de serviço do Microsoft Entra com a qual deseja se conectar. Substitua o valor de clientCertificate pela localização 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 posteriores ou setAADSecurePrincipalSecret na versão 9.4 e anteriores.

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 para usar o 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));
            }
        }
    }
}

Quando a conexão for estabelecida, a seguinte mensagem será exibida como output:

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

Conectar-se usando token de acesso

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

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

Para compilar e executar, veja um exemplo:

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

   1. Entre no portal do Azure.
   2. Selecione Microsoft Entra ID na barra de navegação à esquerda.
   3. Selecione Registros do Aplicativo.
   4. Selecione Novo registro.
   5. Insira mytokentest como um nome amigável para o aplicativo
   6. Deixe a seleção padrão para os tipos de conta suportados que podem usar o aplicativo.
   7. Selecione Registrar na parte inferior.
   8. A URL DE LOGON não é necessária. Forneça qualquer coisa: https://mytokentest.
   9. Selecione Create na parte inferior.
   10. Ao selecionar Registrar, o aplicativo é imediatamente criado e você é levado para sua página de recursos.
   11. Na caixa Essentials, localize o ID do aplicativo (cliente) e copie-o. Você precisará desse valor posteriormente para configurar o aplicativo.
   12. Selecione Certificados e segredos no painel de navegação. Na guia Segredos do cliente (0), selecione Novo segredo do cliente. Insira uma descrição para o segredo do cliente e selecione uma expiração (o padrão pode ser usado). Selecione Adicionar na parte inferior. Importante: antes de sair desta página, copie o Valor gerado para o segredo do seu cliente. Esse valor não pode ser visualizado depois de sair da página. Esse valor é o segredo do cliente.
   13. Retorne ao painel Registros de aplicativo do Microsoft Entra ID e localize a guia Pontos de extremidade. Copie o URL em OAuth 2.0 token endpoint. Essa URL é a URL do STS.

   

2. Conecte-se ao banco de dados como um administrador do Microsoft Entra e use um comando T-SQL para provisionar um usuário de banco de dados independente para a entidade de segurança do aplicativo. Para obter mais informações sobre como criar um administrador do Microsoft Entra e um usuário de banco de dados independente, consulte Conectando-se usando a autenticação do Microsoft Entra.

   CREATE USER [mytokentest] FROM EXTERNAL PROVIDER
   

3. No computador cliente no qual você deseja executar o exemplo, baixe a Biblioteca Microsoft Authentication (MSAL) para Java e as respectivas dependências. A MSAL só é necessária para executar este exemplo específico. O exemplo usa as APIs desta biblioteca para recuperar o token de acesso do Microsoft Entra ID. Se você já tem um token de acesso, pode 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 servidor e o nome 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á uma mensagem semelhante à seguinte:

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

Conectar-se usando um retorno de chamada do token de acesso

Assim como a propriedade do token de acesso, o retorno de chamada do token de acesso permite que você registre um método que fornece um token de acesso ao driver. O benefício desse retorno de chamada em relação à propriedade é que o retorno de chamada permite que o driver solicite um novo token de acesso quando o token expirar. Por exemplo, um pool de conexões que cria uma nova conexão pode solicitar um novo token com uma nova data do término. Para obter mais informações, confira Como usar o pool de conexões.

O exemplo a seguir demonstra a implementação e a configuração do retorno de chamada do 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á uma mensagem semelhante à seguinte:

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

Desde a versão 12.4, o retorno de chamada accessToken pode ser definido por meio da propriedade accessTokenCallbackClass da cadeia de conexão. O exemplo a seguir mostra como definir o retorno de chamada accessToken usando essa 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á uma mensagem semelhante à seguinte:

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

Próximas etapas

Saiba mais sobre conceitos relacionados nos seguintes artigos:

• Conectar-se ao SQL do Azur eusando a autenticação do Microsoft Entra
• MSAL (Biblioteca de Autenticação da Microsoft) para Java
• ADAL (Biblioteca de Autenticação do Microsoft Azure Active Directory) para Java
• Solucionar problemas de conexão no Banco de Dados SQL do Azure