Usar XA com o Microsoft ODBC Driver

Baixar driver ODBC

Finalidade

O Microsoft ODBC Driver for SQL Server versão 13.1 ou acima permite que aplicativos ODBC se conectem a uma instância do Banco de Dados SQL do Azure usando uma identidade federada no Microsoft Entra ID. A autenticação pode ser feita com um nome de usuário e senha, um token de acesso do Microsoft Entra, uma identidade gerenciada do Microsoft Entra (17.3+) ou a Autenticação Integrada do Windows em um ambiente federado associado ao domínio (17.6+ no Linux/macOS). Para o driver ODBC versão 13.1, a autenticação de token de acesso do Microsoft Entra é somente do Windows. O Driver ODBC versão 17 e posterior dá suporte a essa autenticação em todas as plataformas (Windows, Linux e macOS). Um novo método de autenticação interativa do Microsoft Entra, que oferece suporte à autenticação multifator, é introduzido no ODBC Driver versão 17.1 para Windows. O método de autenticação de identidade gerenciada do Active Directory foi adicionado no Driver ODBC versão 17.3.1.1 para identidades atribuídas pelo sistema e pelo usuário. Todas essas opções são realizadas usando novas palavras-chave de cadeia de conexão e DSN e atributos de conexão.

Para usar a autenticação do Microsoft Entra, você precisa configurar sua fonte de dados do SQL do Azure. Para obter mais informações, consulte Configurar e gerenciar a autenticação do Microsoft Entra com o SQL do Azure.

Palavras-chave novas e/ou modificadas da cadeia de conexão e DSN

A palavra-chave Authentication pode ser usada ao se conectar com um DSN ou uma cadeia de conexão para controlar o modo de autenticação. O valor definido na cadeia de conexão substitui o valor do DSN, caso ele seja fornecido. O valor de pré-atributo da configuração da Authentication é o valor computado a partir dos valores de DSN e da cadeia de conexão.

Atributos de conexão novos e/ou modificados

Os seguintes atributos de pré-conexão foram introduzidos ou modificados para dar suporte à autenticação do Microsoft Entra. Quando um atributo de conexão tem uma cadeia de conexão ou palavra-chave do DSN correspondente e está definido, o atributo de conexão tem precedência.

Adições de interface do usuário para o Microsoft Entra ID (somente driver do Windows)

As interfaces do usuário de configuração e conexão do DSN do driver foram aprimoradas com mais opções necessárias para usar a autenticação com o Microsoft Entra ID.

Criação e edição de DSNs no interface do usuário

É possível usar as novas opções de autenticação do Microsoft Entra ao criar ou editar um DSN existente por meio da interface do usuário da configuração do driver:

Autenticação do Azure SQL Microsoft Entra

Autenticação do Azure SQL Microsoft Entra

Autenticação do Azure SQL Microsoft Entra

Authentication=SqlPassword para autenticação de nome de usuário/senha para SQL Server (Azure ou não)

Trusted_Connection=Yes para autenticação integrada de SSPI herdada do Windows

Use as identidades gerenciadas do Microsoft Entra para autenticação.

Autenticação por token do Microsoft Entra ID para entidades de serviço

As sete opções correspondem a Trusted_Connection=Yes (uma autenticação integrada de legado existente somente do SSPI do Windows), bem como Authentication= ActiveDirectoryIntegrated, SqlPassword, ActiveDirectoryPassword, ActiveDirectoryInteractive, ActiveDirectoryMsi e ActiveDirectoryServicePrincipal, respectivamente.

Prompt do SQLDriverConnect (somente driver do Windows)

A caixa de diálogo de prompt exibida pelo SQLDriverConnect quando ele solicita as informações necessárias para concluir a conexão tem quatro novas opções para a autenticação do Microsoft Entra:

Essas opções correspondem às mesmas seis opções disponíveis na interface do usuário da configuração do DSN acima.

Cadeias de conexão de exemplo

