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 SQL Server on-premises, 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 zu ermöglichen (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 Microsoft Entra admin in den Ressourcen SQL Server – Azure Arc und Key vault einzurichten.
Konfigurieren von Berechtigungen für Azure Arc
Befolgen Sie die Anleitung, um sicherzustellen, dass Ihr SQL Server mit Azure Arc verbunden ist. Der Benutzer, der Microsoft Entra admin für die Ressource SQL Server – Azure Arc einrichtet, sollte die Rolle Mitwirkender für den Server haben.
Wählen Sie SQL Server – Azure Arc, und wählen Sie die Instanz für Ihren SQL Server-Host.
Wählen Sie Zugriffssteuerung (IAM) aus.
Wählen Sie Hinzufügen>Rollenzuweisung hinzufügen, um dem Benutzer, der den Microsoft Entra-Admin einrichtet, die Mitwirkender-Rolle hinzuzufügen.
Konfigurieren von Berechtigungen für Azure Key Vault
Erstellen Sie einen Azure Key Vault, wenn Sie noch keinen haben. Der Benutzer bzw. die Benutzerin, der bzw. die den Azure AD-Administrator bzw. die Microsoft Entra-Administratorin einrichtet, muss für Ihren Azure Key Vault über die Rolle Mitwirkender verfügen. So fügen Sie einem Benutzer in Azure Key Vault eine Rolle hinzu:
Wählen Sie Hinzufügen>Rollenzuweisung hinzufügen, um dem Benutzer, der den Microsoft Entra-Admin einrichtet, die Mitwirkender-Rolle 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.
Für Schlüsselberechtigungen verwenden Sie Unterschreiben.
Wählen Sie für die Geheimnisberechtigungen die Optionen Get und List aus.
Wählen Sie für ZertifikatsberechtigungenAbrufen und Liste aus.
Wählen Sie Weiter aus.
Suchen Sie auf der Seite Prinzipal den Namen der Azure Arc-Instanz Ihres Computers, der dem Hostnamen des SQL Server-Hosts entspricht.
Überspringen Sie die Seite Anwendung (optional) indem Sie zweimal auf Weiter klicken, oder Prüfen und 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 in der Übersicht die JSON-Ansicht aus. Unter Identität finden Sie die principalId.
Klicken Sie auf Erstellen.
Sie müssen auf Erstellen klicken, 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 die 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üsselberechtigungenAbrufen, Auflisten und Erstellen.
Wählen Sie für die Geheimnisberechtigungen die Optionen Abrufen, Auflisten und Festlegen.
Wählen Sie für ZertifikatsberechtigungenAbrufen, Auflisten und Erstellen aus.
Fügen Sie für Prinzipal auswählen 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 Tutorial: Einrichten der Microsoft Entra-Authentifizierung für SQL Server.
Verwenden Sie das 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 des Azure-Portals
Wechseln Sie zum Azure-Portal, klicken Sie auf SQL Server – Azure Arc, und 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 Überprüfen der „SQL Server – Azure Arc“-Ressourcen.
Wählen Sie im Ressourcenmenü unter Einstellungen die Option Microsoft Entra ID und Purview aus.
Wählen Sie Administrator festlegen, um den Bereich Microsoft Entra ID zu öffnen, und wählen Sie ein Konto, das als Admin-Anmeldung zu SQL Server hinzugefügt wird.
Wählen Sie Dienstverwaltetes Zertifikat aus.
Wählen Sie Schlüsseltresor ändern und wählen Sie Ihre vorhandene Azure Key Vault-Ressource aus.
Wählen Sie Vom Dienst verwaltete App-Registrierung.
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 mit Saved successfully bestätigt 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 Erteilung 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 unter Tutorial: Microsoft Entra-Authentifizierung für SQL Server einrichten.
Die für das Microsoft Entra-Setup erstellten Zertifikate werden nicht automatisch gedreht.
Die Azure CLI Version 2.37.0 oder höher ist erforderlich
Az.ConnectedMachine 0.5.1 oder höher ist erforderlich
Verwenden Sie Az.ConnectedMachine, um das az extension add --name ConnectedMachine Modul zu installieren. Verwenden Sie 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> - Der Name Ihres Schlüsseltresors Dieser Schlüsseltresor muss erstellt werden, bevor das Skript ausgeführt wird.
<machineName> - Computername Ihres SQL Server-Hosts
<resourceGroupName> - Ressourcengruppenname, der Ihre SQL Server – Azure Arc Instanz enthält
<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 nichts angeben wird, wird der Standardname MSSQLSERVER verwendet.
<tenantId> - Optionaler Parameter für die Mandanten-ID. Die Mandanten-ID finden Sie, indem Sie zum Azure-Portal und dann zu Ihrer Microsoft Entra ID-Ressource navigieren. 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 können Sie über das Azure-Portal ermitteln. 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:
Für SQL Server auf Linux-Hostcomputern ersetzen Sie im Skript WindowsAgent.SqlServer mit LinuxAgent.SqlServer.
# 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"
Die Ausführung 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 Tutorial benötigen Sie folgende Module: Installieren Sie die neuesten Versionen der Module oder höher als die unten aufgeführte Version:
Az.Accounts 3.37.0
Az.ConnectedMachine 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> - Der Name Ihres Schlüsseltresors Dieser Schlüsseltresor muss erstellt werden, bevor das Skript ausgeführt wird.
<machineName> - Computername Ihres SQL Server-Hosts
<resourceGroupName> - Ressourcengruppenname, der Ihre SQL Server – Azure Arc Instanz enthält
<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 nichts angeben wird, wird der Standardname MSSQLSERVER verwendet.
<tenantId> - Optionaler Parameter für die Mandanten-ID. Die Mandanten-ID finden Sie, indem Sie zum Azure-Portal und dann zu Ihrer Microsoft Entra ID-Ressource navigieren. 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 können Sie über das Azure-Portal ermitteln. 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:
Für SQL Server auf Linux-Hostcomputern ersetzen Sie im Skript WindowsAgent.SqlServer mit LinuxAgent.SqlServer.
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 Ihrer SQL Server – Azure Arc-Ressourcengruppe , z. B. West US, oder Central US
<tenantId> - Die Mandanten-ID finden Sie, indem Sie zum Azure-Portal und dann zu Ihrer Microsoft Entra ID-Ressource navigieren. Im Bereich Übersicht sollte Ihre Mandanten-ID angezeigt werden.
<instanceName> - SQL Server Instanzname Der Standardinstanzname von SQL Server lautet MSSQLSERVER
<certSubjectName> - Zertifikatname, den Sie erstellt haben
<subscriptionId> - Abonnement-ID. Ihre Abonnement-ID können Sie über das Azure-Portal ermitteln.
<resourceGroupName> - Ressourcengruppenname, in dem sich Ihr Schlüsseltresor befindet. Der vollständige AzureKeyVaultResourceUID-Wert wird gefunden, indem Sie zu Ihrer Key Vault-Ressource wechseln, Eigenschaften auswählen und Ressourcen-ID kopieren
<keyVaultName> - Der Name Ihres Schlüsseltresors
<certIdentifier> - Der Zertifikatsbezeichner für Ihr Azure Key Vault-Zertifikat. Um den Zertifikatbezeichner zu erhalten, wechseln Sie zu Ihrer Schlüsseltresor-Ressource, und wählen Sie Zertifikate unter Einstellungen aus. Wählen Sie die aktuelle Version des von Ihnen erstellten Zertifikats aus, und kopieren Sie den Zertifikatbezeichner-Wert. Weitere Informationen finden Sie unter Hinzufügen eines Zertifikats in Key Vault.
<certSecret> - Der geheime Bezeichner Ihres Zertifikats und befindet sich im selben Menü wie der Zertifikatbezeichner
<adminType> – Verwenden Sie 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
Für SQL Server auf Linux-Hostcomputern ersetzen Sie im Skript WindowsAgent.SqlServer mit LinuxAgent.SqlServer.
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 Administratoreinwilligung erteilt wird.
Hinweis
Um die Administratoreinwilligung für die Anwendung zu erteilen, benötigt das Konto, das die Zustimmung erteilt, die Rolle Microsoft Entra ID Globaler Administrator oder Administrator für privilegierte Rollen. Diese Rollen sind erforderlich, um der Anwendung Administratoreinwilligung 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> haben.
Wählen Sie das Menü API-Berechtigungen aus.
Wählen Sie Administratoreinwilligung erteilen aus.
Ohne Administratoreinwilligung 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.
Herstellen einer Verbindung mit SQL Server mithilfe der Microsoft Entra-Authentifizierung
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 Tutorial: Einrichten der Microsoft Entra-Authentifizierung für SQL Server zum Herstellen einer Verbindung mit SQL Server mithilfe der Microsoft Entra-Authentifizierung.
SQL Server 2022 (16.x)
