Conectando ao MS SQL Server com autenticação do usuário do Windows (Windows Authentication) em Java

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

1. Download o driver JDBC oficial

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

2. Descompactar o pacote

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.

3. Copiar a DLL para o diretório correto

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.

4. Configurar a string de conexã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.

5. Executar a aplicaçã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

1. Instale os pacotes necessários

Em distribuições baseadas em Debian/Ubuntu:

sudo apt install krb5-user libsasl2-modules-gssapi-mit

No Fedora:

sudo dnf install krb5-workstation
2. Configure o arquivo /etc/krb5.conf

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
    }

3. Obtenha um ticket Kerberos com seu usuário do domínio
kinit usuario@MINHAEMPRESA.LOCAL

Após autenticar, você pode confirmar o ticket com:

klist
4. Configure a conexão JDBC

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!