Ao trabalhar com sistemas corporativos que utilizam o Microsoft SQL Server, é comum encontrar ambientes configurados para autenticação integrada do Windows. Isso significa que o acesso ao banco de dados é feito com base nas credenciais do usuário logado no sistema operacional, dispensando o uso de nome de usuário e senha definidos diretamente no banco.
Quando desenvolvemos aplicações Java que precisam se conectar ao SQL Server usando esse tipo de autenticação, é necessário realizar uma configuração específica no driver JDBC. Caso contrário, a aplicação não conseguirá autenticar corretamente o usuário e a conexão falhará.
Por que é necessário o arquivo msql-jdbc_auth.dll?
O driver oficial do SQL Server para Java, conhecido como Microsoft JDBC Driver for MS QL Server, oferece suporte à autenticação integrada do Windows através de uma biblioteca nativa chamada msql-jdbc_auth.dll.
Essa DLL atua como uma ponte entre o Java e as APIs do Windows responsáveis pela autenticação. Sem ela, o Java não teria acesso ao contexto de segurança do sistema operacional, e a tentativa de conexão com autenticação integrada resultaria em erro.
Em resumo, o Java precisa desse componente nativo para poder "herdar" as credenciais do usuário logado e repassá-las ao SQL Server de forma segura.
Passo a passo para configurar
- Download o driver JDBC oficial
- Descompactar o pacote
- Copiar a DLL para o diretório correto
- Configurar a string de conexão
- Executar a aplicação
Acesse o site oficial da Microsoft e baixe o driver JDBC mais recente.
No momento da escrita deste artigo, a versão disponível é a 12.8.1, e o link direto de download é: https://go.microsoft.com/fwlink?linkid=2283744
Após o download, descompacte o arquivo. Dentro da pasta extraída você encontrará o driver mssql-jdbc-12.8.1.jar (ou .jre11, .jre17, conforme sua versão do Java) e também a biblioteca nativa msql-jdbc_auth-12.8.1.x64.dll.
Copie o arquivo msql-jdbc_auth-12.8.1.x64.dll para o diretório bin da instalação do Java.
Exemplo de caminho no Windows:
C:\Program Files\Java\jdk-17\bin
Esse diretório faz parte do java.library.path, o que garante que a JVM consiga localizar a DLL durante a execução.
A string de conexão deve informar que será usada a autenticação integrada.
Exemplo:
String connectionUrl = "jdbc:sqlserver://localhost:1433;"
+ "databaseName=MinhaBase;"
+ "integratedSecurity=true;";
Connection conn = DriverManager.getConnection(connectionUrl);
Para projetos Spring Boot, configure no arquivo application.properties:
spring.datasource.url=jdbc:sqlserver://IPSERVIDORDBMSSQLSERVER:1433;databaseName=MinhaBase;integratedSecurity=true;
spring.datasource.driver-class-name=com.microsoft.sqlserver.jdbc.SQLServerDriver
Caso use Quarkus, a configuração fica assim:
quarkus.datasource.jdbc.url=jdbc:sqlserver://IPSERVIDORDBMSSQLSERVER:1433;databaseName=MinhaBase;integratedSecurity=true;
quarkus.datasource.jdbc.driver=com.microsoft.sqlserver.jdbc.SQLServerDriver
Observe o parâmetro integratedSecurity=true, que é o que ativa o uso da DLL para autenticação.
Com a DLL no diretório correto e o driver JDBC configurado no classpath, sua aplicação Java será capaz de se conectar ao SQL Server utilizando as credenciais do usuário do Windows atual.
Configuração para Linux com Windows Authentication
Em sistemas Linux, a autenticação integrada não funciona nativamente com a DLL, pois ela é específica do Windows.
Nesse caso, o método recomendado é usar Kerberos, o mesmo protocolo que o Active Directory utiliza para autenticação entre domínios.
Passos para configurar no Linux
- Instale os pacotes necessários
- Configure o arquivo /etc/krb5.conf
- Obtenha um ticket Kerberos com seu usuário do domínio
- Configure a conexão JDBC
Em distribuições baseadas em Debian/Ubuntu:
sudo apt install krb5-user libsasl2-modules-gssapi-mit
No Fedora:
sudo dnf install krb5-workstation
Adicione o domínio e o servidor KDC da sua rede corporativa.
Exemplo:
[libdefaults]
default_realm = MINHAEMPRESA.LOCAL
dns_lookup_kdc = true
dns_lookup_realm = true
[realms]
MINHAEMPRESA.LOCAL = {
kdc = dc1.minhaempresa.local
}
kinit usuario@MINHAEMPRESA.LOCAL
Após autenticar, você pode confirmar o ticket com:
klist
No application.properties (Spring Boot ou Quarkus), a URL deve indicar o uso do principal Kerberos:
Spring
spring.datasource.url=jdbc:sqlserver://IPSERVIDORDBMSSQLSERVER:1433;databaseName=MinhaBase;authenticationScheme=JavaKerberos;
spring.datasource.driver-class-name=com.microsoft.sqlserver.jdbc.SQLServerDriver
Quarkus
quarkus.datasource.jdbc.url=jdbc:sqlserver://IPSERVIDORDBMSSQLSERVER:1433;databaseName=MinhaBase;authenticationScheme=JavaKerberos;
quarkus.datasource.jdbc.driver=com.microsoft.sqlserver.jdbc.SQLServerDriver
A opção authenticationScheme=JavaKerberos instrui o driver JDBC a usar o ticket obtido via kinit.
Considerações finais
Essa configuração é especialmente útil em ambientes corporativos onde a política de segurança exige Single Sign-On (SSO) e o gerenciamento centralizado de permissões. Além disso, evita o armazenamento de senhas no código-fonte ou em arquivos de configuração, o que aumenta a segurança da aplicação.
Vale lembrar que a autenticação integrada funciona apenas quando a aplicação Java está sendo executada em um ambiente Windows. Para servidores Linux, é necessário configurar o Kerberos e utilizar parâmetros adicionais no driver.
Em resumo, a presença da DLL msql-jdbc_auth é fundamental para que o Java consiga usar a autenticação nativa do Windows ao se conectar ao MS SQL Server. Com ela corretamente posicionada e o driver JDBC configurado, o processo de autenticação se torna transparente e seguro, aproveitando os recursos já disponíveis no sistema operacional.
Feito!
