Autentikasi Microsoft Entra ID dengan go-mssqldb

Driver go-mssqldb mendukung autentikasi Microsoft Entra ID melalui azuread paket. Paket ini mendaftarkan driver terpisah bernama azuresql yang membungkus driver standar sqlserver dengan dukungan kredensial Microsoft Entra ID.

Caution

Semua metode autentikasi bawaan fedauth memerlukan nama driver azuresql (bukan sqlserver). Jika Anda menggunakan sql.Open("sqlserver", ...) dengan fedauth parameter, autentikasi gagal secara diam-diam dengan Login failed for user ''. Impor azuread paket dan gunakan azuresql seperti yang ditunjukkan pada contoh berikut.

Pilih alur fedauth

Gunakan tabel berikut untuk memilih alur yang sesuai untuk lingkungan hosting dan sumber kredensial Anda:

Jika Anda perlu terhubung dari...	Mulailah dengan...	Gunakan saat...
Pengembangan lokal	`ActiveDirectoryDefault`	Anda ingin menggunakan kembali kredensial Azure CLI atau Azure Developer CLI tanpa mengonfigurasi perwakilan layanan atau identitas terkelola secara lokal.
Aplikasi yang dihosting Azure dengan identitas terkelola	`ActiveDirectoryManagedIdentity`	Anda menginginkan konfigurasi produksi yang dapat diprediksi dan tidak menginginkan sumber kredensial lokal lainnya dalam rantai.
Alur CI/CD di Azure DevOps	`ActiveDirectoryAzurePipelines`	Alur Anda sudah menggunakan koneksi layanan Azure dan mengekspos `SYSTEM_ACCESSTOKEN`.
Kubernetes dengan Azure Workload Identity	`ActiveDirectoryWorkloadIdentity`	Pod Anda menerima file token OIDC dan Anda menginginkan identitas beban kerja, bukan rahasia klien.
Perwakilan layanan dengan rahasia atau sertifikat	`ActiveDirectoryServicePrincipal`	Aplikasi Anda diautentikasi sebagai pendaftaran aplikasi dan Anda mengelola rahasia atau sertifikat klien.
Alat yang sudah memiliki token akses	`ActiveDirectoryServicePrincipalAccessToken` atau penyedia token kustom	Aplikasi Anda memperoleh dan menyegarkan token di luar driver.
Token pengguna yang didelegasikan dari API web upstream	`ActiveDirectoryOnBehalfOf`	Anda perlu menukar token pengguna dengan token cakupan SQL di layanan tingkat menengah.
Alat pengembang atau utilitas interaktif	`ActiveDirectoryInteractive`, `ActiveDirectoryDeviceCode`, `ActiveDirectoryAzCli`, atau `ActiveDirectoryAzureDeveloperCli`	Manusia hadir untuk masuk, atau Anda ingin menggunakan kembali sesi CLI lokal yang ada.
Aplikasi khusus Windows yang menangani persyaratan autentikasi terintegrasi	`ActiveDirectoryIntegrated` (lanjutan)	Anda menyediakan logika akuisisi token kustom untuk skenario Terintegrasi.

Jika Anda membagikan satu string koneksi di seluruh pengembangan lokal dan hosting Azure, ActiveDirectoryDefault adalah titik awal yang baik. Untuk produksi, gunakan ActiveDirectoryManagedIdentity atau ActiveDirectoryServicePrincipal untuk menghindari latensi rantai kredensial.

Instal paket azuread

Unduh subpaket azuread, yang meregistrasikan driver azuresql:

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

Menggunakan driver azuresql

Impor paket azuread (alih-alih paket dasar go-mssqldb atau sebagai tambahannya) dan buka koneksi menggunakan nama driver 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")
    // ...
}

Semua contoh berikut menargetkan Azure SQL. Simpan encrypt=true&TrustServerCertificate=false string koneksi sehingga driver memvalidasi sertifikat server.

Jenis kredensial Fedauth

Atur fedauth parameter koneksi ke salah satu nilai berikut. Sebagian besar jenis dipetakan ke kredensial Azure Identity dari paket azidentity. ActiveDirectoryServicePrincipalAccessToken dan API penyedia token kustom menggunakan token yang disediakan oleh penelepon.

ActiveDirectoryDefault

Menggunakan azidentity.DefaultAzureCredential, yang mencoba sumber kredensial berikut secara berurutan:

Variabel lingkungan (AZURE_TENANT_ID, AZURE_CLIENT_ID, dan sebagainya).
Identitas beban kerja untuk Kubernetes.
Identitas yang dikelola
Kredensial Azure CLI.
Kredensial CLI Pengembang Azure.

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