1. Autenticação do SQL Server – sintaxe herdada. O certificado do servidor não é validado e a criptografia só será usada se for imposta pelo servidor. O nome de usuário/senha é passado na cadeia de conexão.

   server=Server;database=Database;UID=UserName;PWD=Password;Encrypt=no;TrustServerCertificate=yes;

2. Autenticação do SQL – nova sintaxe. O cliente solicita a criptografia (o valor padrão de Encrypt é true) e o certificado do servidor é validado, qualquer que seja a configuração de criptografia (a menos que TrustServerCertificate esteja definido como true). O nome de usuário/senha é passado na cadeia de conexão.

   server=Server;database=Database;UID=UserName;PWD=Password;Authentication=SqlPassword;

3. Autenticação integrada do Windows (Kerberos no Linux e macOS) por meio da sintaxe SSPI (para SQL Server ou SQL IaaS) – sintaxe atual. O certificado do servidor não é validado, a menos que a criptografia seja necessária ao servidor.

   server=Server;database=Database;Trusted_Connection=yes;Encrypt=no;

4. (Driver do Windows apenas.) Autenticação integrada do Windows por meio de SSPI (se o banco de dados de destino estiver no SQL Server ou SQL IaaS) – nova sintaxe. O cliente solicita a criptografia (o valor padrão de Encrypt é true) e o certificado do servidor é validado, qualquer que seja a configuração de criptografia (a menos que TrustServerCertificate esteja definido como true).

   server=Server;database=Database;Authentication=ActiveDirectoryIntegrated;

5. Autenticação de nome de usuário/senha do Microsoft Entra (se o banco de dados de destino estiver no Banco de Dados SQL do Azure ou na Instância Gerenciada de SQL do Azure). O certificado do servidor é validado, qualquer que seja a configuração de criptografia (a menos que TrustServerCertificate esteja definido como true). O nome de usuário/senha é passado na cadeia de conexão.

   server=Server;database=Database;UID=UserName;PWD=Password;Authentication=ActiveDirectoryPassword;Encrypt=yes;

6. (Windows e Linux/macOS 17.6+, somente driver.) Autenticação integrada do Windows pela ADAL ou Kerberos, que envolve a eliminação de credenciais de conta do Windows para um token de acesso emitido pelo Microsoft Entra, supondo que o banco de dados de destino esteja no Banco de dados SQL do Azure. O certificado do servidor é validado, qualquer que seja a configuração de criptografia (a menos que TrustServerCertificate esteja definido como true). No Linux/macOS, um tíquete do Kerberos precisa estar disponível. Para obter mais informações, confira a seção abaixo sobre Contas Federadas e sobre Como usar a autenticação integrada.

   server=Server;database=Database;Authentication=ActiveDirectoryIntegrated;Encrypt=yes;

7. No Windows, a Autenticação Interativa do Microsoft Entra pode usar a tecnologia de autenticação multifator do Microsoft Entra para configurar a conexão. Nesse modo, ao fornecer a ID de logon, uma caixa de diálogo de autenticação do Azure é acionada para permitir que o usuário insira a senha e conclua a conexão. O nome de usuário é passado na cadeia de conexão.

   server=Server;database=Database;UID=UserName;Authentication=ActiveDirectoryInteractive;Encrypt=yes;

   

8. A autenticação de identidade gerenciada do Microsoft Entra pode usar uma identidade gerenciada atribuída pelo sistema ou pelo usuário. Para uma identidade atribuída pelo usuário, defina o UID como a ID do cliente da identidade para Serviço de Aplicativo do Azure ou Instância de Contêiner do Azure; caso contrário, use seu ID de objeto. Para uma identidade atribuída pelo sistema, o UID não é obrigatório.
   

   Para identidade atribuída pelo sistema:

   server=Server;database=Database;Authentication=ActiveDirectoryMsi;Encrypt=yes;

   Para a identidade atribuída pelo usuário com a ID de objeto igual a myObjectId,

   server=Server;database=Database;UID=myObjectId;Authentication=ActiveDirectoryMsi;Encrypt=yes;

