Tutorial: Menggunakan otomatisasi untuk menyiapkan admin Microsoft Entra untuk SQL Server
Artikel
Berlaku untuk: SQL Server 2022 (16.x)
Catatan
Fitur ini tersedia di SQL Server 2022 (16.x) atau versi yang lebih baru, dan hanya didukung untuk SQL Server lokal, untuk host Windows dan Linux dan SQL Server 2022 di VM Windows Azure.
Dalam artikel ini, kita akan membahas cara menyiapkan admin Microsoft Entra untuk mengizinkan autentikasi dengan ID Microsoft Entra (sebelumnya Azure Active Directory) untuk SQL Server menggunakan portal Azure, dan API seperti:
Meskipun MICROSOFT Entra ID adalah nama baru untuk Azure Active Directory (Azure AD), untuk mencegah mengganggu lingkungan yang ada, Azure AD masih tetap berada di beberapa elemen yang dikodekan secara permanen seperti bidang UI, penyedia koneksi, kode kesalahan, dan cmdlet. Dalam artikel ini, dua nama tersebut dapat dipertukarkan.
Prasyarat
SQL Server 2022 (16.x) atau yang lebih baru diinstal.
Izin berikut diperlukan untuk menyiapkan admin Microsoft Entra di sumber daya SQL Server – Azure Arc dan Key vault .
Mengonfigurasi izin untuk Azure Arc
Ikuti panduan untuk memastikan SQL Server Anda tersambung ke Azure Arc. Pengguna yang menyiapkan admin Microsoft Entra untuk SQL Server – Sumber daya Azure Arc harus memiliki peran Kontributor untuk server.
Pilih SQL Server – Azure Arc, dan pilih instans untuk host SQL Server Anda.
Pilih Kontrol Akses (IAM) .
Pilih Tambahkan>penetapan peran untuk menambahkan peran Kontributor ke pengguna yang menyiapkan admin Microsoft Entra.
Mengonfigurasi izin untuk Azure Key Vault
Buat Azure Key Vault jika Anda belum memilikinya. Pengguna yang menyiapkan admin Microsoft Entra harus memiliki peran Kontributor untuk Azure Key Vault Anda. Untuk menambahkan peran ke pengguna di Azure Key Vault:
Pilih Tambahkan>penetapan peran untuk menambahkan peran Kontributor ke pengguna yang menyiapkan admin Microsoft Entra.
Mengatur kebijakan akses untuk host SQL Server
Di portal Azure, navigasikan ke instans Azure Key Vault Anda, dan pilih Kebijakan akses.
Pilih Tambahkan Kebijakan Akses.
Untuk Izin kunci, gunakan Tanda tangani.
Untuk Izin rahasia, pilih Dapatkan dan Daftar.
Untuk Izin sertifikat, pilih Dapatkan dan Daftar.
Pilih Selanjutnya.
Pada halaman Utama , cari nama komputer Anda - instans Azure Arc, yang merupakan nama host host SQL Server.
Lewati halaman Aplikasi (opsional) dengan memilih Berikutnya dua kali, atau pilih Tinjau + buat.
Verifikasi bahwa "ID Objek" Dari Prinsipal cocok dengan ID Utama identitas terkelola yang ditetapkan ke instans.
Untuk mengonfirmasi, buka halaman sumber daya dan pilih Tampilan JSON di kanan atas kotak Esensial di halaman Gambaran Umum. Di bawah identitas , Anda akan menemukan principalId.
Pilih Buat.
Anda harus memilih Buat untuk memastikan bahwa izin diterapkan. Untuk memastikan izin telah disimpan, refresh jendela browser, dan periksa apakah baris untuk instans Azure Arc Anda masih ada.
Mengatur kebijakan akses untuk pengguna Microsoft Entra
Di portal Azure, navigasikan ke instans Azure Key Vault Anda, dan pilih Kebijakan akses.
Pilih Tambahkan Kebijakan Akses.
Untuk Izin kunci, pilih Dapatkan, Daftar, dan Buat.
Untuk Izin rahasia, pilih Dapatkan, Daftar, dan Atur.
Untuk Izin sertifikat, pilih Dapatkan, Daftar, dan Buat.
Untuk Pilih prinsipal, tambahkan pengguna Microsoft Entra yang ingin Anda gunakan untuk menyambungkan ke SQL Server.
Pilih Tambahkan lalu pilih Simpan.
Menyiapkan admin Microsoft Entra untuk SQL Server
Api baru dan fungsionalitas portal memungkinkan pengguna menyiapkan admin Microsoft Entra untuk SQL Server tanpa harus membuat sertifikat Azure dan aplikasi Microsoft Entra secara terpisah. Pilih tab untuk mempelajari cara menyiapkan admin Microsoft Entra untuk SQL Server Anda yang tersambung ke Azure Arc dengan sertifikat otomatis dan pembuatan aplikasi.
Gunakan portal Azure untuk menyiapkan admin Microsoft Entra, membuat sertifikat Azure Key Vault dan aplikasi Microsoft Entra dalam proses yang sama. Ini diperlukan untuk menggunakan autentikasi Microsoft Entra dengan SQL Server.
Menyiapkan admin Microsoft Entra menggunakan portal Azure
Buka portal Azure, dan pilih SQL Server – Azure Arc. Pilih instans untuk host SQL Server Anda.
Periksa status sumber daya SQL Server - Azure Arc Anda dan lihat apakah sumber daya tersebut tersambung dengan masuk ke menu Properti. Untuk informasi selengkapnya, lihat Memvalidasi sumber daya SQL Server dengan dukungan Arc Anda.
Pilih ID Microsoft Entra dan Purview di bawah Pengaturan dari menu sumber daya.
Pilih Atur Admin untuk membuka panel ID Microsoft Entra, dan pilih akun yang akan ditambahkan sebagai login admin ke SQL Server.
Pilih Sertifikasi yang dikelola layanan.
Pilih Ubah brankas kunci dan pilih sumber daya Azure Key vault yang sudah ada.
Pilih Pendaftaran aplikasi yang dikelola layanan.
Pilih Simpan. Ini mengirimkan permintaan ke agen server Arc, yang mengonfigurasi autentikasi Microsoft Entra untuk instans SQL Server tersebut. Operasi dapat memakan waktu beberapa menit untuk diselesaikan; tunggu hingga proses penyimpanan dikonfirmasi sebelum Saved successfully mencoba masuk Microsoft Entra.
Pendaftaran aplikasi yang dikelola layanan melakukan hal berikut untuk Anda:
Membuat sertifikat di brankas kunci Anda dengan nama dalam formulir <hostname>-<instanceName><uniqueNumber>.
Membuat aplikasi Microsoft Entra dengan nama seperti <hostname>-<instanceName><uniqueNumber>, dan menetapkan izin yang diperlukan untuk aplikasi tersebut. Untuk informasi selengkapnya, lihat Memberikan izin aplikasi
Menetapkan sertifikat baru di Azure Key Vault ke aplikasi.
Menyimpan pengaturan ini ke Azure Arc.
Catatan
Sertifikat yang dibuat untuk Microsoft Entra tidak diputar secara otomatis. Pelanggan dapat memilih untuk menyediakan sertifikat dan aplikasi mereka sendiri untuk penyiapan admin Microsoft Entra. Untuk informasi selengkapnya, lihat Tutorial: Menyiapkan autentikasi Microsoft Entra untuk SQL Server.
Sertifikat yang dibuat untuk penyiapan Microsoft Entra tidak diputar secara otomatis.
Azure CLI versi 2.37.0 atau yang lebih tinggi diperlukan
Diperlukan Az.ConnectedMachine 0.5.1 atau yang lebih tinggi
Untuk menginstal Az.ConnectedMachine modul, gunakan az extension add --name ConnectedMachine. Untuk memeriksa versi Azure CLI mana yang diinstal, gunakan az version.
Parameter input berikut digunakan untuk skrip Azure CLI:
<applicationName> - Nama aplikasi yang akan dibuat
<certSubjectName> - Nama sertifikat yang akan dibuat
<keyVaultName> - Nama brankas kunci Anda. Brankas kunci ini harus dibuat sebelum menjalankan skrip
<machineName> - Nama mesin host SQL Server Anda
<resourceGroupName>- Nama grup sumber daya yang berisi SQL Server Anda – instans Azure Arc
<adminAccountName> - Akun admin Microsoft Entra yang ingin Anda tetapkan untuk SQL Server Anda
<instanceName> - Parameter opsional untuk instans bernama SQL Server. Gunakan parameter ini saat Anda memiliki instans bernama. Jika dihilangkan, nama default digunakan MSSQLSERVER
<tenantId> - Parameter opsional untuk ID penyewa. ID penyewa dapat ditemukan dengan masuk ke portal Azure, dan masuk ke sumber daya ID Microsoft Entra Anda. Di panel Gambaran Umum, Anda akan melihat ID Penyewa Anda. Jika dihilangkan, ID penyewa default digunakan sebagai parameter
<subscriptionId> - Parameter opsional untuk ID langganan. ID langganan Anda dapat ditemukan di portal Azure. Jika dihilangkan, ID langganan default digunakan
Untuk menggunakan skrip Azure CLI di bawah ini, simpan skrip sebagai .ps1 file, dan jalankan perintah berikut:
Untuk SQL Server pada komputer host Linux, ganti WindowsAgent.SqlServer dengan LinuxAgent.SqlServer dalam skrip.
# AZ CLI and AZ CLI's connected machine extension must be installed before running this script
param (
[Parameter(mandatory=$true)] $applicationName,
[Parameter(mandatory=$true)] $certSubjectName,
[Parameter(mandatory=$true)] $keyVaultName,
[Parameter(mandatory=$true)] $machineName,
[Parameter(mandatory=$true)] $resourceGroupName,
[Parameter(mandatory=$true)] $adminAccountName,
$instanceName,
$tenantId,
$subscriptionId
)
# Constants
#
$NUMRETRIES = 60
# Helper functions
#
function ConvertFrom-StringArray {
param (
[string[]] $stringArray
)
if (!$stringArray)
{
return $null
}
else
{
return ConvertFrom-JSON ($stringArray -join "`n")
}
}
# Check parameters
#
if ([string]::IsNullOrEmpty($instanceName))
{
Write-Host "Warning: SQL Instance name (-instanceName) not provided. Default of MSSQLSERVER will be used"
$instanceName = "MSSQLSERVER"
}
$tenantIdArgument = ""
if ([string]::IsNullOrEmpty($tenantId))
{
Write-Host "Warning: Tenant ID (-tenantId) not supplied to the script, so default tenant is being used"
}
else
{
$tenantIdArgument = "-TenantId '" + $tenantId + "'"
}
$subscriptionIdArgument = ""
if ([string]::IsNullOrEmpty($subscriptionId))
{
Write-Host "Warning: Subscription ID (-subscriptionId) not supplied to the script, so default subscription is being used"
}
else
{
$subscriptionIdArgument = "-SubscriptionId '" + $subscriptionId + "'"
}
# Login and select subscription
#
$login = az login --tenant $tenantId --use-device-code
if (!$login)
{
Write-Error "Login to Azure AD failed. Exiting."
exit 1
}
if ($subscriptionId)
{
az account set -s $subscriptionId
}
$accountInfo = ConvertFrom-StringArray (az account show)
if (!$accountInfo)
{
Write-Error "Cannot query logged in Azure AD account. Check that 'az login' and 'az account set' succeeded"
exit 1
}
if ($subscriptionId)
{
if ($subscriptionId.ToLower() -ne $accountInfo.id.ToLower())
{
Write-Error "Could not select the desired subscription"
exit 1
}
}
else
{
$subscriptionId = $accountInfo.id
}
# Check AKV path exists
#
$keyVault = ConvertFrom-StringArray (az keyvault show --name $keyVaultName)
if (!$keyVault)
{
Write-Error "Azure key vault '$keyVaultName' does not exist"
exit 1
}
# Check certificate doesn't exist
#
$cert = ConvertFrom-StringArray (az keyvault certificate show --name $certSubjectName --vault-name $keyVaultName 2>$null)
if ($cert)
{
Write-Error "Certificate '$certSubjectName' already exists in key vault '$keyVaultName'"
exit 1
}
# Check app registration doesn't exist
#
$applications = ConvertFrom-StringArray (az ad app list --display-name $applicationName --only-show-errors)
if ($applications.length -gt 0)
{
Write-Error "App registration with name '$applicationName' already exists"
exit 1
}
# Check Arc SQL instance is valid
#
$extension = ConvertFrom-StringArray (az connectedmachine extension show --machine-name $machineName --name "WindowsAgent.SqlServer" --resource-group $resourceGroupName)
if (!$extension)
{
Write-Error "SQL Server Arc Server not found for machine '$machineName' in resource group '$resourceGroupName'"
exit 1
}
$arcServicePrincipals = ConvertFrom-StringArray(az ad sp list --display-name $machineName --only-show-errors)
if (!$arcServicePrincipals -or $arcServicePrincipals.length -eq 0)
{
Write-Error "Could not find a service principal account with the name '$machineName'"
exit 1
}
else
{
$principalFound = $false
for ($i = 0; $i -lt $arcServicePrincipals.length; $i++)
{
if ($arcServicePrincipals[$i].displayName.toLower() -eq $machineName.toLower()) {
if ($principalFound) {
Write-Error "Could not find exactly one service principal account with the name '$machineName'"
exit 1
}
$arcServicePrincipal = $arcServicePrincipals[$i]
$principalFound = $true
}
}
if (!$principalFound) {
Write-Error "Could not find a service principal account with the name '$machineName'"
exit 1
}
}
# Check if admin account exists
#
$adminAccount = ConvertFrom-StringArray (az ad user show --id $adminAccountName --only-show-errors 2>$null)
$adminAccountType = 0
if (!$adminAccount)
{
$adminAccounts = ConvertFrom-StringArray (az ad user list --filter "mail eq '$adminAccountName'" --only-show-errors 2>$null)
if ($adminAccounts -and $adminAccounts.length -gt 0)
{
if ($adminAccounts.length -eq 1)
{
$adminAccount = $adminAccounts[0]
}
else
{
Write-Error "Multiple Azure AD accounts found with identifier '$adminAccountName'"
exit 1
}
}
else
{
$adminAccount = ConvertFrom-StringArray (az ad group show --group $adminAccountName --only-show-errors 2>$null)
if (!$adminAccount)
{
$adminAccounts = ConvertFrom-StringArray (az ad app list --display-name $adminAccountName --only-show-errors 2>$null)
if ($adminAccounts -and $adminAccounts.length -gt 0)
{
if ($adminAccounts.length -eq 1)
{
$adminAccount = $adminAccounts[0]
}
else
{
Write-Error "Multiple Azure AD applications found with identifier '$adminAccountName'"
exit 1
}
}
else
{
Write-Error "Admin account not found"
exit 1
}
}
else
{
$adminAccountType = 1
}
}
}
if ($adminAccount)
{
$adminAccountSid = $adminAccount.id
}
else
{
Write-Error "Admin account not found"
exit 1
}
# Create certificate in AKV
#
$keyVaultPolicy = ConvertFrom-StringArray (az keyvault certificate get-default-policy)
if (!$keyVaultPolicy)
{
Write-Error "Could not get default key vault policy"
exit 1
}
$keyVaultPolicy.x509CertificateProperties.subject = "CN=" + $certSubjectName
$policyString = (ConvertTo-JSON -Depth 8 $keyVaultPolicy).replace("`r`n", "")
$escapedPolicyString = $policyString.replace("`"", "\`"")
$cert = ConvertFrom-StringArray (az keyvault certificate create --vault-name $keyVaultName --name $certSubjectName --policy $escapedPolicyString)
if (!$cert)
{
Write-Error "Failed to create certificate '$certSubjectName'"
exit 1
}
# Wait until cert is created?
#
$cert = ConvertFrom-StringArray (az keyvault certificate show --vault-name $keyVaultName --name $certSubjectName)
for (($i = 0); $i -lt $NUMRETRIES -and (!$cert -or !$cert.attributes.enabled); $i++)
{
$cert = ConvertFrom-StringArray (az keyvault certificate show --vault-name $keyVaultName --name $certSubjectName)
if (!$cert -or !$cert.attributes.enabled)
{
Start-Sleep -Seconds 5
}
}
# Allow Arc to access AKV
#
$newPerms = ConvertFrom-StringArray (az keyvault set-policy --name $keyVaultName --secret-permissions get list --certificate-permissions get list --object-id $arcServicePrincipal.id)
if (!$newPerms)
{
Write-Host "Warning: Unable to add permissions to key vault '$keyVaultName' for Arc's service principal's identity '$($arcServicePrincipal.id)'. Arc may not be able to configure Azure AD authentication"
}
# Create an Azure AD application
#
$application = ConvertFrom-StringArray (az ad app create --display-name $applicationName --only-show-errors)
if (!$application)
{
Write-Error "Unable to create the app registration '$applicationName'"
exit 1
}
# Set perms on app registration
#
az ad app permission add --id $application.id --api 00000003-0000-0000-c000-000000000000 --api-permissions c79f8feb-a9db-4090-85f9-90d820caa0eb=Scope --only-show-errors # Delegated Application.Read.All
az ad app permission add --id $application.id --api 00000003-0000-0000-c000-000000000000 --api-permissions 0e263e50-5827-48a4-b97c-d940288653c7=Scope --only-show-errors # Delegated Directory.AccessAsUser.All
az ad app permission add --id $application.id --api 00000003-0000-0000-c000-000000000000 --api-permissions 7ab1d382-f21e-4acd-a863-ba3e13f7da61=Role --only-show-errors # Application Directory.Read.All
az ad app permission add --id $application.id --api 00000003-0000-0000-c000-000000000000 --api-permissions 5f8c59db-677d-491f-a6b8-5f174b11ec1d=Scope --only-show-errors # Delegated Group.Read.All
az ad app permission add --id $application.id --api 00000003-0000-0000-c000-000000000000 --api-permissions a154be20-db9c-4678-8ab7-66f6cc099a59=Scope --only-show-errors # Delegated User.Read.All
# Upload cert to Azure AD
#
$certUploadRes = ConvertFrom-StringArray (az ad app credential reset --id $application.id --cert $certSubjectName --keyvault $keyVaultName --append --only-show-errors)
if (!$certUploadRes)
{
Write-Error "Failed to set certificate '$certSubjectName' as a credential for app registration '$applicationName'"
exit 1
}
# Remove the version from the secret ID if present
#
$secretId = $cert.sid
if ($secretId -Match "(https:\/\/[^\/]+\/secrets\/[^\/]+)(\/.*){0,1}$") {
if ($Matches[1]) {
$secretId = $Matches[1]
}
}
# Create the settings object to write to the Azure extension for SQL Server
#
$instanceSettings = @{
instanceName = $instanceName
adminLoginName = $adminAccountName
adminLoginSid = $adminAccountSid
azureCertSecretId = $secretId
azureCertUri = $cert.id
azureKeyVaultResourceUID = $keyVault.id
managedCertSetting = "CUSTOMER MANAGED CERT"
managedAppSetting = "CUSTOMER MANAGED APP"
appRegistrationName = $application.displayName
appRegistrationSid = $application.appId
tenantId = $tenantId
aadCertSubjectName = $certSubjectName
adminLoginType = $adminAccountType
}
$extension = ConvertFrom-StringArray (az connectedmachine extension show --machine-name $machineName --name "WindowsAgent.SqlServer" --resource-group $resourceGroupName)
if ($extension.properties.Settings.AzureAD)
{
$aadSettings = $extension.properties.Settings.AzureAD
$instanceFound = $false
$instanceNameLower = $instanceName.ToLower()
$instanceIndex = 0
for (($i = 0); $i -lt $aadSettings.Length; $i++)
{
if ($aadSettings[$i].instanceName.ToLower() -eq $instanceNameLower)
{
$instanceIndex = $i
$instanceFound = $true
break
}
}
if ($instanceFound)
{
$aadSettings[$instanceIndex] = $instanceSettings
}
else
{
$aadSettings += $instanceSettings
}
$extension.properties.Settings.AzureAD = $aadSettings
}
else
{
$aadSettings = , $instanceSettings
$extension.properties.Settings | Add-Member -Name 'AzureAD' -Value $aadSettings -MemberType NoteProperty
}
$settingsString = (ConvertTo-Json $extension.properties.Settings).replace("`"", "\`"").replace("`r`n", "")
# Push settings to Arc
#
Write-Host "Writing Azure AD setting to Azure extension for SQL Server. This may take several minutes..."
$updateRes = az connectedmachine extension update --machine-name $machineName --name "WindowsAgent.SqlServer" --resource-group $resourceGroupName --settings $settingsString
if (!$updateRes)
{
Write-Error "Failed to update Azure extension for SQL Server with Azure AD settings"
exit 1
}
Write-Output "Success"
Menjalankan skrip dapat memakan waktu beberapa menit untuk diselesaikan. Setelah proses selesai, pesan yang mirip dengan yang berikut ini akan muncul:
Name Location ProvisioningState
---- -------- -----------------
WindowsAgent.SqlServer westus2 Succeeded
Success
Menyiapkan admin Microsoft Entra dengan sertifikat dan aplikasi yang sudah ada menggunakan Azure CLI
Jika Anda sudah memiliki sertifikat Azure Key Vault, dan aplikasi Azure yang ingin Anda gunakan untuk menyiapkan admin Microsoft Entra, Anda dapat menggunakan skrip CLI berikut:
# Set up Microsoft Entra admin for user's existing key vault, certificate, and application
# Requires input parameters indicated below
# Connect statement
AZ Login
#Input parameters
$subscriptionId="<subscriptionId>"
$tenantId="<tenantId>"
$machineName="<machineName>" # hostname
$instanceName="<instanceName>" # SQL Server is define as `machine_name\instance_name`
$resourceGroupName="<resourceGroupName>"
$keyVaultName="<keyVaultName>"
$certSubjectName="<certSubjectName>" # Your existing certificate name
$applicationName="<applicationName>" # Your existing application name
$adminAccountName="<adminAccountName>"
$adminAccountSid="<adminID>" # Use object ID for the Azure AD user and group, or client ID for the Azure AD application
$adminAccountType= 0 # 0 – for Azure AD user and application, 1 for Azure AD group
# Helper function
#
function ConvertFrom-StringArray {
param (
[string[]] $stringArray
)
if (!$stringArray)
{
return $null
}
else
{
return ConvertFrom-JSON ($stringArray -join "`n")
}
}
$keyVault = ConvertFrom-StringArray (az keyvault show --name $keyVaultName)
if (!$keyVault)
{
Write-Error "Azure key vault '$keyVaultName' does not exist"
exit 1
}
$cert = ConvertFrom-StringArray (az keyvault certificate show --name $certSubjectName --vault-name $keyVaultName 2>$null)
if (!$cert)
{
Write-Error "Supplied certificate $certSubjectName was not found for this key vault. Please specify an existing certficate"
exit 1
}
$secretId = $cert.sid
if ($secretId -Match "(https:\/\/[^\/]+\/secrets\/[^\/]+)(\/.*){0,1}$") {
if ($Matches[1]) {
$secretId = $Matches[1]
}
}
$application = ConvertFrom-StringArray (az ad app list --display-name $applicationName --only-show-errors)
if (!$application)
{
Write-Error "Supplied application was not found in the subscription. Please specify an existing application"
exit 1
}
# Create the settings object to write to the Arc extension
#
$instanceSettings = @{
instanceName = $instanceName
adminLoginName = $adminAccountName
adminLoginSid = $adminAccountSid
azureCertSecretId = $secretId
azureCertUri = $cert.id
azureKeyVaultResourceUID = $keyVault.id
managedCertSetting = "CUSTOMER MANAGED CERT"
managedAppSetting = "CUSTOMER MANAGED APP"
appRegistrationName = $application.displayName
appRegistrationSid = $application.appId
tenantId = $tenantId
aadCertSubjectName = $certSubjectName
adminLoginType = $adminAccountType
}
$extension = ConvertFrom-StringArray (az connectedmachine extension show --machine-name $machineName --name "WindowsAgent.SqlServer" --resource-group $resourceGroupName)
if ($extension.properties.Settings.AzureAD)
{
$aadSettings = $extension.properties.Settings.AzureAD
$instanceFound = $false
$instanceNameLower = $instanceName.ToLower()
$instanceIndex = 0
for (($i = 0); $i -lt $aadSettings.Length; $i++)
{
if ($aadSettings[$i].instanceName.ToLower() -eq $instanceNameLower)
{
$instanceIndex = $i
$instanceFound = $true
break
}
}
if ($instanceFound)
{
$aadSettings[$instanceIndex] = $instanceSettings
}
else
{
$aadSettings += $instanceSettings
}
$extension.properties.Settings.AzureAD = $aadSettings
}
else
{
$aadSettings = , $instanceSettings
$extension.properties.Settings | Add-Member -Name 'AzureAD' -Value $aadSettings -MemberType NoteProperty
}
$settingsString = (ConvertTo-Json $extension.properties.Settings).replace("`"", "\`"").replace("`r`n", "")
# Push settings to Arc
#
Write-Host "Writing Azure AD setting to SQL Server Arc Extension. This may take several minutes..."
$updateRes = az connectedmachine extension update --machine-name $machineName --name "WindowsAgent.SqlServer" --resource-group $resourceGroupName --settings $settingsString
if (!$updateRes)
{
Write-Error "Failed to update SQL Arc Extension with Azure AD settings"
exit 1
}
Write-Output "Success"
Sertifikat yang dibuat untuk penyiapan Microsoft Entra tidak diputar secara otomatis.
Modul berikut diperlukan untuk tutorial ini. Instal versi terbaru modul atau yang lebih tinggi dari versi yang tercantum di bawah ini:
Az.Accounts 3.37.0
Az.ConnectedMachine 0.5.0
Az.KeyVault 4.5.0
Az.Resources 6.0.0
Parameter input berikut digunakan untuk skrip PowerShell:
<applicationName> - Nama aplikasi yang akan dibuat
<certSubjectName> - Nama sertifikat yang akan dibuat
<keyVaultName> - Nama brankas kunci Anda. Brankas kunci ini harus dibuat sebelum menjalankan skrip
<machineName> - Nama mesin host SQL Server Anda
<resourceGroupName>- Nama grup sumber daya yang berisi SQL Server Anda – instans Azure Arc
<adminAccountName> - Akun admin Microsoft Entra yang ingin Anda tetapkan untuk SQL Server Anda
<instanceName> - Parameter opsional untuk instans bernama SQL Server. Gunakan parameter ini saat Anda memiliki instans bernama. Jika dihilangkan, nama default digunakan MSSQLSERVER
<tenantId> - Parameter opsional untuk ID penyewa. ID penyewa dapat ditemukan dengan masuk ke portal Azure, dan masuk ke sumber daya ID Microsoft Entra Anda. Di panel Gambaran Umum, Anda akan melihat ID Penyewa Anda. Jika dihilangkan, ID penyewa default digunakan sebagai parameter
<subscriptionId> - Parameter opsional untuk ID langganan. ID langganan Anda dapat ditemukan di portal Azure. Jika dihilangkan, ID langganan default digunakan
Untuk menggunakan skrip PowerShell di bawah ini, simpan skrip sebagai .ps1 file, dan jalankan perintah berikut:
Untuk SQL Server pada komputer host Linux, ganti WindowsAgent.SqlServer dengan LinuxAgent.SqlServer dalam skrip.
param (
[Parameter(mandatory=$true)] $applicationName,
[Parameter(mandatory=$true)] $certSubjectName,
[Parameter(mandatory=$true)] $keyVaultName,
[Parameter(mandatory=$true)] $machineName,
[Parameter(mandatory=$true)] $resourceGroupName,
[Parameter(mandatory=$true)] $adminAccountName,
$instanceName,
$tenantId,
$subscriptionId
)
Import-Module Az.Accounts
Import-Module Az.ConnectedMachine
Import-Module Az.KeyVault
Import-Module Az.Resources
# Constants
#
$NUMRETRIES = 60
# Check parameters
#
if ([string]::IsNullOrEmpty($instanceName))
{
Write-Host "Warning: SQL Instance name (-instanceName) not provided. Default of MSSQLSERVER will be used"
$instanceName = "MSSQLSERVER"
}
$tenantIdArgument = ""
if ([string]::IsNullOrEmpty($tenantId))
{
Write-Host "Warning: Tenant ID (-tenantId) not supplied to the script, so default tenant is being used"
}
else
{
$tenantIdArgument = "-TenantId '" + $tenantId + "'"
}
$subscriptionIdArgument = ""
if ([string]::IsNullOrEmpty($subscriptionId))
{
Write-Host "Warning: Subscription ID (-subscriptionId) not supplied to the script, so default subscription is being used"
}
else
{
$subscriptionIdArgument = "-SubscriptionId '" + $subscriptionId + "'"
}
# Login
#
try
{
$loginRes = Invoke-Expression -Command ("Connect-AzAccount " + $tenantIdArgument + " " + $subscriptionIdArgument + " -ErrorAction stop -UseDeviceAuthentication")
}
catch
{
Write-Error $_
Write-Error "Failed to login to Azure. Script can not continue"
exit 1
}
# Get subscription ID
#
if ([string]::IsNullOrEmpty($subscriptionId))
{
$context = Get-AzContext
if ($context)
{
if ($context.Name -Match "[^(]+\(([^)]{36})\)")
{
if ($Matches[1])
{
$subscriptionId = $Matches[1]
}
}
}
}
if ([string]::IsNullOrEmpty($subscriptionId))
{
Write-Error "Failed to find default subscription"
exit 1
}
# Check AKV path exists
#
$keyVault = Get-AzKeyVault -VaultName $keyVaultName
if (!$keyVault)
{
Write-Error "Supplied key vault was not found in the subscription. Please specify an existing key vault"
exit 1
}
# Check certificate doesn't exist
#
$cert = Get-AzKeyVaultCertificate -VaultName $keyVaultName -Name $certSubjectName
if ($cert)
{
Write-Error "Certificate $certSubjectName already exists"
exit 1
}
# Check app registration doesn't exist
#
$application = Get-AzADApplication -DisplayName $applicationName
if ($application)
{
Write-Error "Application $applicationName already exists"
exit 1
}
# Check Arc SQL instance is valid
#
$arcInstance = Get-AzConnectedMachineExtension -SubscriptionId $subscriptionId -MachineName $machineName -ResourceGroupName $resourceGroupName -Name "WindowsAgent.SqlServer"
if (!$arcInstance)
{
Write-Error "Could not find a SQL Server Arc instance in subscription '$subscriptionId' and resource group '$resourceGroupName' with name '$machineName'"
exit 1
}
# Check if admin account exists
#
$adminAccount = Get-AzADUser -UserPrincipalName $adminAccountName
$adminAccountType = 0
if (!$adminAccount)
{
# Check for guest user
#
$adminAccount = Get-AzADUser -Mail $adminAccountName
if (!$adminAccount)
{
$adminAccount = Get-AzADGroup -DisplayName $adminAccountName
if (!$adminAccount)
{
$adminAccount = Get-AzADServicePrincipal -DisplayName $adminAccountName
}
else
{
$adminAccountType = 1
}
}
}
if ($adminAccount)
{
if ($adminAccount.Length -gt 1)
{
Write-Error "Multiple accounts with found with name $adminAccountName"
exit 1
}
$adminAccountSid = $adminAccount.Id
}
else
{
Write-Error "Could not find an account with name $adminAccountName"
exit 1
}
# Create certificate in AKV
#
$Policy = New-AzKeyVaultCertificatePolicy -SecretContentType "application/x-pkcs12" -SubjectName "CN=$certSubjectName" -IssuerName "Self" -ValidityInMonths 12 -ReuseKeyOnRenewal
try
{
$addCertRes = Add-AzKeyVaultCertificate -VaultName $keyVaultName -Name $certSubjectName -CertificatePolicy $Policy -ErrorAction stop
}
catch
{
Write-Error $_
Write-Error "Certificate $certSubjectName could not be created"
exit 1
}
for (($i = 0); $i -lt $NUMRETRIES -and (!$cert -or !$cert.enabled); $i++)
{
$cert = Get-AzKeyVaultCertificate -VaultName $keyVaultName -Name $certSubjectName
if (!$cert -or !$cert.enabled)
{
Start-Sleep -Seconds 5
}
}
if (!$cert)
{
Write-Error "Certificate $certSubjectName could not be created"
exit 1
}
# Allow Arc to access AKV
#
$arcServicePrincipal = Get-AzADServicePrincipal -DisplayName $machineName
if ($arcServicePrincipal -and ![string]::IsNullOrEmpty($arcServicePrincipal.Id))
{
try
{
Set-AzKeyVaultAccessPolicy -VaultName $keyVaultName -ObjectId $arcServicePrincipal.Id -PermissionsToSecrets Get,List -PermissionsToCertificates Get,List
}
catch
{
Write-Error $_
Write-Host "Warning: Could not find the identity of the Azure extension for SQL Server and thus, could not add permissions for the Arc process to read from AKV. Ensure the Arc identity has the required permissions to read from AKV."
}
}
else
{
Write-Host "Warning: Could not find the identity of the Azure extension for SQL Server and thus, could not add permissions for the Arc process to read from AKV. Ensure the Arc identity has the required permissions to read from AKV."
}
# Create an Azure AD application
#
$application = New-AzADApplication -DisplayName $applicationName
if (!$application)
{
Write-Error "Application could not be created"
exit 1
}
# Set perms on app registration
#
Add-AzADAppPermission -ObjectId $application.Id -ApiId 00000003-0000-0000-c000-000000000000 -PermissionId c79f8feb-a9db-4090-85f9-90d820caa0eb # Delegated Application.Read.All
Add-AzADAppPermission -ObjectId $application.Id -ApiId 00000003-0000-0000-c000-000000000000 -PermissionId 0e263e50-5827-48a4-b97c-d940288653c7 # Delegated Directory.AccessAsUser.All
Add-AzADAppPermission -ObjectId $application.Id -ApiId 00000003-0000-0000-c000-000000000000 -PermissionId 7ab1d382-f21e-4acd-a863-ba3e13f7da61 -Type Role # Application Directory.Read.All
Add-AzADAppPermission -ObjectId $application.Id -ApiId 00000003-0000-0000-c000-000000000000 -PermissionId 5f8c59db-677d-491f-a6b8-5f174b11ec1d # Delegated Group.Read.All
Add-AzADAppPermission -ObjectId $application.Id -ApiId 00000003-0000-0000-c000-000000000000 -PermissionId a154be20-db9c-4678-8ab7-66f6cc099a59 # Delegated User.Read.All
# Upload cert to Azure AD
#
try
{
$base64Cert = [System.Convert]::ToBase64String($cert.Certificate.GetRawCertData())
New-AzADAppCredential -ApplicationObject $application -CertValue $base64Cert -EndDate $cert.Certificate.NotAfter -StartDate $cert.Certificate.NotBefore -ErrorAction stop
}
catch
{
Write-Error $_
Write-Error "Failed to add certificate to app registration"
exit 1
}
# Remove the version from the secret ID if present
#
$secretId = $cert.SecretId
if ($secretId -Match "(https:\/\/[^\/]+\/secrets\/[^\/]+)(\/.*){0,1}$") {
if ($Matches[1]) {
$secretId = $Matches[1]
}
}
# Create the settings object to write to the Azure extension for SQL Server
#
$instanceSettings = @{
instanceName = $instanceName
adminLoginName = $adminAccountName
adminLoginSid = $adminAccountSid
azureCertSecretId = $secretId.replace(":443", "")
azureCertUri = $cert.Id.replace(":443", "")
azureKeyVaultResourceUID = $keyVault.ResourceId
managedCertSetting = "CUSTOMER MANAGED CERT"
managedAppSetting = "CUSTOMER MANAGED APP"
appRegistrationName = $application.DisplayName
appRegistrationSid = $application.AppId
tenantId = $tenantId
aadCertSubjectName = $certSubjectName
adminLoginType = $adminAccountType
}
$arcInstance = Get-AzConnectedMachineExtension -SubscriptionId $subscriptionId -MachineName $machineName -ResourceGroupName $resourceGroupName -Name "WindowsAgent.SqlServer"
if ($arcInstance.Setting.AdditionalProperties.AzureAD)
{
$aadSettings = $arcInstance.Setting.AdditionalProperties.AzureAD
$instanceFound = $false
$instanceNameLower = $instanceName.ToLower()
$instanceIndex = 0
for (($i = 0); $i -lt $aadSettings.Length; $i++)
{
if ($aadSettings[$i].instanceName.ToLower() -eq $instanceNameLower)
{
$instanceIndex = $i
$instanceFound = $true
break
}
}
if ($instanceFound)
{
$aadSettings[$instanceIndex] = $instanceSettings
}
else
{
$aadSettings += $instanceSettings
}
$arcInstance.Setting.AdditionalProperties.AzureAD = $aadSettings
}
else
{
$aadSettings = , $instanceSettings
$arcInstance.Setting.AdditionalProperties | Add-Member -Name 'AzureAD' -Value $aadSettings -MemberType NoteProperty
}
Write-Host "Writing Microsoft Entra setting to SQL Server Arc Extension. This may take several minutes..."
# Push settings to Arc
#
try
{
Update-AzConnectedMachineExtension -MachineName $machineName -Name "WindowsAgent.SqlServer" -ResourceGroupName $resourceGroupName -Setting $arcInstance.Setting
}
catch
{
Write-Error $_
Write-Error "Failed to write settings to Arc host"
exit 1
}
Write-Output "Success"
Menyiapkan admin Microsoft Entra dengan sertifikat dan aplikasi yang sudah ada menggunakan PowerShell
Jika Anda sudah memiliki sertifikat Azure Key Vault yang sudah ada, dan aplikasi Azure yang ingin Anda gunakan untuk menyiapkan admin Microsoft Entra, Anda bisa menggunakan skrip PowerShell berikut ini:
# Connect statement
Connect-AzAccount
#Input parameters
$subscriptionId="<subscriptionId>"
$tenantId="<tenantId>"
$machineName="<machineName>" # hostname
$instanceName="<instanceName>" # SQL Server is define as `machine_name\instance_name`
$resourceGroupName="<resourceGroupName>"
$keyVaultName="<keyVaultName>"
$certSubjectName="<certSubjectName>" # Your existing certificate name
$applicationName="<applicationName>" # Your existing application name
$adminAccountName="<adminAccountName>"
$adminAccountSid="<adminID>" # Use object ID for the Microsoft Entra user and group, or client ID for the Microsoft Entra application
$adminAccountType= 0 # 0 – for Microsoft Entra user and application, 1 for Microsoft Entra group
$keyVault = Get-AzKeyVault -VaultName $keyVaultName
if (!$keyVault)
{
Write-Error "Supplied key vault was not found in the subscription. Please specify an existing key vault"
exit 1
}
$cert = Get-AzKeyVaultCertificate -VaultName $keyVaultName -Name $certSubjectName
if (!$cert)
{
Write-Error "Supplied certificate $certSubjectName was not found for this key vault. Please specify an existing certificate"
exit 1
}
$secretId = $cert.SecretId
if ($secretId -Match "(https:\/\/[^\/]+\/secrets\/[^\/]+)(\/.*){0,1}$") {
if ($Matches[1]) {
$secretId = $Matches[1]
}
}
$application = Get-AzADApplication -DisplayName $applicationName
if (!$application)
{
Write-Error "Supplied application was not found in the subscription. Please specify an existing application"
exit 1
}
# Create the settings object to write to the Arc extension
#
$instanceSettings = @{
instanceName = $instanceName
adminLoginName = $adminAccountName
adminLoginSid = $adminAccountSid
azureCertSecretId = $secretId.replace(":443", "")
azureCertUri = $cert.Id.replace(":443", "")
azureKeyVaultResourceUID = $keyVault.ResourceId
managedCertSetting = "CUSTOMER MANAGED CERT"
managedAppSetting = "CUSTOMER MANAGED APP"
appRegistrationName = $application.DisplayName
appRegistrationSid = $application.AppId
tenantId = $tenantId
aadCertSubjectName = $certSubjectName
adminLoginType = $adminAccountType
}
$arcInstance = Get-AzConnectedMachineExtension -SubscriptionId $subscriptionId -MachineName $machineName -ResourceGroupName $resourceGroupName -Name "WindowsAgent.SqlServer"
if ($arcInstance.Setting.AdditionalProperties.AzureAD)
{
$aadSettings = $arcInstance.Setting.AdditionalProperties.AzureAD
$instanceFound = $false
$instanceNameLower = $instanceName.ToLower()
$instanceIndex = 0
for (($i = 0); $i -lt $aadSettings.Length; $i++)
{
if ($aadSettings[$i].instanceName.ToLower() -eq $instanceNameLower)
{
$instanceIndex = $i
$instanceFound = $true
break
}
}
if ($instanceFound)
{
$aadSettings[$instanceIndex] = $instanceSettings
}
else
{
$aadSettings += $instanceSettings
}
$arcInstance.Setting.AdditionalProperties.AzureAD = $aadSettings
}
else
{
$aadSettings = , $instanceSettings
$arcInstance.Setting.AdditionalProperties | Add-Member -Name 'AzureAD' -Value $aadSettings -MemberType NoteProperty
}
Write-Host "Writing Microsoft Entra setting to SQL Server Arc Extension. This may take several minutes..."
# Push settings to Arc
#
try
{
Update-AzConnectedMachineExtension -MachineName $machineName -Name "WindowsAgent.SqlServer" -ResourceGroupName $resourceGroupName -Setting $arcInstance.Setting
}
catch
{
Write-Error $_
Write-Error "Failed to write settings to Arc host"
exit 1
}
Write-Output "Success"
Templat ARM berikut menyiapkan admin Microsoft Entra menggunakan sertifikat Azure Key Vault dan aplikasi Microsoft Entra yang sudah ada.
Parameter input berikut digunakan untuk templat ARM:
<machineName> - Nama mesin host SQL Server Anda
<Location> - Lokasi SQL Server Anda – grup sumber daya Azure Arc , seperti West US, atau Central US
<instanceName> - Nama instans SQL Server. Nama instans default SQL Server adalah MSSQLSERVER
<certSubjectName> - Nama sertifikat yang Anda buat
<subscriptionId> - ID Langganan. ID langganan Anda dapat ditemukan di portal Microsoft Azure
<resourceGroupName> - Nama grup sumber daya yang berisi brankas kunci Anda. Nilai azureKeyVaultResourceUID lengkap dapat ditemukan dengan masuk ke sumber daya Key vault Anda, memilih Properti dan menyalin ID Sumber Daya
<keyVaultName> - Nama brankas kunci Anda
<certIdentifier>- Pengidentifikasi Sertifikat untuk sertifikat Azure Key Vault Anda. Untuk mendapatkan Pengidentifikasi Sertifikat, buka sumber daya Brankas kunci Anda, dan pilih Sertifikat di bawah Pengaturan. Pilih versi sertifikat saat ini yang Anda buat, dan salin nilai Pengidentifikasi Sertifikat. Untuk informasi selengkapnya, lihat Menambahkan sertifikat ke Key Vault
<certSecret>- Pengidentifikasi Rahasia sertifikat Anda, dan dapat ditemukan di menu yang sama dengan Pengidentifikasi Sertifikat
Setelah admin Microsoft Entra disiapkan, menggunakan kredensial admin Microsoft Entra memungkinkan Anda menyambungkan ke SQL Server. Namun, setiap aktivitas database lebih lanjut yang melibatkan pembuatan login Microsoft Entra baru dan pengguna akan gagal sampai persetujuan admin diberikan ke aplikasi Microsoft Entra.
Catatan
Untuk memberikan persetujuan Admin untuk aplikasi, akun yang memberikan persetujuan memerlukan peran Administrator Global ID Microsoft Entra atau Administrator Peran Istimewa. Peran ini diperlukan untuk memberikan persetujuan admin untuk aplikasi, tetapi tidak perlu menyiapkan admin Microsoft Entra.
Di portal Azure, pilih MICROSOFT Entra ID> Pendaftaran aplikasi, pilih aplikasi yang baru dibuat. Aplikasi harus memiliki nama seperti <hostname>-<instanceName><uniqueNumber>.
Pilih menu izin API.
Pilih Berikan perizinan admin.
Tanpa memberikan persetujuan admin ke aplikasi, membuat login Microsoft Entra atau pengguna di SQL Server akan mengakibatkan kesalahan berikut:
Msg 37455, Level 16, State 1, Line 2
Server identity does not have permissions to access MS Graph.
Menggunakan autentikasi Microsoft Entra untuk menyambungkan ke SQL Server
Autentikasi Microsoft Entra sekarang disiapkan untuk SQL Server Anda yang tersambung ke Azure Arc. Ikuti bagian setelah menyiapkan admin Microsoft Entra dalam artikel, Tutorial: Menyiapkan autentikasi Microsoft Entra untuk SQL Server untuk menyambungkan ke SQL Server menggunakan autentikasi Microsoft Entra.