Gunakan jenis ini untuk pengembangan lokal karena mengambil kredensial Azure CLI secara otomatis. Untuk produksi, gunakan ActiveDirectoryManagedIdentity atau ActiveDirectoryServicePrincipal secara langsung. DefaultAzureCredential menelusuri setiap sumber kredensial saat koneksi pertama, yang menyebabkan latensi tambahan yang tidak diperlukan oleh beban kerja produksi.

ActiveDirectoryManagedIdentity

Mengautentikasi dengan identitas terkelola yang ditetapkan sistem atau ditetapkan pengguna. Untuk identitas yang ditetapkan pengguna, berikan ID klien dalam user id parameter:

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

Dengan identitas yang ditetapkan oleh pengguna:

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

Note

ActiveDirectoryMSI adalah alias untuk ActiveDirectoryManagedIdentity.

ActiveDirectoryServicePrincipal

Mengautentikasi sebagai perwakilan layanan (pendaftaran aplikasi) dengan ID klien dan rahasia klien:

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

Untuk autentikasi perwakilan layanan berbasis sertifikat, gunakan clientcertpath=<path-to-certificate> bersama dengan password=<certificate-password>.

Note

ActiveDirectoryApplication adalah alias untuk ActiveDirectoryServicePrincipal.

ActiveDirectoryServicePrincipalAccessToken

Menggunakan token akses perwakilan layanan yang telah diperoleh sebelumnya yang diteruskan secara langsung oleh aplikasi Anda dalam string koneksi:

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

Gunakan alur ini hanya jika aplikasi Anda sudah memperoleh dan menyegarkan token akses di luar driver. Untuk sebagian besar skenario layanan-ke-layanan, pilih ActiveDirectoryServicePrincipal atau penyedia token kustom.

ActiveDirectoryPassword

Important

Opsi autentikasi ActiveDirectoryPassword (autentikasi kata sandi Microsoft Entra ID) tidak digunakan lagi di driver SQL Microsoft. Alur autentikasi berisiko tinggi ini tidak kompatibel dengan autentikasi multifaktor (MFA) Microsoft Entra wajib dan mungkin tidak berfungsi di penyewa tempat MFA diberlakukan. Rencanakan untuk bermigrasi ke metode autentikasi Microsoft Entra yang berbeda.

Autentikasi kata sandi Microsoft Entra ID didasarkan pada grant OAuth 2.0 Resource Owner Password Credentials (ROPC), yang memungkinkan aplikasi mengautentikasi pengguna dengan menangani kata sandi mereka secara langsung.

Microsoft menyarankan agar Anda tidak menggunakan alur ROPC karena tidak kompatibel dengan MFA. Dalam sebagian besar skenario, alternatif yang lebih aman tersedia dan direkomendasikan. Alur ini membutuhkan tingkat kepercayaan yang tinggi pada aplikasi, dan membawa risiko yang tidak ada dalam alur lain. Gunakan alur ini hanya jika opsi yang lebih aman tidak memungkinkan. Microsoft menjauh dari alur autentikasi berisiko tinggi ini untuk melindungi pengguna dari serangan berbahaya. Untuk informasi selengkapnya, lihat Merencanakan autentikasi multifaktor wajib untuk Azure.

Saat pengguna hadir saat proses masuk, gunakan autentikasi ActiveDirectoryInteractive atau ActiveDirectoryIntegrated sehingga jejak audit dikaitkan dengan pengguna yang masuk dan kebijakan Akses Bersyarat diterapkan.

Untuk skenario layanan ke layanan tanpa pengawas, ikuti panduan akun layanan Microsoft Entra:

Jika aplikasi Anda berjalan pada infrastruktur Azure, gunakan ActiveDirectoryMSI (atau ActiveDirectoryManagedIdentity di beberapa driver). Identitas terkelola menghilangkan overhead untuk memelihara dan memutar rahasia dan sertifikat.
Jika identitas terkelola tidak tersedia (misalnya, aplikasi berjalan di luar Azure), gunakan ActiveDirectoryServicePrincipal. Di mana driver mendukungnya, lebih memilih sertifikat klien daripada rahasia klien. Dengan sertifikat, kunci privat tetap berada di klien dan hanya pernyataan yang ditandatangani yang dikirim ke Microsoft Entra untuk mengautentikasi klien. Jika kunci disimpan di perangkat keras (seperti TPM atau HSM) atau ditandai sebagai tidak dapat diekspor, kunci tersebut tidak dapat disalin keluar sebagai string sebagaimana rahasia klien dapat disalin.
Jangan gunakan akun pengguna Microsoft Entra sebagai akun layanan.

Mengautentikasi dengan nama pengguna dan kata sandi 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

Parameter applicationclientid diperlukan untuk aliran ini.

ActiveDirectoryInteractive

Membuka prompt masuk interaktif berbasis browser untuk pengguna. Cocok untuk alat pengembangan lokal:

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

Parameter applicationclientid diperlukan untuk aliran ini.

Kode Perangkat Active Directory

