Usar o ID do Microsoft Entra com o Driver ODBC

Baixar driver ODBC

Observação

Embora o Microsoft Entra ID seja o novo nome para o Azure Ative Directory (Azure AD), para evitar a interrupção de ambientes existentes, o Azure AD ainda permanece em alguns elementos codificados, como campos de interface do usuário, provedores de conexão, códigos de erro e cmdlets. Neste artigo, os dois nomes são intercambiáveis.

Propósito

O Microsoft ODBC Driver para SQL Server versão 13.1 e superiores permite que aplicações ODBC se liguem à Base de Dados SQL do Azure ou Azure SQL Managed Instance usando identidades no Microsoft Entra ID. A autenticação pode ser feita com um nome de utilizador e palavra-passe, um token de acesso Microsoft Entra, uma identidade gerida Microsoft Entra (17.3+) ou Autenticação Integrada do Windows num ambiente federado, unido ao domínio (17.6+ em Linux/macOS). Para a versão 13.1 do Driver ODBC, a autenticação do token de acesso Microsoft Entra é apenas para Windows. O Driver ODBC versão 17 e superiores suporta esta autenticação em todas as plataformas (Windows, Linux e macOS). Um novo método interativo de autenticação Microsoft Entra, que suporta autenticação multifator, é introduzido no ODBC Driver versão 17.1 para Windows. Um novo método de autenticação de identidade gerida Microsoft Entra foi adicionado na versão 17.3.1.1 do Driver ODBC para identidades geridas atribuídas pelo sistema e atribuídas pelo utilizador. Todas estas opções são realizadas utilizando novas palavras-chave DSN, cadeias de ligação e atributos de ligação.

Para utilizar a autenticação Microsoft Entra, deve configurar a sua fonte de dados SQL do Azure. Para obter mais informações, consulte Configurar e gerir a autenticação de Microsoft Entra com SQL do Azure.

Observação

O driver ODBC nas versões do Linux e macOS anteriores à versão 17.6 suporta apenas autenticação Microsoft Entra diretamente com o Microsoft Entra ID. Se estiver a usar autenticação por nome de utilizador/palavra-passe Microsoft Entra a partir de um cliente Linux ou macOS e a sua configuração Microsoft Entra exigir que o cliente autentique num endpoint Microsoft Entra Federation Services, a autenticação pode falhar. A partir da versão 17.6 do driver, esta limitação foi removida.

Novas e/ou modificadas palavras-chave DSN e cadeia de ligação

A Authentication palavra-chave pode ser usada ao ligar com uma DSN ou cadeia de ligação para controlar o modo de autenticação. O valor definido na string de ligação sobrepõe-se ao da DSN, se for fornecido. O valor pré-atributo da Authentication definição é o valor calculado a partir da cadeia de ligação e dos valores DSN.

Nome	Valores/Predefinido	Description
Authentication	(not set)(default), (empty string), SqlPassword, ActiveDirectoryIntegratedActiveDirectoryInteractive, ActiveDirectoryMsi, ActiveDirectoryServicePrincipal, [ActiveDirectoryPassword OBSOLETO]	Controla o modo de autenticação. (not set) - Modo de autenticação determinado por outras palavras-chave (opções de ligação legadas existentes). (empty string) - (Apenas cadeia de ligação.) Substituir e desativar um valor de Authentication definido no DSN. SqlPassword - Autenticar diretamente para SQL usando um nome de utilizador e palavra-passe. ActiveDirectoryIntegrated - Windows, e Linux/Mac 17.6+, apenas com drivers. Autentifique com uma credencial Windows federada através do Microsoft Entra ID com autenticação integrada. ActiveDirectoryInteractive - Apenas driver para Windows. Autenticar com uma identidade Microsoft Entra usando autenticação interativa. ActiveDirectoryMsi - Autenticar com uma identidade gerida pela Microsoft Entra. Para uma identidade atribuída pelo utilizador, defina o UID como o ID de cliente da identidade no Serviço de Aplicações do Azure ou Azure Container Instance; caso contrário, utilize o ID do objeto da identidade. Para identidade atribuída ao sistema, UID não é obrigatório. ActiveDirectoryServicePrincipal - (17.7+) Autenticar com um principal de serviço Microsoft Entra. O UID é definido como o identificador do cliente da entidade de serviço. PWD é definido como o segredo do cliente. ActiveDirectoryPassword - [OBSOLETO] Autenticar com uma identidade Microsoft Entra usando um nome de utilizador e palavra-passe. ActiveDirectoryPassword está obsoleto. Para mais informações, consulte ActiveDirectoryPassword está obsoleto.
Encrypt	(not set) (por defeito), Yes/Mandatory (18.0 e versões posteriores), No/Optional (18.0 e versões posteriores), Strict (18.0 e versões posteriores)	Controla a encriptação de uma ligação. Quando não defines explicitamente a encriptação, o Driver 17 usa Yes por predefinição se o valor do pré-atributo de Authentication não for none ou SQL_COPT_SS_ACCESS_TOKEN for definido; caso contrário, o valor padrão é No. No Driver 18.0.1 e versões posteriores, o padrão é Yes (Mandatory). Autenticação e encriptação continuam a ser definições separadas. Se SQL_COPT_SS_AUTHENTICATION sobrescreve o valor do pré-atributo de Authentication, define explicitamente a encriptação na DSN, cadeia de ligação ou SQL_COPT_SS_ENCRYPT atributo connection.

