Tutorial: Verwenden der Automatisierung zum Einrichten des*der Microsoft Entra-Administrators*Administratorin für SQL Server
Artikel
Gilt für: SQL Server 2022 (16.x)
Hinweis
Dieses Feature ist in SQL Server 2022 (16.x) oder höheren Versionen verfügbar und wird nur für lokale SQL Server-Server für Windows- und Linux-Hosts und SQL Server 2022 auf Windows Azure-VMs unterstützt.
In diesem Artikel erfahren Sie, wie Sie den Microsoft Entra-Administrator einrichten, um die Authentifizierung mit Microsoft Entra ID (vormals Azure Active Directory) für SQL Server mithilfe der Azure-Portal und APIs wie:
Während Microsoft Entra-ID der neue Name für Azure Active Directory (Azure AD) ist, bleibt Azure AD in einigen fest kodierten Elementen wie Benutzeroberfläche-Feldern, Verbindungsanbietern, Fehlercodes und Cmdlets erhalten, um Störungen in bestehenden Umgebungen zu vermeiden. In diesem Artikel sind die beiden Namen austauschbar.
Voraussetzungen
SQL Server 2022 (16.x) oder höher ist installiert.
Vorbereitung vor dem Festlegen des Microsoft Entra-Administrators
Die folgenden Berechtigungen sind erforderlich, um den Microsoft Entra-Administrator in sql Server – Azure Arc - und Key Vault-Ressourcen einzurichten.
Konfigurieren von Berechtigungen für Azure Arc
Befolgen Sie den Leitfaden, um sicherzustellen, dass Ihr SQL Server mit Azure Arc verbunden ist. Der Benutzer, der Microsoft Entra-Administrator für sql Server – Azure Arc-Ressource eingerichtet hat, sollte über die Rolle "Mitwirkender " für den Server verfügen.
Wählen Sie SQL Server – Azure Arc aus, und wählen Sie die Instanz für Ihren SQL Server-Host aus.
Wählen Sie Zugriffssteuerung (IAM) aus.
Wählen Sie "Rollenzuweisung hinzufügen">aus, um dem Benutzer, der den Microsoft Entra-Administrator eingerichtet hat, die Rolle "Mitwirkender" hinzuzufügen.
Konfigurieren von Berechtigungen für Azure Key Vault
Erstellen Sie einen Azure Key Vault , wenn Sie noch keinen haben. Der Benutzer, der Microsoft Entra-Administrator einnimmt, sollte über die Rolle "Mitwirkender " für Ihren Azure Key Vault verfügen. So fügen Sie einem Benutzer in Azure Key Vault eine Rolle hinzu:
Wählen Sie "Rollenzuweisung hinzufügen">aus, um dem Benutzer, der den Microsoft Entra-Administrator eingerichtet hat, die Rolle "Mitwirkender" hinzuzufügen.
Festlegen von Zugriffsrichtlinien für den SQL Server-Host
Navigieren Sie im Azure-Portal zu Ihrer Azure Key Vault-Instanz, und wählen Sie Zugriffsrichtlinien aus.
Wählen Sie Zugriffsrichtlinie hinzufügen aus.
Verwenden Sie für Schlüsselberechtigungen "Sign".
Wählen Sie für die Geheimnisberechtigungen die Optionen Get und List aus.
Wählen Sie für Zertifikatberechtigungen "Abrufen" und "Liste" aus.
Wählen Sie Weiter aus.
Suchen Sie auf der Hauptseite nach dem Namen Ihres Computers – Azure Arc-Instanz, die den Hostnamen des SQL Server-Hosts darstellt.
Überspringen Sie die Seite "Anwendung (optional)", indem Sie "Weiter" zweimal auswählen oder "Überprüfen + Erstellen" auswählen.
Stellen Sie sicher, dass die "Objekt-ID" des Prinzipals mit der Prinzipal-ID der verwalteten Identität übereinstimmt, die der Instanz zugewiesen ist.
Um dies zu bestätigen, wechseln Sie zur Ressourcenseite, und wählen Sie oben rechts im Feld "Essentials" auf der Seite "Übersicht" die JSON-Ansicht aus. Unter "Identität " finden Sie die PrincipalId.
Klicken Sie auf Erstellen.
Sie müssen "Erstellen" auswählen, um sicherzustellen, dass die Berechtigungen angewendet werden. Um sicherzustellen, dass Berechtigungen gespeichert wurden, aktualisieren Sie das Browserfenster, und überprüfen Sie, ob die Zeile für Ihre Azure Arc-Instanz noch vorhanden ist.
Festlegen von Zugriffsrichtlinien für Microsoft Entra-Benutzer
Navigieren Sie im Azure-Portal zu Ihrer Azure Key Vault-Instanz, und wählen Sie Zugriffsrichtlinien aus.
Wählen Sie Zugriffsrichtlinie hinzufügen aus.
Wählen Sie für Schlüsselberechtigungen "Abrufen", "Liste" und "Erstellen" aus.
Wählen Sie für "Geheime Berechtigungen" die Option "Abrufen", "Auflisten" und "Festlegen" aus.
Wählen Sie für Zertifikatberechtigungen "Abrufen", "Liste" und "Erstellen" aus.
Fügen Sie für den Select-Prinzipal den Microsoft Entra-Benutzer hinzu, den Sie zum Herstellen einer Verbindung mit SQL Server verwenden möchten.
Klicken Sie auf Hinzufügen und dann auf Speichern.
Einrichten des Microsoft Entra-Administrators für SQL Server
Mit neuen APIs und Portalfunktionen können Benutzer einen Microsoft Entra-Administrator für SQL Server einrichten, ohne ein Azure-Zertifikat und eine Microsoft Entra-Anwendung separat erstellen zu müssen. Wählen Sie eine Registerkarte aus, um zu erfahren, wie Sie einen Microsoft Entra-Administrator für Ihren SQL Server einrichten, der mit Azure Arc verbunden ist, mit automatischer Zertifikat- und Anwendungserstellung.
Hinweis
Die ARM-Vorlage erfordert weiterhin die Erstellung eines Azure Key Vault-Zertifikats und einer Microsoft Entra-Anwendung, bevor Sie einen Microsoft Entra-Administrator einrichten. Weitere Informationen zu diesem Prozess finden Sie im Lernprogramm: Einrichten der Microsoft Entra-Authentifizierung für SQL Server.
Verwenden Sie die Azure-Portal, um einen Microsoft Entra-Administrator einzurichten, erstellen Sie ein Azure Key Vault-Zertifikat und eine Microsoft Entra-Anwendung im selben Prozess. Dies ist erforderlich, um die Microsoft Entra-Authentifizierung mit SQL Server zu verwenden.
Einrichten des Microsoft Entra-Administrators mithilfe der Azure-Portal
Wechseln Sie zum Azure-Portal, und wählen Sie SQL Server – Azure Arc aus. Wählen Sie die Instanz für Ihren SQL Server-Host aus.
Überprüfen Sie den Status Ihrer SQL Server – Azure Arc-Ressource, und testen Sie deren Verbindung, indem Sie zum Menü Eigenschaften navigieren. Weitere Informationen finden Sie unter Validate your Arc-enabled SQL Server resources.
Wählen Sie microsoft Entra ID und Purview unter Einstellungen aus dem Ressourcenmenü aus.
Wählen Sie "Administrator festlegen" aus, um den Bereich "Microsoft Entra ID " zu öffnen, und wählen Sie ein Konto aus, das als Administratoranmeldung bei SQL Server hinzugefügt wird.
Wählen Sie das vom Dienst verwaltete Zertifikat aus.
Wählen Sie "Schlüsseltresor ändern" und dann Ihre vorhandene Azure Key Vault-Ressource aus.
Wählen Sie die Dienstverwaltete App-Registrierung aus.
Wählen Sie Speichern. Dadurch wird eine Anforderung an den Arc-Server-Agent gesendet, der die Microsoft Entra-Authentifizierung für diese SQL Server-Instanz konfiguriert. Der Vorgang kann mehrere Minuten dauern; Warten Sie, bis der Speichervorgang bestätigt Saved successfully wurde, bevor Sie eine Microsoft Entra-Anmeldung versuchen.
Die dienstverwaltete App-Registrierung führt folgendes für Sie aus:
Erstellt ein Zertifikat im Schlüsseltresor mit einem Namen im Formular <hostname>-<instanceName><uniqueNumber>.
Erstellt eine Microsoft Entra-Anwendung mit einem Namen wie <hostname>-<instanceName><uniqueNumber>, und weist dieser Anwendung die erforderlichen Berechtigungen zu. Weitere Informationen finden Sie unter Erteilen von Anwendungsberechtigungen
Weist das neue Zertifikat im Azure Key Vault der Anwendung zu.
Speichert diese Einstellungen in Azure Arc.
Hinweis
Die für Microsoft Entra erstellten Zertifikate werden nicht automatisch gedreht. Kunden können ein eigenes Zertifikat und eine eigene Anwendung für das Microsoft Entra-Administratorsetup bereitstellen. Weitere Informationen finden Sie im Lernprogramm: Einrichten der Microsoft Entra-Authentifizierung für SQL Server.
Az.Verbinden edMachine 0.5.1 oder höher ist erforderlich.
Verwenden Sie az extension add --name ConnectedMachinezum Installieren des Moduls Az.ConnectedMachine . Verwenden Sie die Verwendung az version, um zu überprüfen, welche Version der Azure CLI installiert ist.
Die folgenden Eingabeparameter werden für das Azure CLI-Skript verwendet:
<applicationName> - Anwendungsname, der erstellt wird
<certSubjectName> – Zertifikatname, der erstellt wird
<keyVaultName> - Ihr Schlüsseltresorname. Dieser Schlüsseltresor muss erstellt werden, bevor das Skript ausgeführt wird.
<machineName> - Computername Ihres SQL Server-Hosts
<resourceGroupName>– Ressourcengruppenname, der Ihren SQL Server enthält – Azure Arc-Instanz
<adminAccountName> – Microsoft Entra-Administratorkonto, das Sie für Ihren SQL Server festlegen möchten
<instanceName> - Optionaler Parameter für benannte SQL Server-Instanzen. Verwenden Sie diesen Parameter, wenn Sie über eine benannte Instanz verfügen. Wenn dieser Wert nicht angegeben wird, wird der Standardname MSSQLSERVER verwendet.
<tenantId> - Optionaler Parameter für die Mandanten-ID. Die Mandanten-ID finden Sie, indem Sie zur Azure-Portal wechseln und zu Ihrer Microsoft Entra ID-Ressource wechseln. Im Bereich Übersicht sollte die Mandanten-ID angezeigt werden. Wenn sie weggelassen wird, wird die Standardmandanten-ID als Parameter verwendet.
<subscriptionId> - Optionaler Parameter für die Abonnement-ID. Ihre Abonnement-ID finden Sie im Azure-Portal. Wenn dies nicht angegeben wird, wird die Standardabonnement-ID verwendet.
Um das folgende Azure CLI-Skript zu verwenden, speichern Sie das Skript als .ps1 Datei, und führen Sie den folgenden Befehl aus:
Ersetzen Sie WindowsAgent.SqlServerLinuxAgent.SqlServer für SQL Server für Linux Hostcomputer durch das Skript.
# 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"
Das Ausführen des Skripts kann mehrere Minuten dauern. Wenn der Prozess abgeschlossen ist, wird eine Meldung wie folgt angezeigt:
Name Location ProvisioningState
---- -------- -----------------
WindowsAgent.SqlServer westus2 Succeeded
Success
Einrichten eines Microsoft Entra-Administrators mit vorhandenem Zertifikat und einer vorhandenen Anwendung mithilfe der Azure CLI
Wenn Sie bereits über ein Azure Key Vault-Zertifikat verfügen und eine Azure-Anwendung, die Sie zum Einrichten eines Microsoft Entra-Administrators verwenden möchten, können Sie das folgende CLI-Skript verwenden:
# 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"
Die für das Microsoft Entra-Setup erstellten Zertifikate werden nicht automatisch gedreht.
Für dieses Lernprogramm sind die folgenden Module erforderlich. Installieren Sie die neuesten Versionen der Module oder höher als die unten aufgeführte Version:
Az.Accounts 3.37.0
Az.Verbinden edMachine 0.5.0
Az.KeyVault 4.5.0
Az.Resources 6.0.0
Die folgenden Eingabeparameter werden für das PowerShell-Skript verwendet:
<applicationName> - Anwendungsname, der erstellt wird
<certSubjectName> – Zertifikatname, der erstellt wird
<keyVaultName> - Ihr Schlüsseltresorname. Dieser Schlüsseltresor muss erstellt werden, bevor das Skript ausgeführt wird.
<machineName> - Computername Ihres SQL Server-Hosts
<resourceGroupName>– Ressourcengruppenname, der Ihren SQL Server enthält – Azure Arc-Instanz
<adminAccountName> – Microsoft Entra-Administratorkonto, das Sie für Ihren SQL Server festlegen möchten
<instanceName> - Optionaler Parameter für benannte SQL Server-Instanzen. Verwenden Sie diesen Parameter, wenn Sie über eine benannte Instanz verfügen. Wenn dieser Wert nicht angegeben wird, wird der Standardname MSSQLSERVER verwendet.
<tenantId> - Optionaler Parameter für die Mandanten-ID. Die Mandanten-ID finden Sie, indem Sie zur Azure-Portal wechseln und zu Ihrer Microsoft Entra ID-Ressource wechseln. Im Bereich Übersicht sollte die Mandanten-ID angezeigt werden. Wenn sie weggelassen wird, wird die Standardmandanten-ID als Parameter verwendet.
<subscriptionId> - Optionaler Parameter für die Abonnement-ID. Ihre Abonnement-ID finden Sie im Azure-Portal. Wenn dies nicht angegeben wird, wird die Standardabonnement-ID verwendet.
Um das folgende PowerShell-Skript zu verwenden, speichern Sie das Skript als .ps1 Datei, und führen Sie den folgenden Befehl aus:
Ersetzen Sie WindowsAgent.SqlServerLinuxAgent.SqlServer für SQL Server für Linux Hostcomputer durch das Skript.
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"
Einrichten eines Microsoft Entra-Administrators mit vorhandenem Zertifikat und einer vorhandenen Anwendung mithilfe von PowerShell
Wenn Sie bereits über ein Azure Key Vault-Zertifikat und eine Azure-Anwendung verfügen, die Sie zum Einrichten eines Microsoft Entra-Administrators verwenden möchten, können Sie das folgende PowerShell-Skript verwenden:
# 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"
Die folgende ARM-Vorlage richtet einen Microsoft Entra-Administrator mithilfe eines vorhandenen Azure Key Vault-Zertifikats und einer Microsoft Entra-Anwendung ein.
Die folgenden Eingabeparameter werden für die ARM-Vorlage verwendet:
<machineName> - Computername Ihres SQL Server-Hosts
<Location> – Speicherort Ihres SQL Server – Azure Arc-Ressourcengruppe , z West US. B. , oder Central US
<tenantId>– Die Mandanten-ID kann gefunden werden, indem Sie zur Azure-Portal wechseln und zu Ihrer Microsoft Entra ID-Ressource wechseln. Im Bereich Übersicht sollte Ihre Mandanten-ID angezeigt werden.
<instanceName> - SQL Server-Instanzname. Der Standardinstanzname von SQL Server ist MSSQLSERVER
<certSubjectName> – Zertifikatname, den Sie erstellt haben
<subscriptionId> – Abonnement-ID. Ihre Abonnement-ID können Sie über das Azure-Portal ermitteln.
<resourceGroupName> – Ressourcengruppenname, der Ihren Schlüsseltresor enthält. Der vollständige AzureKeyVaultResourceUID-Wert wird gefunden, indem Sie zu Ihrer Key Vault-Ressource wechseln, Eigenschaften auswählen und Ressourcen-ID kopieren
<keyVaultName> - Ihr Schlüsseltresorname
<certIdentifier> – Der Zertifikatbezeichner für Ihr Azure Key Vault-Zertifikat. Um den Zertifikatbezeichner zu erhalten, wechseln Sie zu Ihrer Schlüsseltresorressource, und wählen Sie "Zertifikate" unter Einstellungen aus. Wählen Sie die aktuelle Version des von Ihnen erstellten Zertifikats aus, und kopieren Sie den Zertifikatbezeichnerwert . Weitere Informationen finden Sie unter Hinzufügen eines Zertifikats zum Key Vault
<certSecret> - Der geheime Bezeichner Ihres Zertifikats und befindet sich im selben Menü wie der Zertifikatbezeichner.
<adminType> – Verwendung 0 für Microsoft Entra-Benutzer und -Anwendungen und 1 für Microsoft Entra-Gruppen
Verwenden Sie eine benutzerdefinierte Bereitstellung im Azure-Portal, und erstellen Sie im Editor Ihre eigene Vorlage. Speichern Sie als Nächstes die Konfiguration, nachdem Sie das Beispiel eingefügt haben.
Hinweis
Ersetzen Sie WindowsAgent.SqlServerLinuxAgent.SqlServer für SQL Server für Linux Hostcomputer durch das Skript.
Erteilen der Administratorzustimmung für die Anwendung
Nachdem der Microsoft Entra-Administrator eingerichtet wurde, können Sie mithilfe der Microsoft Entra-Administratoranmeldeinformationen eine Verbindung mit SQL Server herstellen. Alle weiteren Datenbankaktivitäten, die das Erstellen neuer Microsoft Entra-Anmeldungen und Benutzer betreffen, schlagen jedoch fehl, bis der Microsoft Entra-Anwendung die Administratorzustimmung erteilt wird.
Hinweis
Zum Erteilen der Administratorzustimmung für die Anwendung erfordert das Konto, das die Zustimmung erteilt, eine Rolle des globalen Microsoft Entra ID- oder Privileged Role Administrators. Diese Rollen sind erforderlich, um der Anwendung Administratorzustimmung zu erteilen, ist jedoch nicht erforderlich, um den Microsoft Entra-Administrator einzurichten.
Wählen Sie im Azure-Portal die Microsoft Entra-ID> aus App-Registrierungen die neu erstellte Anwendung aus. Die Anwendung sollte einen Namen wie <hostname>-<instanceName><uniqueNumber>.
Wählen Sie das Menü "API-Berechtigungen" aus .
Wählen Sie Administratoreinwilligung erteilen aus.
Ohne Administratorzustimmung für die Anwendung zu erteilen, führt das Erstellen einer Microsoft Entra-Anmeldung oder eines Benutzers in SQL Server zu folgendem Fehler:
Msg 37455, Level 16, State 1, Line 2
Server identity does not have permissions to access MS Graph.
Verwenden der Microsoft Entra-Authentifizierung zum Herstellen einer Verbindung mit SQL Server
Die Microsoft Entra-Authentifizierung ist jetzt für Ihren SQL Server eingerichtet, der mit Azure Arc verbunden ist. Folgen Sie den Abschnitten nach dem Einrichten des Microsoft Entra-Administrators im Artikel Lernprogramm : Einrichten der Microsoft Entra-Authentifizierung für SQL Server zum Herstellen einer Verbindung mit SQL Server mithilfe der Microsoft Entra-Authentifizierung.
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
SQL Server 2022 (16.x)
