Autenticação Microsoft Entra com mssql-django

Este artigo explica como configurar a autenticação Microsoft Entra para aplicações Django usando o mssql-django backend. A autenticação Microsoft Entra elimina a necessidade de armazenar palavras-passe na configuração da sua aplicação.

Pré-requisitos

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

Métodos de autenticação

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

mssql-djangosuporta a autenticação Microsoft Entra de duas formas:

• Autenticação do controlador ODBC através de OPTIONS["extra_params"]. O backend acrescenta esta cadeia à cadeia de ligação ODBC sem alterações, pelo que os valores Authentication= disponíveis são fornecidos pelo Microsoft ODBC Driver for SQL Server instalado, e não pelo próprio mssql-django.
• Autenticação por token de acesso programático através da definição TOKEN. O backend transmite TOKEN ao controlador ODBC na forma de SQL_COPT_SS_ACCESS_TOKEN, o que ignora a palavra-chave Authentication= do ODBC.

Métodos de autenticação num relance

Conceder o acesso à identidade no SQL do Azure

Para autenticação de identidade gerida ou principal de serviço, crie um utilizador de base de dados e conceda apenas as funções de que a sua aplicação necessita:

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>];

O papel de base de dados fixo db_ddladmin é necessário apenas se a aplicação executar migrações. Para cargas de trabalho apenas 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 vir um erro VIEW ANY COLUMN MASTER KEY DEFINITION permission denied, conceda acesso adicional à identidade para cenários 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 gerida (ActiveDirectoryMsi)

Use identidade gerida quando a sua aplicação Django corre num serviço Azure, como Serviço de Aplicações do Azure, Azure Container Apps ou Máquinas Virtuais do Azure. Esta abordagem é recomendada para ambientes de produção porque o driver ODBC adquire e atualiza os tokens automaticamente.

Identidade gerenciada atribuída ao 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 tanto para a identidade gerida atribuída pelo sistema (SAMI) como para a identidade gerida atribuída pelo utilizador (UAMI). Para UAMI, o driver ODBC espera UID identificar a identidade gerida: usar o ID do cliente para Serviço de Aplicações do Azure ou Azure Container Instance, caso contrário usar o ID do objeto. Coloque isso UID dentro de extra_params, porque extra_params é passado diretamente para o controlador ODBC.

Se usar identidade gerida, crie manualmente a base de dados de testes e passe --keepdb quando executa testes unitários.

Autenticação do principal de serviço (ActiveDirectoryServicePrincipal)

Use um registo de aplicação Microsoft Entra (principal de serviço) quando a sua aplicação está a correr sem contexto de utilizador e a identidade gerida 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 os segredos do cliente em settings.py. Use variáveis de ambiente ou um gestor de segredos como o Azure Key Vault para fornecer credenciais em tempo de execução.

Autenticação integrada (ActiveDirectoryIntegrated)

Utilize a autenticação integrada quando o processo do Django for executado num contexto de utilizador associado a um domínio e pretender que o controlador ODBC utilize essa identidade do Windows ou 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 este modo no Windows e no Linux ou macOS com o Driver ODBC 17.6 e versões posteriores para ambientes federados.

Autenticação interativa (ActiveDirectoryInteractive)

Utilize a autenticação interativa para o início de sessão de utilizador local quando quiser que o controlador solicite credenciais e processe 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 de autenticação ODBC são apenas para Windows. Se planeias usá-lo noutra plataforma, valida o comportamento com a versão exata do teu driver primeiro.

Autenticação por cadeia de credenciais por defeito (ActiveDirectoryDefault)

Use este modo quando quiser que o driver ODBC aplique a sua cadeia de credenciais padrão 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=ActiveDirectoryDefault",
        },
    },
}

mssql-django As versões 1.7.3 e posteriores transmitem este modo ao driver ODBC. Se precisar de controlo explícito sobre a origem das credenciais ou o comportamento de atualização do token, use autenticação com token de acesso.

Autenticação por token de acesso (TOKEN)

Utilize TOKEN quando pretender que o seu código Python obtenha ele próprio o token do Microsoft Entra.

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",
        },
    },
}

Este caminho funciona com qualquer classe de credencial Python, incluindo DefaultAzureCredential, ManagedIdentityCredential, e ClientSecretCredential.

Os tokens de acesso obtidos em settings.py são avaliados apenas uma vez no arranque do processo e normalmente expiram ao fim de 60 a 90 minutos. Se o seu processo Django permanecer ativo por mais tempo do que a vida útil do token, deve atualizar o token no código da aplicação. Para a maioria das aplicações de produção de execução prolongada, utilize um modo do controlador ODBC que atualize automaticamente os tokens, como ActiveDirectoryMsi ou ActiveDirectoryServicePrincipal.

Autenticação por palavra-passe (ActiveDirectoryPassword, descontinuada)

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.

Se tiver de o usar para um cenário legado, 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

• Melhores práticas de segurança para mssql-django
• Referência de configuração MSSQL-Django
• Opções de ligação para mssql-django
• Implementar uma aplicação Django com o SQL Server no Serviço de Aplicações do Azure
• Utilizar o 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 Microsoft Entra
• Sempre encriptado com mssql-django