Autenticação Microsoft Entra com mssql-python

O Microsoft Entra ID fornece autenticação baseada em identidade para Banco de Dados SQL do Azure, Instância Gerenciada de SQL do Azure e banco de dados SQL no Microsoft Fabric por meio do driver mssql-python. A autenticação Microsoft Entra oferece estas capacidades sobre a autenticação SQL:

• Gerenciamento centralizado de identidade por meio do Microsoft Entra ID.
• Autenticação baseada em token que elimina a necessidade de senhas.
• Suporte para políticas de acesso condicional.
• Identidades gerenciadas para aplicações hospedadas no Azure.

O driver mssql-python oferece suporte a sete modos de autenticação do Microsoft Entra, todos configurados por meio da palavra-chave Authentication da cadeia de conexão.

Modos de autenticação

Defina a Authentication palavra-chave na sua cadeia de conexão para um dos seguintes valores:

DefaultAzureCredential

O modo ActiveDirectoryDefault usa DefaultAzureCredential do SDK Azure Identity, que tenta estes métodos de autenticação na seguinte ordem:

1. Variáveis de ambiente.
2. Identidade da carga de trabalho para Kubernetes.
3. Identidade gerenciada.
4. Credenciais da CLI do Azure.
5. Credenciais do Azure PowerShell.
6. Credenciales CLI de Azure Developer.
7. Navegador interativo, se ativado.

Exemplo: Autenticação padrão

O exemplo a seguir se conecta com ActiveDirectoryDefault, que usa a DefaultAzureCredential cadeia para encontrar automaticamente uma credencial válida:

import mssql_python

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryDefault;"
    "Encrypt=yes;"
)

cursor = conn.cursor()
cursor.execute("SELECT USER_NAME()")
print(f"Connected as: {cursor.fetchval()}")

Use esse modo para desenvolvimento local porque ele capta automaticamente as credenciais do CLI do Azure. Para produção, use um modo de autenticação específico (ActiveDirectoryMSI, ActiveDirectoryServicePrincipal) em vez disso. DefaultAzureCredential percorre vários provedores de credenciais na primeira conexão, o que aumenta a latência de forma desnecessária para cargas de trabalho de produção.

Autenticação interativa

Para aplicações interativas, utilize autenticação baseada em navegador. O usuário deve ter uma conta de banco de dados criada com CREATE USER [user@domain.com] FROM EXTERNAL PROVIDER. Para todos os pré-requisitos, veja Configurar autenticação Microsoft Entra.

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryInteractive;"
    "Encrypt=yes;"
)

No Windows, esse modo delega ao fluxo interativo nativo do driver ODBC. Em outras plataformas, ele utiliza a autenticação baseada em navegador do Azure Identity SDK.

Autenticação de código de dispositivo

Use autenticação por código de dispositivo para ambientes sem navegador, como sessões SSH ou containers. O usuário deve ter uma conta de banco de dados criada com CREATE USER [user@domain.com] FROM EXTERNAL PROVIDER. Para pré-requisitos, veja Configurar autenticação Microsoft Entra.

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryDeviceCode;"
    "Encrypt=yes;"
)
# Output: To sign in, use a web browser to open https://microsoft.com/devicelogin
# and enter the code XXXXXXX to authenticate.

Siga o aviso para autenticar em um navegador em outro dispositivo.

Autenticação do principal de serviço

Use autenticação do principal de serviço para aplicações automatizadas que não exigem interação do usuário:

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryServicePrincipal;"
    "UID=<client-id>;"       # Application (client) ID
    "PWD=<client-secret>;"   # Client secret
    "Encrypt=yes;"
)

Criar um principal de serviço

1. Registrar um aplicativo no Microsoft Entra ID.
2. Crie um segredo de cliente.
3. Conceda ao principal do serviço acesso ao seu banco de dados:

-- In Azure SQL
CREATE USER [app-name] FROM EXTERNAL PROVIDER;
ALTER ROLE db_datareader ADD MEMBER [app-name];
ALTER ROLE db_datawriter ADD MEMBER [app-name];

CREATE USER [app-name] FROM EXTERNAL PROVIDER
    WITH OBJECT_ID = '<enterprise-app-object-id>';

Identidade gerenciada

Use autenticação de identidade gerenciada para aplicações hospedadas no Azure, como App Service, Azure Functions e VMs:

Identidade gerenciada atribuída pelo sistema

Conecte-se usando a identidade atribuída diretamente ao recurso Azure:

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryMSI;"
    "Encrypt=yes;"
)

Identidade gerenciada atribuída pelo usuário

Especifique o ID do cliente de uma identidade gerenciada atribuída pelo usuário no UID campo:

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryMSI;"
    "UID=<managed-identity-client-id>;"
    "Encrypt=yes;"
)

Configurar acesso ao banco de dados

Conceda à identidade gerenciada acesso ao seu banco de dados. Um administrador do Microsoft Entra deve estar configurado no servidor antes que você possa criar usuários externos. Para habilitar a identidade gerenciada no seu recurso Azure, veja Identidades gerenciadas para recursos Azure.

-- Replace 'my-app-service' with your Azure resource name
CREATE USER [my-app-service] FROM EXTERNAL PROVIDER;
ALTER ROLE db_datareader ADD MEMBER [my-app-service];
ALTER ROLE db_datawriter ADD MEMBER [my-app-service];

Autenticação por senha (obsoleta)

A autenticação por senha do Microsoft Entra ID baseia-se na concessão ROPC (Credenciais de Senha do Proprietário do Recurso) do OAuth 2.0, que permite que um aplicativo conecte o usuário ao lidar diretamente com sua senha.