Novos e/ou Modificados Atributos de Ligação

Os seguintes atributos de ligação pré-conexão foram introduzidos ou modificados para suportar a autenticação Microsoft Entra. Quando um atributo de conexão tem uma cadeia de ligação correspondente ou palavra-chave DSN e está definido, o atributo de ligação tem prioridade.

Attribute	Tipo	Valores	Predefinido	Description
SQL_COPT_SS_AUTHENTICATION	SQL_IS_INTEGER	SQL_AU_NONE, SQL_AU_PASSWORD, SQL_AU_AD_INTEGRATED, SQL_AU_AD_PASSWORDSQL_AU_AD_INTERACTIVE, SQL_AU_AD_MSI, SQL_AU_AD_SPA, SQL_AU_RESET	(não definido)	Veja a descrição da Authentication palavra-chave acima. SQL_AU_NONE é fornecido para sobrepor explicitamente um valor definido Authentication na DSN e/ou cadeia de conexão, enquanto SQL_AU_RESET remove o atributo caso ele tenha sido definido, permitindo que o valor da DSN ou da cadeia de conexão tenha prioridade.
SQL_COPT_SS_ACCESS_TOKEN	SQL_IS_POINTER	Apontador para ACCESSTOKEN ou NULL	NULO	Se não for nulo, especifica o token de acesso Microsoft Entra a utilizar. É um erro especificar um token de acesso assim como palavras-chave de cadeia de conexão UID, PWD, Trusted_Connection, ou Authentication ou os seus atributos equivalentes. NOTA: O driver ODBC versão 13.1 só suporta esta definição no Windows.
SQL_COPT_SS_ENCRYPT	SQL_IS_INTEGER	SQL_EN_OFF, SQL_EN_ON	(ver descrição)	Gere o pedido de cifragem do cliente. SQL_EN_OFF não impede que o servidor exija encriptação. No Driver 17, se não definires explicitamente a encriptação e o valor do pré-atributo de Authentication não for SQL_COPT_SS_ACCESS_TOKEN ou SQL_EN_ON estiver definido, o padrão é none. Caso contrário, o Driver 17 utiliza, por predefinição, SQL_EN_OFF. No Driver 18.0.1 e versões posteriores, o padrão é SQL_EN_ON independentemente da autenticação quando não se define explicitamente a encriptação. Se SQL_COPT_SS_AUTHENTICATION sobrescreve o valor do pré-atributo de Authentication, define explicitamente a encriptação na DSN, cadeia de ligação ou neste atributo. Para comportamento de encriptação e validação de certificados, veja Exemplos de cadeias de conexão.
SQL_COPT_SS_OLDPWD	-	-	-	Não é suportado com o Microsoft Entra ID, porque as alterações de palavra-passe para as entidades Microsoft Entra não podem ser feitas através de uma ligação ODBC. A expiração da palavra-passe para autenticação SQL Server foi introduzida no SQL Server 2005. O SQL_COPT_SS_OLDPWD atributo foi adicionado para permitir que o cliente forneça tanto a palavra-passe antiga como a nova para a ligação. Quando esta propriedade é definida, o fornecedor não usa o pool de ligações para a primeira ligação ou para ligações futuras, pois a cadeia de ligação contém a "palavra-passe antiga", que agora foi alterada.
SQL_COPT_SS_INTEGRATED_SECURITY	SQL_IS_INTEGER	SQL_IS_OFF,SQL_IS_ON	SQL_IS_OFF	Obsoleto; use SQL_COPT_SS_AUTHENTICATION defina como SQL_AU_AD_INTEGRATED em vez disso. Força o uso da Autenticação do Windows (Kerberos no Linux e macOS) para validação de acesso no login do servidor. Quando a Autenticação Windows é utilizada, o driver ignora os valores de identificador de utilizador e palavra-passe fornecidos durante o processamento de SQLConnect, SQLDriverConnect ou SQLBrowseConnect.

