Autenticação do Microsoft Entra ID com go-mssqldb

O controlador go-mssqldb suporta a autenticação do Microsoft Entra ID através do pacote azuread. Este pacote regista um driver separado chamado azuresql que envolve o driver padrão sqlserver com suporte a credenciais do Microsoft Entra ID.

Caution

Todos os métodos de autenticação integrados fedauth requerem o nome do controlador azuresql (não sqlserver). Se usar sql.Open("sqlserver", ...) com um fedauth parâmetro, a autenticação falha silenciosamente com Login failed for user ''. Importe o azuread pacote e use azuresql conforme mostrado no exemplo seguinte.

Escolha um fluxo de fedauth

Use a tabela seguinte para escolher o fluxo adequado para o seu ambiente de alojamento e fonte de credenciais:

Se precisares de estabelecer ligação a partir de...	Começa com...	Utilize quando...
Desenvolvimento local	`ActiveDirectoryDefault`	Quer reutilizar as credenciais do CLI do Azure ou do Azure Developer CLI sem configurar localmente uma entidade de serviço ou uma identidade gerida.
Uma aplicação alojada no Azure com identidade gerida	`ActiveDirectoryManagedIdentity`	Queres uma configuração de produção previsível e não queres outras fontes locais de credenciais na cadeia.
Um pipeline de CI/CD no Azure DevOps	`ActiveDirectoryAzurePipelines`	O seu pipeline já utiliza uma ligação de serviço do Azure e expõe `SYSTEM_ACCESSTOKEN`.
Kubernetes com Azure Workload Identity	`ActiveDirectoryWorkloadIdentity`	O teu pod recebe um ficheiro de token OIDC e queres a identidade da carga de trabalho em vez de um segredo cliente.
Um principal de serviço com um segredo ou certificado	`ActiveDirectoryServicePrincipal`	A sua aplicação autentica-se como um registo da aplicação e o utilizador gere o segredo do cliente ou o certificado.
Uma ferramenta que já tem um token de acesso	`ActiveDirectoryServicePrincipalAccessToken` ou um fornecedor de tokens personalizados	A sua aplicação adquire e atualiza tokens fora do driver.
Um token de utilizador delegado de uma API da Web ascendente	`ActiveDirectoryOnBehalfOf`	É necessário trocar um token de utilizador por um token com escopo SQL num serviço de nível intermédio.
Uma ferramenta para programadores ou utilidade interativa	`ActiveDirectoryInteractive`, `ActiveDirectoryDeviceCode`, `ActiveDirectoryAzCli`ou `ActiveDirectoryAzureDeveloperCli`	Está presente um utilizador para iniciar sessão, ou pretende reutilizar uma sessão local existente da CLI.
Uma aplicação exclusiva para Windows que gere requisitos de autenticação integrada	`ActiveDirectoryIntegrated` (avançado)	Forneces uma lógica personalizada de aquisição de tokens para cenários integrados.

Se partilhares uma cadeia de ligação entre desenvolvimento local e alojamento Azure, ActiveDirectoryDefault é um bom ponto de partida. Para produção, use ActiveDirectoryManagedIdentity ou ActiveDirectoryServicePrincipal para evitar a latência da cadeia de credenciais.

Instala o pacote azuread

Descarregue o subpacote azuread, que regista o controlador azuresql:

go get github.com/microsoft/go-mssqldb/azuread

Usa o driver AzureSQL

Importar o pacote azuread (em vez do pacote base go-mssqldb ou adicionalmente a este) e abrir conexões utilizando o nome do controlador azuresql:

import (
    "database/sql"

    _ "github.com/microsoft/go-mssqldb/azuread"
)

func main() {
    db, err := sql.Open("azuresql",
        "sqlserver://<server>.database.windows.net?database=AdventureWorks2025&fedauth=ActiveDirectoryDefault&encrypt=true&TrustServerCertificate=false")
    // ...
}

Todos os exemplos seguintes têm como alvo o SQL do Azure. Mantenha encrypt=true&TrustServerCertificate=false na cadeia de ligação para que o controlador valide o certificado do servidor.

Tipos de credenciais Fedauth

