Аутентификация Microsoft Entra ID с помощью go-mssqldb

Драйвер go-mssqldb поддерживает аутентификацию Microsoft Entra ID через azuread пакет. Этот пакет регистрирует отдельный драйвер с именемazuresql, который обёртывает стандартный sqlserver драйвер с поддержкой учетных данных Microsoft Entra ID.

Предостережение

Все встроенные fedauth методы аутентификации требуют имя azuresql драйвера (не sqlserver). Если использовать sql.Open("sqlserver", ...) с параметром fedauth , аутентификация тихо проваливается с Login failed for user ''. Импортируйте пакет azuread и используйте azuresql, как показано в следующем примере.

Выберите поток Fedauth

Используйте следующую таблицу, чтобы выбрать подходящий поток для вашей хостинговой среды и источника учетных данных:

Если нужно подключиться из...	Начни с...	Следует использовать в следующих случаях...
Местное развитие	`ActiveDirectoryDefault`	Вы хотите повторно использовать учетные данные Azure CLI или Azure Developer CLI без локальной настройки принципала сервиса или управляемой идентичности.
Приложение на Azure с управляемой идентичностью	`ActiveDirectoryManagedIdentity`	Вам нужна предсказуемая производственная конфигурация и не нужны другие локальные источники учетных данных в цепочке.
Конвейер CI/CD в Azure DevOps	`ActiveDirectoryAzurePipelines`	Ваш конвейер уже использует сервисное соединение Azure и открывает `SYSTEM_ACCESSTOKEN`.
Kubernetes с Azure Workload Identity	`ActiveDirectoryWorkloadIdentity`	Ваш pod получает файл токена OIDC, и вам нужна идентификация рабочей нагрузки вместо секрета клиента.
Руководитель службы с секретом или сертификатом	`ActiveDirectoryServicePrincipal`	Ваше приложение проходит аутентификацию с использованием регистрации приложения, а вы управляете секретом клиента или сертификатом.
Инструмент, у которого уже есть токен доступа	`ActiveDirectoryServicePrincipalAccessToken` или пользовательский поставщик токенов	Ваше приложение получает и обновляет токены вне водителя.
Делегированный пользовательский токен из верхнего веб-API	`ActiveDirectoryOnBehalfOf`	Вам нужно обменять пользовательский токен на токен с областью действия SQL в промежуточном сервисе.
Инструмент для разработчиков или интерактивная утилита	`ActiveDirectoryInteractive`, `ActiveDirectoryDeviceCode`, `ActiveDirectoryAzCli`или `ActiveDirectoryAzureDeveloperCli`	Человек присутствует для входа, или вы хотите повторно использовать существующую локальную сессию CLI.
Приложение только для Windows, которое обрабатывает интегрированные требования к аутентификации	`ActiveDirectoryIntegrated` (продвинутый)	Вы предоставляете пользовательскую логику получения токенов для интегрированных сценариев.

Если вы делите одну строка подключения между локальной разработкой и хостингом Azure, ActiveDirectoryDefault это хорошая отправная точка. В рабочей среде используйте ActiveDirectoryManagedIdentity или ActiveDirectoryServicePrincipal, чтобы избежать задержек при проверке цепочки учетных данных.

Установите пакет azuread

Скачайте azuread подпакет, который регистрирует azuresql драйвер:

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

Используйте драйвер azuresql

Импортируйте azuread пакет (вместо или в дополнение к базовому go-mssqldb ) и открывайте соединения, используя имя 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")
    // ...
}

Все следующие примеры нацелены на Azure SQL. Держите encrypt=true&TrustServerCertificate=false в строка подключения, чтобы драйвер проверял сертификат сервера.

Типы удостоверений Fedauth

Установить fedauth параметр соединения на одно из следующих значений. Большинство типов соответствуют учетным данным Azure Identity из пакета azidentity. ActiveDirectoryServicePrincipalAccessToken и API настраиваемых поставщиков токенов используют токены, предоставляемые вызывающей стороной.

ActiveDirectoryDefault

Использует azidentity.DefaultAzureCredential, который проверяет следующие источники учетных данных в порядке:

Переменные среды (AZURE_TENANT_ID, AZURE_CLIENT_ID, и так далее).
Идентификация рабочей нагрузки для Kubernetes.
Управляемая идентификация.
Учетные данные Azure CLI.
Учетные данные Azure Developer CLI.

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

