Autenticación de Microsoft Entra ID con go-mssqldb

El controlador go-mssqldb admite la autenticación de Microsoft Entra ID a través del paquete azuread. Este paquete registra un controlador separado llamado azuresql que envuelve el controlador estándar sqlserver con soporte para credenciales de Microsoft Entra ID.

Precaución

Todos los métodos de autenticación integrados fedauth requieren el nombre del azuresql controlador (no sqlserver). Si usas sql.Open("sqlserver", ...) con un fedauth parámetro, la autenticación falla silenciosamente con Login failed for user ''. Importa el azuread paquete y úsalo azuresql como se muestra en el siguiente ejemplo.

Elige un flujo de fedauth

Utiliza la siguiente tabla para elegir el flujo adecuado para tu entorno de alojamiento y la fuente de credenciales:

Si necesitas conectar desde...	Empieza con...	Use cuando...
Desarrollo local	`ActiveDirectoryDefault`	Quieres reutilizar las credenciales de CLI de Azure o Azure Developer sin configurar localmente un principal de servicio o una identidad gestionada.
Una aplicación alojada en Azure con una identidad gestionada	`ActiveDirectoryManagedIdentity`	Quieres una configuración de producción predecible y no quieres otras fuentes locales de credenciales en la cadena.
Un pipeline de CI/CD en Azure DevOps	`ActiveDirectoryAzurePipelines`	Tu pipeline ya utiliza una conexión de servicio de Azure y expone `SYSTEM_ACCESSTOKEN`.
Kubernetes con Azure Workload Identity	`ActiveDirectoryWorkloadIdentity`	Tu pod recibe un archivo de token de OIDC y quieres usar identidad de carga de trabajo en lugar de un secreto de cliente.
Un principal de servicio con un secreto o certificado	`ActiveDirectoryServicePrincipal`	Tu app se autentica como un registro de app y tú gestionas el secreto o certificado del cliente.
Una herramienta que ya tiene un token de acceso	`ActiveDirectoryServicePrincipalAccessToken` o un proveedor de tokens personalizados	Tu aplicación adquiere y renueva tokens fuera del controlador.
Un token de usuario delegado desde una API web ascendente	`ActiveDirectoryOnBehalfOf`	Necesitas intercambiar un token de usuario por uno con alcance SQL en un servicio de nivel intermedio.
Una herramienta para desarrolladores o utilidad interactiva	`ActiveDirectoryInteractive`, `ActiveDirectoryDeviceCode`, `ActiveDirectoryAzCli` o `ActiveDirectoryAzureDeveloperCli`	Hay una persona presente para iniciar sesión, o quieres reutilizar una sesión local de CLI existente.
Una aplicación solo para Windows que gestiona los requisitos de autenticación integrada	`ActiveDirectoryIntegrated` (avanzado)	Proporcionáis una lógica personalizada de adquisición de tokens para escenarios integrados.

Si compartes una cadena de conexión entre desarrollo local y hosting en Azure, ActiveDirectoryDefault es un buen punto de partida. En producción, utiliza ActiveDirectoryManagedIdentity o ActiveDirectoryServicePrincipal para evitar la latencia de la cadena de credenciales.

Instala el paquete azuread

Descarga el azuread subpaquete, que registra el azuresql controlador:

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

Usa el controlador azuresql

Importa el paquete azuread (en lugar del paquete base go-mssqldb o además de este) y abre conexiones utilizando el nombre del 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 los siguientes ejemplos están dirigidos a Azure SQL. Mantenlo encrypt=true&TrustServerCertificate=false en la cadena de conexión para que el controlador valide el certificado del servidor.

Tipos de credenciales Fedauth

Establece el fedauth parámetro de conexión en uno de los siguientes valores. La mayoría de los tipos se asignan a una credencial de Azure Identity del paquete azidentity. ActiveDirectoryServicePrincipalAccessToken y las APIs personalizadas de los proveedores de tokens utilizan tokens suministrados por el llamante.

ActiveDirectoryDefault

Utiliza azidentity.DefaultAzureCredential, que prueba las siguientes fuentes de credenciales en orden:

Variables de entorno (AZURE_TENANT_ID, AZURE_CLIENT_ID, y así sucesivamente).
Identidad de carga de trabajo para Kubernetes.
Identidad administrada.
Credenciales de CLI de Azure
Credenciales CLI de Azure Developer.

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

