Autenticação do Microsoft Entra com mssql-django

Este artigo explica como configurar a autenticação Microsoft Entra para aplicativos Django usando o mssql-django back-end. A autenticação do Microsoft Entra elimina a necessidade de armazenar senhas na configuração do seu aplicativo.

Pré-requisitos

• Microsoft ODBC Driver 18 para SQL Server (recomendado). Todos os modos de autenticação neste artigo têm suporte com Microsoft ODBC Driver 18 para SQL Server. ActiveDirectoryInteractive é somente para Windows, independentemente da versão do driver. Se você precisar usar o ODBC Driver 17, consulte a referência de autenticação ODBC para versões mínimas de 17.x por modo.
• Para autenticação de token de acesso: pip install azure-identity.

Métodos de autenticação

Configure cada um dos métodos adicionando ou editando a configuração DATABASES no arquivo settings.py do seu projeto Django. Os exemplos neste artigo mostram o bloco completo DATABASES["default"] para maior clareza; copie as chaves relevantes para sua configuração existente.

mssql-djangodá suporte à autenticação Microsoft Entra de duas maneiras:

• Autenticação do driver ODBC por meio de OPTIONS["extra_params"]. O backend acrescenta esta string à string de conexão ODBC sem alterações; portanto, os valores Authentication= disponíveis vêm do Driver ODBC da Microsoft para SQL Server instalado, não do próprio mssql-django.
• Autenticação com token de acesso programático por meio da configuração TOKEN. O back-end passa TOKEN para o driver ODBC como SQL_COPT_SS_ACCESS_TOKEN, o que ignora a palavra-chave ODBC Authentication= .

Métodos de autenticação em um relance

Conceder acesso à identidade no SQL do Azure

Para autenticação de identidade gerenciada ou entidade de serviço, crie um usuário de banco de dados e conceda apenas as funções de que seu aplicativo precisa:

CREATE USER [<identity-name>] FOR EXTERNAL PROVIDER;

ALTER ROLE db_datareader ADD MEMBER [<identity-name>];
ALTER ROLE db_datawriter ADD MEMBER [<identity-name>];
ALTER ROLE db_ddladmin ADD MEMBER [<identity-name>];

A função de banco de dados fixa db_ddladmin será necessária somente se o aplicativo executar migrações. Para cargas de trabalho somente de leitura, db_datareader é suficiente.

CREATE USER [<identity-name>] WITH SID = 0x<sid-hex>, TYPE = E;

$b = ([Guid]"<app-id>").ToByteArray()
"0x" + (($b | ForEach-Object { $_.ToString('X2') }) -join '')

Se você vir o erro VIEW ANY COLUMN MASTER KEY DEFINITION permission denied, conceda acesso adicional à identidade para cenários do Always Encrypted:

GRANT VIEW ANY COLUMN MASTER KEY DEFINITION TO [<identity-name>];
GRANT VIEW ANY COLUMN ENCRYPTION KEY DEFINITION TO [<identity-name>];

Autenticação de identidade gerenciada (ActiveDirectoryMsi)

Use a identidade gerenciada quando seu aplicativo Django for executado em um serviço de Azure, como Serviço de Aplicativo do Azure, Aplicativos de Contêiner do Azure ou Máquinas Virtuais do Azure. Essa abordagem é recomendada para ambientes de produção porque o driver ODBC adquire e atualiza tokens automaticamente.

Identidade gerenciada atribuída pelo sistema:

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "HOST": "<your-server>.database.windows.net",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
            "extra_params": "Authentication=ActiveDirectoryMsi",
        },
    },
}

Identidade gerenciada atribuída pelo usuário:

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "HOST": "<your-server>.database.windows.net",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
            "extra_params": (
                "Authentication=ActiveDirectoryMsi;"
                "UID=<managed-identity-client-id-or-object-id>"
            ),
        },
    },
}

ActiveDirectoryMsi é o modo ODBC para SAMI (identidade gerenciada) atribuída pelo sistema e UAMI (identidade gerenciada atribuída pelo usuário). Para UAMI, o driver ODBC espera que UID identifique a identidade gerenciada: use o ID do cliente para o Serviço de Aplicativo do Azure ou o Azure Container Instance; caso contrário, use o ID do objeto. Coloque isso UID dentro de extra_params, porque extra_params é transmitido diretamente para o driver ODBC.