Defina o fedauth parâmetro de ligação para um dos seguintes valores. A maioria dos tipos corresponde a uma credencial de identidade do Azure a partir do azidentity pacote. ActiveDirectoryServicePrincipalAccessToken e APIs personalizadas de fornecedores de tokens utilizam tokens fornecidos pelo chamador.

ActiveDirectoryDefault

Utiliza azidentity.DefaultAzureCredential, que tenta as seguintes origens de credenciais pela seguinte ordem:

Variáveis de ambiente (AZURE_TENANT_ID, AZURE_CLIENT_ID, e assim sucessivamente).
Identidade da carga de trabalho para Kubernetes.
Identidade gerenciada.
Credenciais da CLI do Azure.
Credenciais da CLI de Desenvolvimento do Azure.

sqlserver://<server>.database.windows.net?database=AdventureWorks2025&fedauth=ActiveDirectoryDefault&encrypt=true&TrustServerCertificate=false

Use este tipo para desenvolvimento local porque ele recolhe automaticamente as credenciais do CLI do Azure. Para produção, uso ActiveDirectoryManagedIdentity ou ActiveDirectoryServicePrincipal diretamente. DefaultAzureCredential percorre cada fonte de credencial na primeira ligação, o que adiciona uma latência que as cargas de trabalho de produção não precisam.

ActiveDirectoryManagedIdentity

Autentica-se com uma identidade gerida atribuída pelo sistema ou pelo utilizador. Para uma identidade atribuída pelo utilizador, forneça o ID do cliente no user id parâmetro:

sqlserver://<server>.database.windows.net?database=AdventureWorks2025&fedauth=ActiveDirectoryManagedIdentity&encrypt=true&TrustServerCertificate=false

Com uma identidade atribuída pelo utilizador:

sqlserver://<server>.database.windows.net?database=AdventureWorks2025&fedauth=ActiveDirectoryManagedIdentity&user id=<client-id>&encrypt=true&TrustServerCertificate=false

Observação

ActiveDirectoryMSI é um alias para ActiveDirectoryManagedIdentity.

ActiveDirectoryServicePrincipal

Autentica-se como principal de serviço (registo de app) com um ID de cliente e um segredo de cliente:

sqlserver://<server>.database.windows.net?database=AdventureWorks2025&fedauth=ActiveDirectoryServicePrincipal&user id=<client-id>&password=<client-secret>&encrypt=true&TrustServerCertificate=false

Para a autenticação do principal de serviço baseada em certificados, use clientcertpath=<path-to-certificate> em conjunto com password=<certificate-password>.

Observação

ActiveDirectoryApplication é um alias para ActiveDirectoryServicePrincipal.

ActiveDirectoryServicePrincipalAccessToken

Utiliza um token de acesso principal de serviço pré-adquirido que a sua aplicação passa diretamente na cadeia de ligação:

sqlserver://<server>.database.windows.net?database=AdventureWorks2025&fedauth=ActiveDirectoryServicePrincipalAccessToken&password=<access-token>&encrypt=true&TrustServerCertificate=false

Use este fluxo apenas quando a sua aplicação já adquire e renova o token de acesso fora do driver. Para a maioria dos cenários de serviço-a-serviço, prefira ActiveDirectoryServicePrincipal ou um fornecedor de tokens personalizado.

ActiveDirectoryPassword

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.

Autentica-se com um nome de utilizador e palavra-passe Microsoft Entra:

sqlserver://<server>.database.windows.net?database=AdventureWorks2025&fedauth=ActiveDirectoryPassword&user id=<user>@mydomain.com&password=<password>&applicationclientid=<app-id>&encrypt=true&TrustServerCertificate=false

O applicationclientid parâmetro é necessário para este fluxo.

ActiveDirectoryInteractive

Abre um prompt interativo de login baseado no navegador para o utilizador. Adequado para ferramentas de desenvolvimento local:

sqlserver://<server>.database.windows.net?database=AdventureWorks2025&fedauth=ActiveDirectoryInteractive&user id=<user>@mydomain.com&applicationclientid=<app-id>&encrypt=true&TrustServerCertificate=false

O applicationclientid parâmetro é necessário para este fluxo.