Utiliza este tipo para desarrollo local porque recoge automáticamente las credenciales de CLI de Azure. Para producción, usa ActiveDirectoryManagedIdentity o ActiveDirectoryServicePrincipal directamente. DefaultAzureCredential recorre cada fuente de credenciales en la primera conexión, lo que añade una latencia que las cargas de trabajo en producción no necesitan.

ActiveDirectoryManagedIdentity

Se autentica con una identidad gestionada asignada por el sistema o el usuario. Para una identidad asignada por el usuario, proporciona el ID del cliente en el user id parámetro:

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

Con una identidad asignada por el usuario:

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

Note

ActiveDirectoryMSI es un alias de ActiveDirectoryManagedIdentity.

ActiveDirectoryServicePrincipal

Se autentica como principal de servicio (registro de la app) con un ID de cliente y un secreto de cliente:

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

Para la autenticación de entidad de servicio basada en certificados, use clientcertpath=<path-to-certificate> junto con password=<certificate-password>.

Note

ActiveDirectoryApplication es un alias de ActiveDirectoryServicePrincipal.

ActiveDirectoryServicePrincipalAccessToken

Utiliza un token de acceso principal de servicio preadquirido que tu aplicación pasa directamente en la cadena de conexión:

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

Usa este flujo solo cuando tu aplicación ya adquiera y actualice el token de acceso fuera del controlador. Para la mayoría de los escenarios de servicio-a-servicio, prefiero ActiveDirectoryServicePrincipal o un proveedor de tokens personalizado.

ActiveDirectoryPassword

Importante

La opción de autenticación ActiveDirectoryPassword (autenticación con contraseña Microsoft Entra ID) está en desuso en los controladores sql de Microsoft. Este flujo de autenticación de alto riesgo no es compatible con la autenticación multifactor (MFA) obligatoria Microsoft Entra y es posible que no funcione en inquilinos en los que se aplica MFA. Planee la migración a un método de autenticación de Microsoft Entra diferente.

La autenticación mediante contraseña de Microsoft Entra ID se basa en la concesión de credenciales de contraseña del propietario del recurso (ROPC) de OAuth 2.0, que permite a una aplicación iniciar la sesión del usuario mediante la administración directa de su contraseña.

Microsoft recomienda no usar el flujo ROPC porque no es compatible con MFA. En la mayoría de los escenarios, hay alternativas más seguras disponibles y recomendadas. Este flujo requiere un alto grado de confianza en la aplicación y conlleva riesgos que no están presentes en otros flujos. Use este flujo solo cuando los flujos más seguros no sean viables. Microsoft se aleja de este flujo de autenticación de alto riesgo para proteger a los usuarios frente a ataques malintencionados. Para obtener más información, consulte Planificación para la autenticación multifactor obligatoria en Azure.

Cuando un usuario está presente al iniciar sesión, use la autenticación ActiveDirectoryInteractive o ActiveDirectoryIntegrated para que el registro de auditoría se atribuya al usuario que ha iniciado sesión y se apliquen las directivas de Acceso condicional.

Para escenarios de servicio a servicio sin supervisión, siga las directrices sobre cuentas de servicio de Microsoft Entra:

Si la aplicación se ejecuta en la infraestructura de Azure, use ActiveDirectoryMSI (o ActiveDirectoryManagedIdentity en algunos controladores). Las identidades administradas eliminan la sobrecarga de mantener y rotar secretos y certificados.
Si la identidad administrada no está disponible (por ejemplo, la aplicación se ejecuta fuera de Azure), use ActiveDirectoryServicePrincipal. Cuando el controlador lo admita, prefiera un certificado de cliente sobre un secreto de cliente. Con un certificado, la clave privada permanece en el cliente y solo se envía una aserción firmada a Microsoft Entra para autenticar al cliente. Si la clave se almacena en hardware (como un TPM o un HSM) o está marcada como no exportable, no puede extraerse como una cadena, como sí puede hacerse con un secreto de cliente.
No use una cuenta de usuario de Microsoft Entra como cuenta de servicio.

Autentica con un nombre de usuario y contraseña de 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

El applicationclientid parámetro es necesario para este flujo.

ActiveDirectoryInteractive

Abre una solicitud interactiva de inicio de sesión en el navegador para que el usuario inicie sesión. Adecuado para herramientas de desarrollo local:

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

El applicationclientid parámetro es necesario para este flujo.

ActiveDirectoryDeviceCode

Muestra un código de dispositivo para que el usuario lo introduzca en https://microsoft.com/devicelogin. Útil para entornos sin navegador:

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