9. Autenticação da entidade de serviço do Microsoft Entra

server=Server;database=Database;UID=clientId;PWD=clientSecret;Authentication=ActiveDirectoryServicePrincipal;Encrypt=yes;

Comentários

• Ao usar opções do Active Directory com o driver ODBC do Windows antes da versão 17.4.2, verifique se a Biblioteca de Autenticação do Active Directory para SQL Server foi instalada. Quando usar drivers do Linux e macOS, verifique se libcurl foi instalado. Para o driver versão 17.2 e posterior, essa não é uma dependência explícita já que não é necessária para os demais métodos de autenticação ou operações ODBC.

• Quando a configuração do Microsoft Entra ID inclui políticas de acesso condicional e o cliente é o Windows 10 ou o Server 2016 ou posterior, a autenticação via Integrado ou nome de usuário/senha pode falhar. As políticas de Acesso Condicional exigem o uso do WAM (Gerenciador de Contas da Web), que tem suporte no driver versão 17.6 ou posterior para Windows. Para usar o WAM, crie um valor de sequência chamado ADALuseWAM em HKLM\Software\ODBC\ODBCINST.INI\ODBC Driver 17 for SQL Server, HKCU\Software\ODBC\ODBC.INI\<your-user-DSN-name> ou HKLM\Software\ODBC\ODBC.INI\<your-system-DSN-name> para configuração global, de DSN de usuário ou de DSN do sistema, respectivamente, e defina-o como um valor de 1. Observe que a autenticação com o WAM não oferece suporte à execução do aplicativo como um usuário diferente com runas. Cenários que exigem políticas de acesso condicional não têm suporte para Linux ou macOS.

• Para se conectar usando um nome de usuário e senha da conta de SQL Server, você pode usar a nova opção SqlPassword que é recomendada especialmente para o SQL do Azure já que permite padrões de conexão mais seguros.

• Para se conectar usando um nome de usuário e senha da conta do Microsoft Entra ID, especifique Authentication=ActiveDirectoryPassword na cadeia de conexão e as palavras-chave UID e PWD com o nome de usuário e a senha, respectivamente.

• Para se conectar usando a autenticação integrada do Windows ou do Active Directory (Windows e Linux/macOS 17.6+, somente driver), especifique Authentication=ActiveDirectoryIntegrated na cadeia de conexão. O driver escolherá o modo de autenticação correto automaticamente. Para as versões de driver 17.7 ou anterior, UID e PWD não devem ser especificados. A partir da versão 17.8 do driver UID e PWD serão ignorados.

• Para se conectar usando a autenticação interativa do Active Directory (somente driver do Windows), UID deve ser especificado. Para as versões de driver 17.7 ou anterior, PWD não deve ser especificado. A partir da versão 17.8 do driver PWD será ignorado.

• A partir da versão 18.1, Trusted_Connection=Yes não usa mais a autenticação federada do Microsoft Entra ID por padrão e, como alternativa, usa a integração de SSPI. Para usar o Microsoft Entra ID para esta opção, TrustedConnection_UseAAD=Yes deve ser configurado.

• As versões 17.7 e inferiores do driver ODBC têm um problema conhecido com o tempo limite de conexão quando a autenticação do AAD e a criptografia forçada estão habilitadas em uma instância SQL. O log de erros do SQL Server pode conter mensagens de erro como: "Erro: 33155, Gravidade: 20, Estado: 1. Um evento de desconexão foi gerado quando o servidor estava aguardando o token de autenticação federada. Isso pode ser devido ao encerramento do cliente ou à expiração do tempo limite do servidor.". Se você estiver usando soluções SQL de alta disponibilidade, como grupos de disponibilidade ou instâncias de cluster de failover, a comunicação interna do cluster para SQL poderá ser afetada por esse comportamento, que poderá afetar a disponibilidade dos recursos. No log do cluster, você pode ver mensagens de erro como: [hadrag] Connect to SQL Server ...ODBC Error: [HY000] [Microsoft][ODBC Driver 17 for SQL Server]An unknown error has occurred. Detailed error information is not available. (0). As versões 17.10 e superiores do driver ODBC corrigem esse problema e, com o SQL Server 2022 GDR KB5021522/CU1 KB5022375, o driver mais recente que contém essa correção é instalado durante a instalação do SQL. É possível verificar qual versão do driver ODBC você instalou consultando o administrador da fonte de dados ODBC.