O ActiveDirectoryPassword está obsoleto

Importante

A opção de autenticação ActiveDirectoryPassword (autenticação por palavra-passe do Microsoft Entra ID) está obsoleta nos drivers SQL da Microsoft. Este fluxo de autenticação de alto risco é incompatível com a autenticação multifator (MFA) obrigatória da Microsoft Entra e pode não funcionar em inquilinos onde a MFA é aplicada. Planeio migrar para um método de autenticação Microsoft Entra diferente.

A autenticação por palavra-passe do Microsoft Entra ID baseia-se na concessão OAuth 2.0 Resource Owner Password Credentials (ROPC), que permite a uma aplicação iniciar a sessão do utilizador processando diretamente a respetiva palavra-passe.

A Microsoft recomenda que não uses o fluxo ROPC porque é incompatível com o MFA. Na maioria dos cenários, alternativas mais seguras estão disponíveis e são recomendadas. Este fluxo exige um elevado grau de confiança na aplicação e acarreta riscos que não existem noutros fluxos. Use este fluxo apenas quando fluxos mais seguros não forem viáveis. A Microsoft está a afastar-se deste fluxo de autenticação de alto risco para proteger os utilizadores de ataques maliciosos. Para mais informações, consulte Planeamento para autenticação multifator obrigatória para Azure.

Quando um utilizador estiver presente no início de sessão, utilize a autenticação ActiveDirectoryInteractive ou ActiveDirectoryIntegrated para que o registo de auditoria seja atribuído ao utilizador com sessão iniciada e as políticas de Acesso Condicional se apliquem.

Para cenários de serviço para serviço não supervisionados, siga as orientações sobre contas de serviço do Microsoft Entra:

• Se a sua aplicação correr na infraestrutura Azure, use o ActiveDirectoryMSI (ou o ActiveDirectoryManagedIdentity em alguns drivers). As identidades geridas eliminam a sobrecarga de manter e rotacionar segredos e certificados.
• Se a identidade gerida não estiver disponível (por exemplo, se a aplicação estiver a ser executada fora do Azure), use o ActiveDirectoryServicePrincipal. Quando o driver o permite, prefira um certificado de cliente em vez de um segredo de cliente. Com um certificado, a chave privada permanece no cliente e apenas uma asserção assinada é enviada à Microsoft Entra para autenticar o cliente. Se a chave estiver armazenada em hardware (como um TPM ou HSM) ou marcada como não exportável, não pode ser extraída sob a forma de uma cadeia de caracteres, da mesma forma que um segredo do cliente pode.
• Não use uma conta de utilizador Microsoft Entra como conta de serviço.

Adições de Interface de Utilizador para o Microsoft Entra ID (apenas controlador Windows)

A configuração da DSN e as interfaces de ligação do driver foram melhoradas com as opções adicionais necessárias para autenticar com o Microsoft Entra ID.

Criar e editar DSNs na interface de utilizador

É possível usar as opções de autenticação do Microsoft Entra ao criar ou editar uma DSN existente usando a interface de configuração do driver:

Authentication=ActiveDirectoryIntegrated para autenticação integrada do Microsoft Entra no SQL do Azure

Authentication=ActiveDirectoryPassword para autenticação de utilizador e senha do Microsoft Entra no SQL do Azure

Observação

O ActiveDirectoryPassword está obsoleto. Para mais informações, consulte ActiveDirectoryPassword está obsoleto.

Authentication=ActiveDirectoryInteractive para autenticação interativa do Microsoft Entra com SQL do Azure