ActiveDirectoryAzCli

Usa el token de la sesión iniciada en CLI de Azure:

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

ActiveDirectoryAzureDeveloperCli

Utiliza el token de la sesión de CLI de Desarrollo de Azure (azd) iniciada sesión:

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

Entorno de Active Directory

Lee las credenciales de las variables de entorno. La biblioteca de identidad de Azure inspecciona variables como AZURE_TENANT_ID, AZURE_CLIENT_ID, y AZURE_CLIENT_SECRET:

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

ActiveDirectoryWorkloadIdentity

Se autentica mediante la federación de identidad de carga de trabajo. Utiliza este método en pods de Kubernetes configurados con Azure Workload Identity.

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

ActiveDirectoryAzurePipelines

Se autentica usando una conexión de servicio de Azure Pipelines. Proporciona los parámetros del pipeline en la cadena de conexión, o deja que el controlador lea los valores que faltan de las variables de entorno de 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

Establece los parámetros según lo requiera el conductor:

Parámetro	Description
`user id`	ID de cliente principal de servicio, opcionalmente seguido de `@tenant-id`.
`serviceconnectionid`	ID de conexión de servicio de Azure DevOps.
`systemtoken`	El token de acceso al sistema de tuberías (`$(System.AccessToken)`).

ActiveDirectoryClientAssertion

Se autentica utilizando una aserción cliente (un token JWT firmado) en lugar de un secreto cliente. Proporciona el JWT firmado en el parámetro clientassertion:

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 el flujo On-Behalf-Of (OBO). El controlador intercambia un token de usuario ascendente por un nuevo token destinado a 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

La etapa de autenticación del cliente puede usar password, clientcertpath, o clientassertion, pero userassertion siempre es obligatoria.

ActiveDirectoryIntegrated

Soporta un flujo de trabajo avanzado de autenticación integrada. Este modo requiere una lógica personalizada de adquisición de tokens a través de un proveedor de tokens.

Usa este modo solo en Windows. En Linux y macOS, utiliza un proveedor de tokens personalizado para tu flujo de autenticación.

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

Proveedor de tokens personalizados

Si ninguno de los tipos integrados fedauth encaja en tu situación, utiliza una de estas APIs de proveedores de tokens para proporcionar tu propia lógica de adquisición de tokens:

NewSecurityTokenConnector (Recomendado)

Usa esta API cuando tengas un token de acceso OAuth2 preadquirido:

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)

Utiliza esta API para una adquisición de tokens más sencilla sin necesidad de manipular el 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 (flujos de trabajo ADAL personalizados)

Utiliza esta API para flujos de trabajo personalizados de adquisición de tokens de Azure AD cuando ni los modos integrados fedauth ni las APIs de SecurityToken encajen en tu situación:

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)

Este enfoque es útil cuando necesitas integrarte con un proveedor de identidad personalizado, implementar caché de tokens o gestionar un tipo de credencial no cubierto por el azuread paquete. La mayoría de las aplicaciones deberían usar NewSecurityTokenConnector con un token adquirido previamente.

Opciones de credenciales comunes

Estos parámetros se aplican a múltiples tipos de fedauth:

Parámetro	Description
`applicationclientid`	ID de la aplicación del cliente. Requerida para `ActiveDirectoryPassword` y `ActiveDirectoryInteractive`.
`clientcertpath`	Ruta a un archivo de certificado de cliente PEM o PFX para la autenticación basada en certificados de un principal de servicio o en nombre de otro.
`clientassertion`	Aserción JWT firmada para `ActiveDirectoryClientAssertion` o autenticación en nombre de otro.
`serviceconnectionid`	Identificador de la conexión de servicio de Azure Pipelines.
`systemtoken`	Token de acceso del sistema de Azure Pipelines.
`userassertion`	Token de usuario ascendente para `ActiveDirectoryOnBehalfOf`.
`tokenfilepath`	Ruta hacia el archivo de tokens OIDC para `ActiveDirectoryWorkloadIdentity` en Kubernetes.
`additionallyallowedtenants`	Lista separada por comas de identificadores adicionales de inquilinos que se permiten cuando se necesita autenticación multiinquilino.
`disableinstancediscovery`	Establécelo en `true` para deshabilitar el descubrimiento de instancias; úsalo solo si controlas la URL de autoridad.
`sendcertificatechain`	Configura para `true` enviar la cadena de certificados para autenticación basada en certificados.

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2026-07-21