• A partir da versão 18.3 do driver ODBC, a autenticação de Identidade Gerenciada (ActiveDirectoryMSI) é compatível no Azure Arc e no Azure Cloud Shell.

Autenticação com um token de acesso

O atributo de pré-conexão SQL_COPT_SS_ACCESS_TOKEN permite usar um token de acesso obtido do Microsoft Entra para autenticação, em vez do nome de usuário e senha, e também ignora a negociação e a obtenção de um token de acesso pelo driver. Para usar um token de acesso, defina o atributo de conexão SQL_COPT_SS_ACCESS_TOKEN como um ponteiro para uma estrutura ACCESSTOKEN:

typedef struct AccessToken
{
    DWORD dataSize;
    BYTE data[];
} ACCESSTOKEN;

O ACCESSTOKEN é uma estrutura de comprimento variável formada por um comprimento de 4 bytes seguido pelos bytes de comprimento dos dados opacos que formam o token de acesso. Devido ao modo como o SQL Server lida com os tokens de acesso, um token obtido por meio de uma resposta JSON do OAuth 2.0 deve ser expandido para que cada byte seja seguido por um byte de preenchimento zero, semelhante a uma cadeia de caracteres UCS-2 contendo apenas caracteres ASCII. No entanto, o token é um valor opaco e o comprimento especificado, em bytes, NÃO deve incluir terminadores nulos. Devido a suas restrições de comprimento e formato consideráveis, esse método de autenticação só está disponível programaticamente por meio do atributo de conexão SQL_COPT_SS_ACCESS_TOKEN. Não há palavras-chave correspondentes da cadeia de conexão e do DSN. A cadeia de conexão não deve conter as palavras-chave UID, PWD, Authentication ou Trusted_Connection.

Exemplos de autenticação do Microsoft Entra

O exemplo a seguir mostra o código necessário para se conectar ao SQL Server por meio do Microsoft Entra ID com palavras-chave de conexão. Não há necessidade de alterar o código do aplicativo em si. A cadeia de conexão (ou o DSN, se um for usado) é a única modificação necessária para usar o Microsoft Entra ID para autenticação:

    ...
    SQLCHAR connString[] = "Driver={ODBC Driver 18 for SQL Server};Server={server};UID=myuser;PWD=myPass;Authentication=ActiveDirectoryPassword;Encrypt=yes;"
    ...
    SQLDriverConnect(hDbc, NULL, connString, SQL_NTS, NULL, 0, NULL, SQL_DRIVER_NOPROMPT);
    ...

O exemplo a seguir mostra o código necessário para se conectar ao SQL Server por meio do Microsoft Entra ID com a autenticação de token de acesso. Nesse caso, é necessário modificar o código do aplicativo para processar o token de acesso e definir o atributo de conexão associado.

    SQLCHAR connString[] = "Driver={ODBC Driver 18 for SQL Server};Server={server};Encrypt=yes;"
    SQLCHAR accessToken[] = "eyJ0eXAiOi..."; // In the format extracted from an OAuth JSON response
    ...
    DWORD dataSize = 2 * strlen(accessToken);
    ACCESSTOKEN *pAccToken = malloc(sizeof(ACCESSTOKEN) + dataSize);
    pAccToken->dataSize = dataSize;
    // Expand access token with padding bytes
    for(int i = 0, j = 0; i < dataSize; i += 2, j++) {
        pAccToken->data[i] = accessToken[j];
        pAccToken->data[i+1] = 0;
    }
    ...
    SQLSetConnectAttr(hDbc, SQL_COPT_SS_ACCESS_TOKEN, (SQLPOINTER)pAccToken, SQL_IS_POINTER);
    SQLDriverConnect(hDbc, NULL, connString, SQL_NTS, NULL, 0, NULL, SQL_DRIVER_NOPROMPT);
    ...
    free(pAccToken);