Observação

A partir da versão 17.9 do driver, o comportamento de autenticação interativa mudou. Os utilizadores serão sempre solicitados a obter credenciais, a menos que o driver tenha um token de acesso válido armazenado em cache. Esta alteração impede que os utilizadores em dispositivos associados ao Microsoft Entra ignorem o pedido e iniciem sessão automaticamente com credenciais em cache ao usar a autenticação de ActiveDirectoryInteractive.

Authentication=SqlPassword para autenticação por nome de utilizador/palavra-passe para SQL Server e SQL do Azure

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

Authentication=ActiveDirectoryMsi para a autenticação de identidade gerida da Microsoft Entra

Authentication=ActiveDirectoryServicePrincipal para autenticação do principal de serviço Microsoft Entra

As sete opções correspondem a Trusted_Connection=Yes (autenticação integrada existente apenas para Windows SSPI) e Authentication=ActiveDirectoryIntegrated, SqlPassword, ActiveDirectoryPassword, ActiveDirectoryInteractive, ActiveDirectoryMsi, , e ActiveDirectoryServicePrincipal respetivamente.

SQLDriverConnect Prompt (apenas driver Windows)

O diálogo de aviso apresentado pelo SQLDriverConnect quando solicita a informação necessária para completar a ligação contém quatro novas opções para a autenticação Microsoft Entra:

Estas opções correspondem às mesmas seis disponíveis na interface de configuração DSN acima.

Exemplo de cadeias de conexão

Observação

As descrições de encriptação e de validação de certificados nestes exemplos aplicam-se a conexões remotas comuns sem sobreposições DSN ou atributos de conexão, definições do registo do Windows Force Protocol Encryption, ou callbacks internos de validação de certificados do Windows. Descrevem a encriptação não-Strict. A encriptação apenas no início de sessão protege a troca de autenticação, não os dados subsequentes da aplicação.

Com Encrypt=yes e TrustServerCertificate=no (o padrão), os drivers 17 e 18 solicitam encriptação de sessão completa e validam o certificado do servidor. Se o cliente definir Encrypt=no mas o servidor exigir encriptação de sessão completa, o Driver 17 não seleciona a validação normal do certificado para esse pedido só do servidor. O Driver 18 verifica o estado de encriptação da sessão completa negociado e valida o certificado, a menos que TrustServerCertificate=yes. No percurso normal sem Strict, TrustServerCertificate=yes suprime a validação normal; a encriptação forçada pelo registo do Windows pode selecionar a validação independentemente dessa definição, e um callback interno do Windows pode substituir o caminho normal de validação.

1. Autenticação SQL Server - sintaxe legada. O certificado do servidor não é validado, e a encriptação só é usada se o servidor a aplicar. O nome de utilizador/palavra-passe é passado na cadeia de ligação.

   server=Server;database=Database;UID=UserName;PWD=<password>;Encrypt=no;TrustServerCertificate=yes;

2. Autenticação SQL - nova sintaxe. Ao usar Authentication=SqlPassword e omitir encriptação como mostrado, os Drivers 17 e 18 por defeito solicitam encriptação de sessão completa. O driver valida o certificado do servidor com a predefinição TrustServerCertificate=no. O nome de utilizador e a palavra-passe estão na cadeia de ligação.

   server=Server;database=Database;UID=UserName;PWD=<password>;Authentication=SqlPassword;

3. Autenticação integrada do Windows (Kerberos em Linux e macOS) usando SSPI (para SQL Server ou SQL IaaS) - sintaxe atual. Com Encrypt=no, a encriptação de sessão completa é usada apenas se o servidor a necessitar. Para esse pedido apenas ao servidor, o Driver 17 não seleciona validação normal de certificados; o Driver 18 valida com o padrão TrustServerCertificate=no.

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

4. (Apenas driver para Windows.) Autenticação integrada do Windows usando SSPI (se a base de dados de destino estiver em SQL Server ou SQL Server em VMs Azure) - nova sintaxe. Ao usar Authentication=ActiveDirectoryIntegrated e omitir encriptação como mostrado, os Drivers 17 e 18 por defeito solicitam encriptação de sessão completa. O driver valida o certificado do servidor com a predefinição TrustServerCertificate=no.

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