Se você usar a identidade gerenciada, crie o banco de dados de teste manualmente e passe --keepdb ao executar testes de unidade.

Autenticação de service principal (ActiveDirectoryServicePrincipal)

Use um registro de aplicativo do Microsoft Entra (service principal) quando seu aplicativo for executado sem contexto de usuário e a identidade gerenciada não estiver disponível.

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "USER": "<application-client-id>",
        "PASSWORD": "<client-secret>",
        "HOST": "<your-server>.database.windows.net",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
            "extra_params": "Authentication=ActiveDirectoryServicePrincipal",
        },
    },
}

Não codifique segredos do cliente diretamente em settings.py. Use variáveis de ambiente ou um gerenciador de segredos, como Azure Key Vault para fornecer credenciais em runtime.

Autenticação integrada (ActiveDirectoryIntegrated)

Use a autenticação integrada quando o processo do Django for executado em um contexto de usuário associado a um domínio e quando você quiser que o driver ODBC use essa identidade do Windows ou do Kerberos para autenticação no Microsoft Entra.

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "HOST": "<your-server>.database.windows.net",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
            "extra_params": "Authentication=ActiveDirectoryIntegrated",
        },
    },
}

A referência de autenticação ODBC documenta esse modo no Windows e no Linux ou macOS com o ODBC Driver 17.6 e versões posteriores para ambientes federados.

Autenticação interativa (ActiveDirectoryInteractive)

Use a autenticação interativa para entrada do usuário local quando quiser que o driver solicite credenciais e manipule a autenticação multifator.

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "USER": "<user@email.com>",
        "HOST": "<your-server>.database.windows.net",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
            "extra_params": "Authentication=ActiveDirectoryInteractive",
        },
    },
}

Os principais documentos ActiveDirectoryInteractive de referência se referem à autenticação ODBC como exclusiva do Windows. Se você planeja usá-lo em outra plataforma, valide o comportamento com a versão exata do driver primeiro.

Autenticação de cadeia de credenciais padrão (ActiveDirectoryDefault)

Use esse modo quando quiser que o driver ODBC aplique sua cadeia de credenciais de Microsoft Entra padrão.

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "HOST": "<your-server>.database.windows.net",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
            "extra_params": "Authentication=ActiveDirectoryDefault",
        },
    },
}

mssql-django 1.7.3 e versões posteriores passam esse modo para o driver ODBC. Se você precisar de controle explícito sobre a origem da credencial ou o comportamento de renovação do token, use a autenticação por token de acesso.

Autenticação de token de acesso (TOKEN)

Use TOKEN quando quiser que seu código Python adquira o token Microsoft Entra em si.

from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()
token = credential.get_token("https://database.windows.net/.default").token

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "HOST": "<your-server>.database.windows.net",
        "PORT": "1433",
        "TOKEN": token,
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
        },
    },
}

Esse caminho funciona com qualquer classe de credencial Python, incluindo DefaultAzureCredential, ManagedIdentityCredentiale ClientSecretCredential.

Os tokens de acesso obtidos em settings.py são avaliados uma vez quando o processo é iniciado e geralmente expiram após 60 a 90 minutos. Se o processo do Django permanecer vivo por mais tempo do que o tempo de vida do token, você deverá atualizar o token no código do aplicativo. Para a maioria dos aplicativos de produção de execução longa, use um modo de driver ODBC que atualize tokens automaticamente, como ActiveDirectoryMsi ou ActiveDirectoryServicePrincipal.

Autenticação por senha (ActiveDirectoryPassword, 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.

Se você precisar usá-lo para um cenário herdado, configure-o explicitamente:

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "USER": "<user@email.com>",
        "PASSWORD": "<your-password>",
        "HOST": "<your-server>.database.windows.net",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
            "extra_params": "Authentication=ActiveDirectoryPassword",
        },
    },
}

Conteúdo relacionado

• Práticas recomendadas de segurança para mssql-django
• Referência de configuração mssql-django
• Opções de conexão para mssql-django
• Implantar um aplicativo Django com SQL Server para Serviço de Aplicativo do Azure
• Usar Microsoft Entra ID com o driver ODBC
• Configurar e gerenciar a autenticação do Microsoft Entra com o SQL do Azure
• wiki de autenticação do Microsoft Entra
• Always Encrypted com mssql-django