Veja a seguir um exemplo de cadeia de conexão para ser usada com a Autenticação Interativa do Microsoft Entra ID. Ela não contém um campo PWD, pois a senha seria inserida usando a tela da Autenticação do Azure.

SQLCHAR connString[] = "Driver={ODBC Driver 18 for SQL Server};Server={server};UID=myuser;Authentication=ActiveDirectoryInteractive;Encrypt=yes;"

A cadeia de conexão de exemplo a seguir é para uso com a autenticação de identidade gerenciada do Microsoft Entra. A UID é definida como a ID de objeto/cliente da identidade do usuário ao usar uma identidade atribuída pelo usuário.

// For system-assigned identity,
SQLCHAR connString[] = "Driver={ODBC Driver 18 for SQL Server};Server={server};Authentication=ActiveDirectoryMsi;Encrypt=yes;"
...
// For user-assigned identity with object ID equals to myObjectId
SQLCHAR connString[] = "Driver={ODBC Driver 18 for SQL Server};Server={server};UID=myObjectId;Authentication=ActiveDirectoryMsi;Encrypt=yes;"

Considerações sobre o uso de contas federadas do ADFS em Linux/macOS

Da versão 17.6 em diante, os drivers para Linux e macOS dão suporte à autenticação usando contas federadas do ADFS do Microsoft Entra ID usando o nome de usuário/senha () ou Kerberos (). Há algumas limitações dependentes da plataforma ao usar o modo integrado.

Ao autenticar com um usuário cujo sufixo UPN é diferente do realm do Kerberos, ou seja, quando um sufixo UPN alternativo está sendo usado, é necessário usar a opção de entidade de segurança corporativa (use a opção -E com kinit e forneça o nome da entidade de segurança no formato user@federated-domain) ao obter tíquetes do Kerberos. Dessa forma, o driver pode determinar corretamente o domínio federado e o realm do Kerberos.

Você pode verificar se um tíquete Kerberos adequado está disponível inspecionando a saída do comando klist. Se o domínio federado for o mesmo que o realm do Kerberos e o sufixo UPN, o nome da entidade de segurança estará no formato user@realm. Se for diferente, o nome da entidade de segurança deverá ter o formato user@federated-domain@realm.

Linux

No SUSE 11, a versão padrão da biblioteca Kerberos 1.6.x não dá suporte à opção de entidade de segurança corporativa necessária para usar sufixos UPN alternativos. Para usar sufixos UPN alternativos com a autenticação integrada do Microsoft Entra, atualize a biblioteca Kerberos para 1.7 ou mais recente.

No Alpine Linux, o libcurl padrão não dá suporte à autenticação SPNEGO/Kerberos necessária para a autenticação integrada do Microsoft Entra.

macOS

A biblioteca Kerberos do sistema kinit dá suporte à entidade de segurança corporativa com a opção --enterprise, mas também realiza implicitamente a canonicalização do nome, o que impede o uso de sufixos UPN alternativos. Para usar sufixos UPN alternativos com a autenticação integrada do Microsoft Entra, instale uma biblioteca Kerberos mais recente via brew install krb5 e use sua kinit com a opção -E, conforme descrito acima.

Conteúdo relacionado

• Suporte à autenticação baseada em token para o Banco de Dados SQL do Azure usando a autenticação do Microsoft Entra
• Como usar a autenticação integrada