Используйте этот тип для локальной разработки, так как он автоматически получает учетные данные Azure CLI. В рабочей среде используйте ActiveDirectoryManagedIdentity или ActiveDirectoryServicePrincipal напрямую. DefaultAzureCredential при первом подключении последовательно проверяет все источники учетных данных, что увеличивает задержку, не нужную для производственных нагрузок.

ActiveDirectoryManagedIdentity

Аутентифицируется с управляемой идентичностью, назначенной системой или пользователем. Для идентификатора, назначенного пользователем, укажите идентификатор клиента в параметре user id :

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

С идентификатором, назначенным пользователем:

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

Note

ActiveDirectoryMSI является псевдонимом для ActiveDirectoryManagedIdentity.

ActiveDirectoryServicePrincipal

Аутентифицируется как принципал сервиса (регистрация приложения) с идентификатором клиента и секретом клиента:

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

Для аутентификации принципа сервиса на основе сертификатов используйте clientcertpath=<path-to-certificate> вместе с password=<certificate-password>.

Note

ActiveDirectoryApplication является псевдонимом для ActiveDirectoryServicePrincipal.

ActiveDirectoryServicePrincipalAccessToken

Использует заранее полученный токен доступа субъекта-службы, который приложение передаёт непосредственно в строке подключения:

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

Используйте этот поток только тогда, когда ваше приложение уже получает и обновляет токен доступа вне драйвера. Для большинства сценариев взаимодействия между службами предпочтительны ActiveDirectoryServicePrincipal или пользовательский поставщик токенов.

ActiveDirectoryPassword

Important

Параметр аутентификации ActiveDirectoryPassword (аутентификация по паролю Microsoft Entra ID) устарел в драйверах Microsoft SQL. Этот высокорисковый сценарий аутентификации несовместим с обязательной многофакторной аутентификацией Microsoft Entra (MFA) и может не работать в арендаторах, где требуется MFA. Запланируйте переход на другой метод аутентификации Microsoft Entra.

Microsoft Entra ID проверка подлинности паролей основана на предоставлении учетных данных владельца ресурса OAuth 2.0 ( ROPC), что позволяет приложению войти в систему, напрямую обрабатывая пароль.

Microsoft рекомендует не использовать поток ROPC, так как он несовместим с MFA. В большинстве случаев доступны и рекомендуются более безопасные альтернативы. Этот поток требует высокой степени доверия к приложению и несет риски, которые не присутствуют в других потоках. Используйте этот поток только в том случае, если более безопасные потоки не являются жизнеспособными. Корпорация Майкрософт отойдет от этого потока проверки подлинности с высоким риском, чтобы защитить пользователей от вредоносных атак. Дополнительные сведения см. в разделе Планирование обязательной многофакторной аутентификации для Azure.

Когда пользователь присутствует при входе в систему, используйте аутентификацию ActiveDirectoryInteractive или ActiveDirectoryIntegrated, чтобы записи в журнале аудита относились к вошедшему пользователю и применялись политики условного доступа.

Для сценариев взаимодействия между службами без участия пользователя следуйте рекомендациям по использованию служебной учетной записи Microsoft Entra:

Если приложение работает в инфраструктуре Azure, используйте ActiveDirectoryMSI (или ActiveDirectoryManagedIdentity в некоторых драйверах). Управляемые удостоверения устраняют затраты на обслуживание и смену секретов и сертификатов.
Если управляемое удостоверение недоступно (например, приложение работает вне Azure), используйте ActiveDirectoryServicePrincipal. Если драйвер это поддерживает, предпочтительнее использовать клиентский сертификат вместо секрета клиента. При использовании сертификата закрытый ключ остается на клиенте, и только подписанное утверждение отправляется в Microsoft Entra для проверки подлинности клиента. Если ключ хранится в аппаратном модуле (например, TPM или HSM) или помечен как неэкспортируемый, его нельзя экспортировать в виде строки, как это можно сделать с секретом клиента.
Не используйте Microsoft Entra учетную запись пользователя в качестве учетной записи службы.

Аутентификация с помощью имени пользователя и пароля 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

applicationclientid Параметр необходим для этого потока.

ActiveDirectoryInteractive

Открывается интерактивный запрос входа в браузере для пользователя. Подходящие для местных инструментов развития:

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

applicationclientid Параметр необходим для этого потока.

ActiveDirectoryDeviceCode

Отображает код устройства для ввода пользователем на https://microsoft.com/devicelogin. Полезно для сред без браузера:

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