Microsoft recomenda que você não use o fluxo ROPC porque ele é incompatível com a MFA. Na maioria dos cenários, alternativas mais seguras estão disponíveis e são recomendadas. Esse fluxo requer um alto grau de confiança no aplicativo e traz riscos que não estão presentes em outros fluxos. Use esse fluxo somente quando fluxos mais seguros não forem viáveis. A Microsoft está se afastando desse fluxo de autenticação de alto risco para proteger os usuários contra ataques mal-intencionados. Para obter mais informações, consulte Planejamento para autenticação multifator obrigatória do Azure.

Quando houver um usuário presente no momento do logon, use a autenticação ActiveDirectoryInteractive ou ActiveDirectoryIntegrated para que a trilha de auditoria seja atribuída ao usuário conectado e as políticas de Acesso Condicional se apliquem.

Para cenários não assistidos de serviço a serviço, siga as orientações sobre conta de serviço do Microsoft Entra:

• Se o aplicativo é executado na infraestrutura do Azure, use ActiveDirectoryMSI (ou ActiveDirectoryManagedIdentity em alguns drivers). As identidades gerenciadas eliminam a sobrecarga de manutenção e rotação de segredos e certificados.
• Se a identidade gerenciada não estiver disponível (por exemplo, o aplicativo será executado fora Azure), use ActiveDirectoryServicePrincipal. Quando o driver dá suporte a ele, prefira um certificado de cliente em vez de um segredo do cliente. Com um certificado, a chave privada permanece no cliente e apenas uma declaração assinada é enviada para 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, ela não poderá ser copiada para fora como uma cadeia de caracteres da mesma forma que um segredo do cliente pode.
• Não use uma conta de usuário Microsoft Entra como uma conta de serviço.

Use autenticação por senha quando precisar de um nome de usuário e senha com uma conta Microsoft Entra. O usuário deve ter uma conta de banco de dados criada com CREATE USER [user@domain.com] FROM EXTERNAL PROVIDER:

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryPassword;"
    "UID=<login@domain.com>;"
    "PWD=<password>;"
    "Encrypt=yes;"
)

Autenticação integrada ao Windows

Use autenticação integrada ao Windows para ambientes Windows unidos a domínio com Kerberos. Esse modo exige que seu Active Directory local esteja federado com o Microsoft Entra ID e um administrador da Microsoft Entra configurado no servidor:

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryIntegrated;"
    "Encrypt=yes;"
)

Esse modo utiliza as credenciais Kerberos do usuário atual do Windows. No Linux e macOS, você deve configurar o Kerberos manualmente (krb5.conf e um keytab ou ticket válido). Veja Usar autenticação do Active Directory com SQL Server em Linux para configuração do Kerberos do lado do cliente.

Autenticação de token de acesso

Você pode adquirir tokens externamente, por exemplo, por meio de um provedor de tokens personalizado ou cache compartilhado de tokens. Nesses casos, use SQL_COPT_SS_ACCESS_TOKEN com o parâmetro attrs_before para passar o token diretamente. Essa abordagem contorna o fluxo de aquisição de tokens embutido pelo driver.

import mssql_python
from azure.identity import DefaultAzureCredential
import struct

def get_token():
    credential = DefaultAzureCredential(
        exclude_interactive_browser_credential=False
    )
    token_bytes = credential.get_token(
        "https://database.windows.net/.default"
    ).token.encode("utf-16le")
    token_struct = struct.pack(
        f'<I{len(token_bytes)}s', len(token_bytes), token_bytes
    )
    return token_struct

SQL_COPT_SS_ACCESS_TOKEN = 1256

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;",
    attrs_before={SQL_COPT_SS_ACCESS_TOKEN: get_token()}
)

Escolher um modo de autenticação

Troubleshoot

Falha no logon do usuário 'NT AUTHORITY\ANONYMOUS LOGON'

Verifique se o usuário ou identidade gerenciada existe no banco de dados:

CREATE USER [identity-name] FROM EXTERNAL PROVIDER;

"AADSTS700016: Aplicação não encontrada"

A entidade de serviço ou o ID do aplicativo está incorreto. Verifique o ID do cliente e se o aplicativo está registrado no seu tenant Microsoft Entra.

Endpoint de Identidade Gerenciada não está acessível

• Verifique se a identidade gerenciada está ativada no recurso do Azure.
• Para a identidade atribuída ao usuário, verifique se o ID do cliente está correto.
• Verifique se o recurso tem acesso de rede ao endpoint de identidade.

Tempo limite para aquisição de tokens

ActiveDirectoryDefault usa DefaultAzureCredential, que percorre uma cadeia de provedores de credenciais em sequência até que um tenha sucesso. Esse percurso pela cadeia adiciona segundos de latência à conexão inicial, especialmente quando provedores anteriores da cadeia (variáveis de ambiente, identidade de carga de trabalho) falham antes de alcançar o provedor que funciona. Em produção, especifique diretamente o tipo de credencial para pular a cadeia:

# Slow: DefaultAzureCredential tries multiple providers
conn = mssql_python.connect(connection_string, authentication="ActiveDirectoryDefault")

# Fast: Skip directly to managed identity
conn = mssql_python.connect(connection_string, authentication="ActiveDirectoryMSI")

Conteúdo relacionado

• Strings de conexão
• Solução de problemas
• Migração sem senha para SQL do Azure
• Autenticação do SQL do Azure com o Microsoft Entra