Menampilkan kode perangkat agar pengguna memasukkannya di https://microsoft.com/devicelogin. Berguna untuk lingkungan tanpa browser:

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

ActiveDirectoryAzCli

Menggunakan token dari sesi Azure CLI yang telah masuk:

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

ActiveDirectoryAzureDeveloperCli

Menggunakan token dari sesi Azure Developer CLI (azd) yang masuk:

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

Lingkungan Active Directory

Membaca kredensial dari variabel lingkungan. Pustaka Azure Identity memeriksa variabel seperti AZURE_TENANT_ID, AZURE_CLIENT_ID, dan AZURE_CLIENT_SECRET:

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

ActiveDirectoryWorkloadIdentity

Mengautentikasi menggunakan federasi identitas beban kerja. Gunakan metode ini di pod Kubernetes yang dikonfigurasi dengan Azure Workload Identity.

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

Active Directory Azure Pipelines

Mengautentikasi dengan menggunakan koneksi layanan Azure Pipelines. Berikan parameter alur dalam string koneksi, atau biarkan driver membaca nilai yang hilang dari variabel lingkungan 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

Atur parameter sesuai kebutuhan driver:

Parameter	Description
`user id`	ID klien perwakilan layanan, secara opsional diikuti dengan `@tenant-id`.
`serviceconnectionid`	ID koneksi layanan dari Azure DevOps.
`systemtoken`	Token akses sistem alur (`$(System.AccessToken)`).

ActiveDirectoryClientAssertion

Mengautentikasi dengan menggunakan pernyataan klien (token JWT yang ditandatangani) alih-alih rahasia klien. Berikan JWT yang ditandatangani dalam clientassertion parameter:

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

ActiveDirectoryAtasNama

Melakukan autentikasi dengan alur On-Behalf-Of (OBO). Driver menukarkan token pengguna upstream dengan sebuah token baru yang cakupannya terbatas pada 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

Kaki autentikasi klien dapat menggunakan password, clientcertpath, atau clientassertion, tetapi userassertion selalu diperlukan.

Terintegrasi dengan Active Directory

Mendukung alur kerja Autentikasi Terintegrasi tingkat lanjut. Mode ini memerlukan logika akuisisi token kustom melalui penyedia token.

Gunakan mode ini hanya di Windows. Di Linux dan macOS, gunakan penyedia token kustom untuk alur autentikasi Anda.

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

Penyedia token kustom

Jika tidak ada jenis bawaan fedauth yang sesuai dengan skenario Anda, gunakan salah satu API penyedia token ini untuk menyediakan logika akuisisi token Anda sendiri:

NewSecurityTokenConnector (direkomendasikan)

Gunakan API ini saat Anda memiliki token akses OAuth2 yang telah diperoleh sebelumnya:

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 yang Disederhanakan)

Gunakan API ini untuk akuisisi token yang lebih sederhana tanpa penanganan konteks.

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 (Alur Kerja ADAL Kustom)

Gunakan API ini untuk alur kerja akuisisi token Azure AD kustom jika mode bawaan fedauth maupun API SecurityToken tidak sesuai dengan skenario Anda:

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)

Pendekatan ini berguna ketika Anda perlu berintegrasi dengan penyedia identitas kustom, menerapkan penembolokan token, atau menangani jenis kredensial yang tidak tercakup dalam azuread paket. Sebagian besar aplikasi sebaiknya menggunakan NewSecurityTokenConnector dengan token yang telah diperoleh sebelumnya.

Opsi kredensial umum

Parameter ini berlaku di beberapa jenis fedauth:

Parameter	Description
`applicationclientid`	ID aplikasi klien. Diperlukan untuk `ActiveDirectoryPassword` dan `ActiveDirectoryInteractive`.
`clientcertpath`	Jalur menuju file sertifikat klien PEM atau PFX untuk autentikasi service principal berbasis sertifikat atau On-Behalf-Of.
`clientassertion`	Pernyataan JWT yang ditandatangani untuk `ActiveDirectoryClientAssertion` atau autentikasi On-Behalf-Of.
`serviceconnectionid`	ID koneksi layanan Azure Pipelines.
`systemtoken`	Token akses sistem Azure Pipelines.
`userassertion`	Token pengguna upstream untuk `ActiveDirectoryOnBehalfOf`.
`tokenfilepath`	Jalur ke file token OIDC untuk `ActiveDirectoryWorkloadIdentity` di Kubernetes.
`additionallyallowedtenants`	Daftar ID penyewa tambahan yang dipisahkan koma untuk diizinkan saat autentikasi multipenyewa diperlukan.
`disableinstancediscovery`	Tetapkan ke `true` untuk menonaktifkan deteksi instans; gunakan hanya jika Anda mengendalikan URL otoritas.
`sendcertificatechain`	Atur ke `true` untuk mengirim rantai sertifikat untuk autentikasi berbasis sertifikat.

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-07-21