ActiveDirectoryAzCli

Использует токен из входной сессии Azure CLI:

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

ActiveDirectoryAzureDeveloperCli

Использует токен из входной сессии Azure Developer CLI (azd):

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

ActiveDirectoryEnvironment

Считывает учетные данные из переменных среды. Библиотека Azure Identity проверяет переменные, такие как AZURE_TENANT_ID, AZURE_CLIENT_ID, и AZURE_CLIENT_SECRET:

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

ActiveDirectoryWorkloadIdentity

Аутентифицируется с помощью федерации идентификации рабочей нагрузки. Используйте этот метод в подах Kubernetes с настроенным Azure Workload Identity.

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

ActiveDirectoryAzurePipelines

Аутентифицируется с помощью сервисного соединения Azure Pipelines. Введите параметры конвейера в строка подключения или позвольте драйверу читать недостающие значения из переменных среды 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

Задайте параметры в соответствии с требованиями драйвера:

Parameter	Description
`user id`	Идентификатор основного клиента сервиса, опционально с `@tenant-id`.
`serviceconnectionid`	ID подключения к службе из Azure DevOps.
`systemtoken`	Токен доступа к системе конвейера (`$(System.AccessToken)`).

ActiveDirectoryClientAssertion

Аутентифицируется с помощью клиентского утверждения (подписанного токена JWT) вместо клиентского секрета. Введите подписанный JWT в clientassertion параметре:

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

ActiveDirectoryOnBehalfOf

Аутентифицируется с помощью потока On-Behalf-Of (OBO). Драйвер обменивает исходный пользовательский токен на новый токен для 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

Этап аутентификации клиента может использовать password, clientcertpath, или clientassertion, но userassertion всегда необходим.

Интегрировано с Active Directory

Поддерживает продвинутый рабочий процесс интегрированной аутентификации. Для этого режима требуется пользовательская логика получения токенов через провайдера токенов.

Используйте этот режим только на Windows. На Linux и macOS используйте пользовательский провайдер токенов для вашего процесса аутентификации.

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

Поставщик пользовательских токенов

Если ни один из встроенных fedauth типов не подходит вашему сценарию, используйте один из этих API поставщика токенов, чтобы создать собственную логику приобретения токенов:

NewSecurityTokenConnector (рекомендуют)

Используйте этот API, если у вас есть заранее приобретённый токен доступа OAuth2:

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)

Используйте этот API для более простого сбора токенов без обработки контекста.

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 (Настраиваемые рабочие процессы ADAL)

Используйте этот API для пользовательских рабочих процессов получения токенов Azure AD, если ни встроенные fedauth режимы, ни API SecurityToken не подходят для вашего сценария:

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)

Этот подход полезен, когда необходимо интегрироваться с пользовательским идентификатором, реализовать кэширование токенов или обрабатывать тип учетных данных, не покрываемый azuread пакетом. Большинству приложений следует использовать NewSecurityTokenConnector с предварительно полученным токеном.

Распространённые варианты квалификации

Эти параметры применимы к нескольким типам федаутов:

Parameter	Description
`applicationclientid`	Идентификатор клиентского приложения. Требуется для `ActiveDirectoryPassword` и `ActiveDirectoryInteractive`.
`clientcertpath`	Путь к файлу клиентского сертификата в формате PEM или PFX для аутентификации субъекта-службы на основе сертификата или аутентификации On-Behalf-Of.
`clientassertion`	Подписанное утверждение JWT для `ActiveDirectoryClientAssertion` или аутентификации от имени.
`serviceconnectionid`	Идентификатор подключения к службе Azure Pipelines.
`systemtoken`	токен системного доступа Azure Pipelines
`userassertion`	Входящий пользовательский токен для `ActiveDirectoryOnBehalfOf`.
`tokenfilepath`	Путь к файлу токена OIDC для `ActiveDirectoryWorkloadIdentity` в Kubernetes.
`additionallyallowedtenants`	Список дополнительных идентификаторов арендаторов, разделённых запятыми, которые следует разрешить, если требуется многоарендная аутентификация.
`disableinstancediscovery`	Установите значение `true`, чтобы отключить обнаружение экземпляров; используйте только, если вы контролируете URL-адрес центра авторизации.
`sendcertificatechain`	Настройте на `true` отправку цепочки сертификатов для аутентификации на основе сертификатов.

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2026-07-21