5. Autenticação de nome de utilizador e palavra-passe do Microsoft Entra (se a base de dados de destino estiver no Base de Dados SQL do Azure ou no Azure SQL Managed Instance). O pedido explícito Encrypt=yes solicita encriptação de sessão completa. O driver valida o certificado do servidor com a predefinição TrustServerCertificate=no. O nome de utilizador e a palavra-passe estão na cadeia de ligação.

   Observação

   O ActiveDirectoryPassword está obsoleto. Para mais informações, consulte ActiveDirectoryPassword está obsoleto.

   server=Server;database=Database;UID=UserName;PWD=<password>;Authentication=ActiveDirectoryPassword;Encrypt=yes;

6. (Windows, e versões Linux/macOS 17.6 e posteriores, apenas o controlador.) Autenticação Windows integrada usando ADAL ou Kerberos, que envolve trocar as credenciais da conta Windows por um token de acesso do Microsoft Entra, assumindo que a base de dados alvo está em SQL do Azure. A opção explícita Encrypt=yes solicita encriptação de sessão completa. O driver valida o certificado do servidor com a predefinição TrustServerCertificate=no. No Linux/macOS, é necessário disponer de um bilhete Kerberos adequado. Para mais informações, consulte Considerações para o uso de Contas Federadas ADFS em Linux/macOS e Utilização de Autenticação Integrada.

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

7. (Apenas driver Windows.) A Autenticação Interativa Microsoft Entra utiliza a tecnologia de autenticação multifator Microsoft Entra para estabelecer uma ligação. Podes omitir UID com o Driver 17.8 e versões posteriores, ou defini-lo como a conta de utilizador para autenticar. Quando fornece UID, o diálogo de login pode não oferecer uma forma de selecionar outra conta. Para usar outra conta, mude UID antes de estabelecer ligação, ou omita-a com o Driver 17.8 e versões posteriores. O driver abre um diálogo de Autenticação Azure para que o utilizador possa completar qualquer verificação adicional.

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

   

8. A autenticação de identidade gerida Microsoft Entra pode usar uma identidade gerida atribuída pelo sistema ou pelo utilizador. Para uma identidade atribuída pelo utilizador, defina o UID como o ID de cliente da identidade no Serviço de Aplicações do Azure ou Azure Container Instance; caso contrário, utilize o ID do objeto da identidade. Para identidade atribuída ao sistema, UID não é obrigatório.

   Para a identidade atribuída ao sistema:

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

   Para identidade atribuída pelo utilizador com ID de objeto igual a myObjectId:

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

9. Autenticação do principal de serviço Microsoft Entra

   server=Server;database=Database;UID=clientId;PWD=<password>;Authentication=ActiveDirectoryServicePrincipal;Encrypt=yes;

Observações

• Ao utilizar as opções Microsoft Entra com o driver Windows ODBC anterior à versão 17.4.2, certifique-se de que a Biblioteca de Autenticação do Active Directory para SQL Server foi instalada. Ao usar os drivers Linux e macOS, certifique-se de que está libcurl instalado. Para a versão 17.2 do driver e posteriores, esta não é uma dependência explícita, pois não é necessária para os outros métodos de autenticação ou operações ODBC.

• Quando a configuração Microsoft Entra inclui políticas de acesso condicional, e o cliente é Windows 10 ou Server 2016 ou posterior, a autenticação via Integrated ou nome de utilizador/palavra-passe pode falhar. As políticas de acesso condicional requerem o uso do Web Account Manager (WAM), que é suportado na versão 17.6 ou posterior do driver para Windows. Para usar WAM, crie um novo valor de cadeia nomeado 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, DSN de utilizador ou DSN do sistema, respetivamente, e defina-o para um valor de 1. Note que a autenticação com WAM não suporta a execução da aplicação como um utilizador diferente com runas. Cenários que requerem políticas de Acesso Condicional não são suportados para Linux ou macOS.

• Para se ligar utilizando um nome de utilizador e palavra-passe de conta SQL Server, pode agora usar a nova opção SqlPassword, recomendada especialmente para SQL do Azure, pois esta opção permite definições de ligação predefinidas mais seguras.