ActiveDirectoryDeviceCode

Apresenta um código de dispositivo para o utilizador introduzir em https://microsoft.com/devicelogin. Útil para ambientes sem navegador:

sqlserver://<server>.database.windows.net?database=AdventureWorks2025&fedauth=ActiveDirectoryDeviceCode&encrypt=true&TrustServerCertificate=false

ActiveDirectoryAzCli

Utiliza o token da sessão autenticada do CLI do Azure:

sqlserver://<server>.database.windows.net?database=AdventureWorks2025&fedauth=ActiveDirectoryAzCli&encrypt=true&TrustServerCertificate=false

ActiveDirectoryAzureDeveloperCli

Utiliza o token da sessão Azure Developer CLI (azd) iniciada:

sqlserver://<server>.database.windows.net?database=AdventureWorks2025&fedauth=ActiveDirectoryAzureDeveloperCli&encrypt=true&TrustServerCertificate=false

ActiveDirectoryEnvironment

Lê credenciais a partir de variáveis de ambiente. A biblioteca Azure Identity inspeciona variáveis como AZURE_TENANT_ID, AZURE_CLIENT_ID, e AZURE_CLIENT_SECRET:

sqlserver://<server>.database.windows.net?database=AdventureWorks2025&fedauth=ActiveDirectoryEnvironment&encrypt=true&TrustServerCertificate=false

ActiveDirectoryWorkloadIdentity

Autentica-se usando a federação de identidade da carga de trabalho. Utilize este método nos pods do Kubernetes que tenham o Azure Workload Identity configurado.

sqlserver://<server>.database.windows.net?database=AdventureWorks2025&fedauth=ActiveDirectoryWorkloadIdentity&encrypt=true&TrustServerCertificate=false

ActiveDirectoryAzurePipelines

Autentica usando uma ligação de serviço Azure Pipelines. Forneça os parâmetros do pipeline na cadeia de ligação, ou deixe o driver ler os valores em falta das variáveis de ambiente do Azure Pipelines.

sqlserver://<server>.database.windows.net?database=AdventureWorks2025&fedauth=ActiveDirectoryAzurePipelines&user id=<client-id>@<tenant-id>&serviceconnectionid=<service-connection-id>&systemtoken=<system-access-token>&encrypt=true&TrustServerCertificate=false

Defina parâmetros conforme exigido pelo condutor:

Parâmetro	Description
`user id`	ID do cliente principal de serviço, opcionalmente seguido por `@tenant-id`.
`serviceconnectionid`	ID da ligação de serviço do Azure DevOps.
`systemtoken`	O token de acesso ao sistema de pipeline (`$(System.AccessToken)`).

ActiveDirectoryClientAssertion

Autentica usando uma asserção cliente (um token JWT assinado) em vez de um segredo cliente. Forneça o JWT assinado no clientassertion parâmetro:

sqlserver://<server>.database.windows.net?database=AdventureWorks2025&fedauth=ActiveDirectoryClientAssertion&user id=<client-id>@<tenant-id>&clientassertion=<jwt-token>&encrypt=true&TrustServerCertificate=false

ActiveDirectoryOnBehalfOf

Autentica usando o fluxo On-Behalf-Of (OBO). O controlador troca um token de utilizador a montante por um novo token limitado ao SQL Server.

sqlserver://<server>.database.windows.net?database=AdventureWorks2025&fedauth=ActiveDirectoryOnBehalfOf&user id=<client-id>@<tenant-id>&password=<client-secret>&userassertion=<user-token>&encrypt=true&TrustServerCertificate=false

A perna de autenticação do cliente pode usar password, clientcertpath, ou clientassertion, mas userassertion é sempre obrigatória.

Integrado no Active Directory

Suporta um fluxo de trabalho avançado de autenticação integrada. Este modo requer lógica personalizada de aquisição de tokens através de um fornecedor de tokens.

Use este modo apenas no Windows. No Linux e macOS, usa um fornecedor de tokens personalizado para o teu fluxo de autenticação.

sqlserver://<server>.database.windows.net?database=AdventureWorks2025&fedauth=ActiveDirectoryIntegrated&encrypt=true&TrustServerCertificate=false

Fornecedor de tokens personalizados

Se nenhum dos tipos incorporados fedauth se adequar ao seu cenário, utilize uma destas APIs de fornecedor de tokens para disponibilizar a sua própria lógica de aquisição de tokens:

NewSecurityTokenConnector (Recomendado)

Use esta API quando tiver um token de acesso OAuth2 pré-adquirido:

import (
    "context"
    "database/sql"
    "log"

    "github.com/microsoft/go-mssqldb"
)

connector, err := mssql.NewSecurityTokenConnector(
    "sqlserver://<server>.database.windows.net?database=AdventureWorks2025&encrypt=true&TrustServerCertificate=false",
    func(ctx context.Context) (string, error) {
        // Return a pre-acquired OAuth2 access token.
        return myTokenProvider(ctx)
    },
)
if err != nil {
    log.Fatal(err)
}
db := sql.OpenDB(connector)

NewAccessTokenConnector (API simplificada)

Use esta API para aquisição de tokens mais simples sem lidar com o contexto.

import (
    "database/sql"
    "log"

    "github.com/microsoft/go-mssqldb"
)

connector, err := mssql.NewAccessTokenConnector(
    "sqlserver://<server>.database.windows.net?database=AdventureWorks2025&encrypt=true&TrustServerCertificate=false",
    func() (string, error) {
        // Return a pre-acquired OAuth2 access token.
        return mySimpleTokenProvider()
    },
)
if err != nil {
    log.Fatal(err)
}
db := sql.OpenDB(connector)

NewActiveDirectoryTokenConnector (Fluxos de Trabalho ADAL Personalizados)

Use esta API para fluxos de trabalho personalizados de aquisição de tokens Azure AD quando nem os modos incorporados fedauth nem as APIs SecurityToken se encaixam no seu cenário:

import (
    "context"
    "database/sql"
    "log"

    "github.com/microsoft/go-mssqldb"
)

connector, err := mssql.NewActiveDirectoryTokenConnector(
    "sqlserver://<server>.database.windows.net?database=AdventureWorks2025&encrypt=true&TrustServerCertificate=false",
    mssql.FedAuthADALWorkflowPassword,
    func(ctx context.Context, serverSPN, stsURL string) (string, error) {
        // Custom ADAL workflow using server-provided SPN and STS URL.
        return myCustomADALFlow(ctx, serverSPN, stsURL)
    },
)
if err != nil {
    log.Fatal(err)
}
db := sql.OpenDB(connector)

Esta abordagem é útil quando precisa de integrar com um fornecedor de identidade personalizada, implementar cache de tokens ou lidar com um tipo de credencial não coberto pelo azuread pacote. A maioria das aplicações deve usar NewSecurityTokenConnector com um token previamente adquirido.

Opções de credenciais comuns

Estes parâmetros aplicam-se a vários tipos de fedauth:

Parâmetro	Description
`applicationclientid`	ID da aplicação do cliente. Necessária para `ActiveDirectoryPassword` e `ActiveDirectoryInteractive`.
`clientcertpath`	Caminho para um ficheiro de certificado de cliente PEM ou PFX para autenticação de entidade de serviço baseada em certificado ou autenticação On-Behalf-Of.
`clientassertion`	Asserção JWT assinada para `ActiveDirectoryClientAssertion` ou autenticação On-Behalf-Of.
`serviceconnectionid`	ID da ligação de serviço do Azure Pipelines.
`systemtoken`	token de acesso do sistema do Azure Pipelines
`userassertion`	Token de utilizador ascendente para `ActiveDirectoryOnBehalfOf`.
`tokenfilepath`	Caminho para o ficheiro de token OIDC para `ActiveDirectoryWorkloadIdentity` no Kubernetes.
`additionallyallowedtenants`	Lista separada por vírgulas de IDs de inquilino adicionais a permitir quando for necessária autenticação multitenant.
`disableinstancediscovery`	Defina como `true` para desativar a descoberta de instâncias; use apenas se controlar a URL da autoridade.
`sendcertificatechain`	Defina para `true` enviar a cadeia de certificados para autenticação baseada em certificados.

Comentários

Esta página foi útil?

Last updated on 2026-07-21