• Para se ligar usando um nome de utilizador e palavra-passe de uma conta Microsoft Entra, especifique Authentication=ActiveDirectoryPassword na cadeia de ligação, juntamente com as palavras-chave UID e PWD, correspondendo ao nome de utilizador e à palavra-passe, respetivamente.

  Observação

  O ActiveDirectoryPassword está obsoleto. Para mais informações, consulte ActiveDirectoryPassword está obsoleto.

• Para se ligar usando autenticação Windows Integrated ou Microsoft Entra Integrated (Windows, e Linux/macOS 17.6+, apenas driver), especifique Authentication=ActiveDirectoryIntegrated na cadeia de ligação. O condutor escolherá automaticamente o modo de autenticação correto. Para versões do driver 17.7 ou anteriores, UID e PWD não devem ser especificados. A partir da versão 17.8, UID e PWD do driver são ignorados.

• Para se ligar usando a autenticação interativa do Microsoft Entra (apenas para o driver do Windows), pode omitir UID com o Driver 17.8 e versões posteriores, ou defini-lo como a conta de utilizador para autenticar. O diálogo de iniciar sessão pode não permitir que mude de conta quando introduz UID. Para usar outra conta, mude UID antes de estabelecer a ligação, ou omite-a com o Driver 17.8 e versões posteriores. As versões do driver 17.7 e anteriores exigem UID e proíbem PWD. A partir da versão 17.8 do driver, PWD é ignorada.

• A partir da versão 18.1, Trusted_Connection=Yes deixou de usar por defeito a autenticação federada Microsoft Entra ID, passando a usar em alternativa SSPI integrada. Para usar o ID Microsoft Entra para esta opção, TrustedConnection_UseAAD=Yes deve estar 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 Microsoft Entra e a funcionalidade Force Encryption estão ativadas numa instância do SQL Server. O registo de erros do SQL Server pode conter mensagens de erro tais como: "Erro: 33155, Gravidade: 20, Estado: 1. Foi gerado um evento de desconexão quando o servidor está à espera do token de Autenticação Federada. Isto pode dever-se ao encerramento do cliente ou ao timeout do servidor expirado.". Se estiver a usar soluções de alta disponibilidade, como grupos de disponibilidade Always On ou instâncias de clusters de failover, a comunicação interna do cluster para SQL Server pode ser afetada por este comportamento, o que pode afetar a disponibilidade de recursos. No registo do cluster, 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 este problema e, com o SQL Server 2022 GDR KB5021522 /CU1 KB5022375, o driver mais recente que contém esta correção é instalado com a instalação do SQL Server. Pode verificar qual a versão do driver ODBC que tem instalado consultando o Administrador da Fonte de Dados ODBC.

• A partir da versão 18.3 do driver ODBC, a autenticação por Identidade Gerida (ActiveDirectoryMSI) é suportada no Azure Arc e no Azure Cloud Shell.

Autenticação com um token de acesso

O SQL_COPT_SS_ACCESS_TOKEN atributo pré-conexão permite o uso de um token de acesso obtido do ID Microsoft Entra para autenticação em vez de nome de utilizador e palavra-passe, e também contorna a negociação e obtenção de um token de acesso pelo driver. Para usar um token de acesso, defina o SQL_COPT_SS_ACCESS_TOKEN atributo de ligação como um ponteiro para uma ACCESSTOKEN estrutura:

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

É ACCESSTOKEN uma estrutura de comprimento variável composta por um comprimento de 4 bytes seguido de bytes de comprimento de dados opacos que formam o token de acesso. Devido à forma como o SQL Server gere os tokens de acesso, um obtido através de uma resposta OAuth 2.0 JSON deve ser expandido para que cada byte seja seguido por um byte de enchimento zero, semelhante a uma string UCS-2 contendo apenas caracteres ASCII. No entanto, o token é um valor opaco e o comprimento especificado, em bytes, NÃO deve incluir nenhum terminador nulo. Devido às consideráveis restrições de comprimento e formato, este método de autenticação só está disponível programaticamente através do SQL_COPT_SS_ACCESS_TOKEN atributo de conexão.

Deve manter o ACCESSTOKEN alocado enquanto o handle de ligação estiver alocado. Caso contrário, podem ocorrer violações de acesso. Quando usa o Gestor de Drivers ODBC do Windows, o ponteiro de token faz parte da chave do pool de ligação, por isso um ponteiro diferente seleciona um pool diferente. Mantenha o buffer associado à mesma identidade quando substituir um token expirado. Atualizar o buffer não altera a identidade de uma ligação já autenticada.

Caution

No Linux e macOS, o pooling de ligações unixODBC não usa SQL_COPT_SS_ACCESS_TOKEN para distinguir identidades. Quando usas a mesma cadeia de ligação, um pedido de ligação com um token diferente pode reutilizar uma ligação em pool autenticada como a identidade anterior. Se o seu processo se ligar a tokens para diferentes identidades, desative o agrupamento unixODBC antes de o iniciar: defina Pooling=No na secção [ODBC] do ficheiro efetivo odbcinst.ini e certifique-se de que a sua aplicação e as suas bibliotecas não ativam o pooling ODBC. Reinicie os processos de aplicação existentes após alterar a configuração. Não dependas de mudar os ponteiros dos tokens para isolar identidades.

Não existe uma palavra-chave correspondente a um DSN ou uma string de conexão. A cadeia de ligação não deve conter UID, PWD, Authentication, ou Trusted_Connection palavras-chave.

Observação

A versão 13.1 do Driver ODBC só suporta esta autenticação no Windows. As versões subsequentes suportam esta autenticação em todas as plataformas.

Código de exemplo de autenticação Microsoft Entra

O exemplo seguinte mostra o código necessário para se ligar ao SQL Server usando o Microsoft Entra ID com palavras-chave de ligação. Não há necessidade de alterar o código da aplicação em si. A cadeia de ligação, ou DSN se for usada, é 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=<password>;Authentication=ActiveDirectoryInteractive;Encrypt=yes;"
    ...
    SQLDriverConnect(hDbc, NULL, connString, SQL_NTS, NULL, 0, NULL, SQL_DRIVER_NOPROMPT);
    ...

O exemplo seguinte mostra o código necessário para se ligar ao SQL Server usando a autenticação do token de acesso Microsoft Entra. Neste caso, é necessário modificar o código da aplicação para processar o token de acesso e definir o atributo de ligaçã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);

A seguinte string de conexão de exemplo destina-se à autenticação interativa com o Microsoft Entra. Não contém o campo PWD, pois a palavra-passe seria introduzida no ecrã de Autenticação Azure.

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

A seguinte cadeia de ligação de exemplo destina-se à autenticação de identidade gerida pelo Microsoft Entra. O UID é definido como o ID do objeto/cliente da identidade do utilizador quando se utiliza uma identidade atribuída pelo utilizador.

// 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 para a utilização de Contas Federadas ADFS em Linux/macOS

A partir da versão 17.6, os drivers para Linux e macOS suportam autenticação usando contas federadas Microsoft Entra ADFS , utilizando nome de utilizador/palavra-passe (ActiveDirectoryPassword) ou Kerberos (ActiveDirectoryIntegrated). Existem algumas limitações dependendo da plataforma ao usar o modo Integrado.

Ao autenticar com um utilizador cujo sufixo UPN é diferente do domínio Kerberos, ou seja, se estiver em uso um sufixo UPN alternativo, é necessário usar a opção Enterprise Principal (usar a -E opção com kinit, e fornecer o nome principal no formulário user@federated-domain) ao obter bilhetes Kerberos. Desta forma, o driver pode determinar corretamente tanto o domínio federado como o reino Kerberos.

Pode verificar se existe um ticket Kerberos adequado ao inspecionar a saída do klist comando. Se o domínio federado for o mesmo que o domínio de Kerberos e o sufixo UPN, o nome principal é da forma user@realm. Se for diferente, o nome principal deve ser da forma user@federated-domain@realm.

Linux

No SUSE 11, a versão padrão da biblioteca Kerberos da 1.6.x não suporta a opção Enterprise Principal necessária para usar sufixos UPN alternativos. Para usar sufixos UPN alternativos com autenticação integrada Microsoft Entra, atualize a biblioteca Kerberos para a versão 1.7 ou mais recente.

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

macOS

A biblioteca kinit Kerberos do sistema suporta Enterprise Principal com a --enterprise opção, mas também implicitamente faz a canonização dos nomes, 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 o seu kinit com a opção -E conforme descrito acima.

Conteúdo relacionado

• Suporte de autenticação baseada em token para Base de Dados SQL do Azure usando a autenticação Microsoft Entra
• Utilização da Autenticação Integrada