Verwenden von JEAUsing JEA

In diesem Artikel werden die verschiedenen Möglichkeiten beschrieben, um eine Verbindung mit einem JEA-Endpunkt herzustellen und ihn zu verwenden.This article describes the various ways you can connect to and use a JEA endpoint.

Interaktives Verwenden von JEAUsing JEA interactively

Wenn Sie Ihre JEA-Konfiguration testen oder über einfache Aufgaben für Benutzer verfügen, können Sie JEA wie eine normale PowerShell-Remotingsitzung verwenden.If you're testing your JEA configuration or have simple tasks for users, you can use JEA the same way you would a regular PowerShell remoting session. Für komplexe Remotingaufgaben wird das implizite Remoting empfohlen.For complex remoting tasks, it's recommended to use implicit remoting. Damit können Benutzer die Datenobjekte lokal ausführen.Implicit remoting allows users to operate with the data objects locally.

Wenn Sie JEA interaktiv verwenden möchten, benötigen Sie Folgendes:To use JEA interactively, you need:

  • Name des Computers, mit dem Sie eine Verbindung herstellen (möglicherweise der lokale Computer)The name of the computer you're connecting to (can be the local machine)
  • der Name des auf diesem Computer registrierten JEA-EndpunktsThe name of the JEA endpoint registered on that computer
  • Anmeldeinformationen mit Zugriff auf den JEA-Endpunkt auf diesem ComputerCredentials that have access to the JEA endpoint on that computer

Anhand dieser Informationen können Sie eine JEA-Sitzung über die Cmdlets New-PSSession oder Enter-PSSession starten.Given that information, you can start a JEA session using the New-PSSession or Enter-PSSession cmdlets.

$nonAdminCred = Get-Credential
Enter-PSSession -ComputerName localhost -ConfigurationName JEAMaintenance -Credential $nonAdminCred

Wenn das aktuelle Benutzerkonto Zugriff auf den JEA-Endpunkt besitzt, können Sie den Parameter Credential auslassen.If the current user account has access to the JEA endpoint, you can omit the Credential parameter.

Wenn sich die PowerShell-Aufforderung in [localhost]: PS> ändert, wissen Sie, dass Sie ab jetzt mit der JEA-Remotesitzung interagieren.When the PowerShell prompt changes to [localhost]: PS> you know that you're now interacting with the remote JEA session. Sie können Get-Command ausführen, um zu überprüfen, welche Befehle verfügbar sind.You can run Get-Command to check which commands are available. Wenden Sie sich an Ihren Administrator, um zu erfahren, ob für die verfügbaren Parameter oder zulässigen Parameterwerte Einschränkungen gelten.Consult with your administrator to learn if there are any restrictions on the available parameters or allowed parameter values.

Bedenken Sie, dass JEA-Sitzungen im Modus „NoLanguage“ ausgeführt werden.Remember, JEA sessions operate in NoLanguage mode. Einige ihrer üblichen Verwendungsmöglichkeiten in PowerShell sind möglicherweise nicht verfügbar.Some of the ways you typically use PowerShell may not be available. Beispielsweise können Sie keine Variablen zum Speichern von Daten nutzen oder die Eigenschaften der von Cmdlets zurückgegebenen Objekte überprüfen.For instance, you can't use variables to store data or inspect the properties on objects returned from cmdlets. Das folgende Beispiel enthält zwei Ansätze für die Ausführung derselben Befehle im Modus „NoLanguage“:The following example shows two approaches to get the same commands to work in NoLanguage mode.

# Using variables is prohibited in NoLanguage mode. The following will not work:
# $vm = Get-VM -Name 'SQL01'
# Start-VM -VM $vm

# You can use pipes to pass data through to commands that accept input from the pipeline
Get-VM -Name 'SQL01' | Start-VM

# You can also wrap subcommands in parentheses and enter them inline as arguments
Start-VM -VM (Get-VM -Name 'SQL01')

# You can also use parameter sets that don't require extra data to be passed in
Start-VM -VMName 'SQL01'

Für komplexere Befehlsaufrufe, die mit diesem Ansatz nur schwer möglich sind, sollten Sie implizites Remoting oder das Erstellen von benutzerdefinierten Funktionen in Erwägung ziehen, um die benötigten Funktionen nutzen zu können.For more complex command invocations that make this approach difficult, consider using implicit remoting or creating custom functions that wrap the functionality you require.

Verwenden von JEA mit implizitem RemotingUsing JEA with implicit remoting

PowerShell bietet ein implizites Remotingmodell, bei dem Sie Proxy-Cmdlets von einem Remotecomputer importieren und damit interagieren können, als wären es lokale Befehle.PowerShell has an implicit remoting model that lets you import proxy cmdlets from a remote machine and interact with them as if they were local commands. Weitere Informationen zum impliziten Remoting finden Sie in diesem Blogbeitrag vonImplicit remoting is explained in this Hey, Scripting Guy! Hey, Scripting Guy!.blog post. Implizites Remoting ist für die Arbeit mit JEA geeignet, da Sie auf diese Weise mit JEA-Cmdlets im Modus „FullLanguage“ arbeiten können.Implicit remoting is useful when working with JEA because it allows you to work with JEA cmdlets in a full language mode. Dabei können Sie die Vervollständigung mit der TAB-TASTE und Variablen nutzen, Objekte bearbeiten und sogar lokale Skripts verwenden, um Aufgaben für einen JEA-Endpunkt zu automatisieren.You can use tab completion, variables, manipulate objects, and even use local scripts to automate tasks against a JEA endpoint. Jedes Mal, wenn Sie einen Proxybefehl aufrufen, werden die Daten an den JEA-Endpunkt auf dem Remotecomputer gesendet und dort ausgeführt.Anytime you invoke a proxy command, the data is sent to the JEA endpoint on the remote machine and executed there.

Mithilfe von implizitem Remoting können Sie Cmdlets aus einer vorhandenen PowerShell-Sitzung importieren.Implicit remoting works by importing cmdlets from an existing PowerShell session. Sie können optional den Namen der einzelnen Proxy-Cmdlets eine Zeichenfolge Ihrer Wahl vorausstellen.You can optionally choose to prefix the nouns of each proxy cmdlet with a string of your choosing. Mit diesem Präfix können Sie die Befehle hervorheben, die zum Remotesystem gehören.The prefix allows you to distinguish the commands that are for the remote system. Ein temporäres Skriptmodul mit allen Proxybefehlen wird erstellt und für die Dauer Ihrer lokalen PowerShell-Sitzung importiert.A temporary script module containing all the proxy commands is created and imported for the duration of your local PowerShell session.

# Create a new PSSession to your JEA endpoint
$jeasession = New-PSSession -ComputerName 'SERVER01' -ConfigurationName 'JEAMaintenance'

# Import the entire PSSession and prefix each imported cmdlet with "JEA"
Import-PSSession -Session $jeasession -Prefix 'JEA'

# Invoke "Get-Command" on the remote JEA endpoint using the proxy cmdlet
Get-JEACommand

Wichtig

Einige Systeme können möglicherweise aufgrund von Einschränkungen in den Standard-JEA-Cmdlets keine vollständige JEA-Sitzung importieren.Some systems may not be able to import an entire JEA session due to constraints in the default JEA cmdlets. Dies können Sie umgehen, indem Sie nur die von Ihnen benötigten Befehle aus der JEA-Sitzung importieren und ihre Namen explizit für den -CommandName Parameter angeben.To get around this, only import the commands you need from the JEA session by explicitly providing their names to the -CommandName parameter. Ein zukünftiges Update wird dieses Problem berücksichtigen und die vollständigen JEA-Sitzungen auf den betroffenen Systemen importieren.A future update will address the issue with importing entire JEA sessions on affected systems.

Wenn Sie aufgrund von JEA-Einschränkungen für die Standardparameter keine JEA-Sitzung importieren können, führen Sie die nachfolgenden Schritte aus, um die Standardbefehle aus dem importierten Satz herauszufiltern.If you're unable to import a JEA session because of JEA constraints on the default parameters, follow the steps below to filter out the default commands from the imported set. Sie können weiterhin Befehle wie Select-Object ausführen, verwenden dabei aber nur die auf Ihrem Computer installierte lokale Version anstelle der importierten Version der JEA-Remotesitzung.You can continue use commands like Select-Object, but you'll just use the local version installed on your computer instead of the one imported from the remote JEA session.

# Create a new PSSession to your JEA endpoint
$jeasession = New-PSSession -ComputerName 'SERVER01' -ConfigurationName 'JEAMaintenance'

# Get a list of all the commands on the JEA endpoint
$commands = Invoke-Command -Session $jeasession -ScriptBlock { Get-Command }

# Filter out the default cmdlets
$jeaDefaultCmdlets = 'Clear-Host', 'Exit-PSSession', 'Get-Command', 'Get-FormatData', 'Get-Help', 'Measure-Object', 'Out-Default', 'Select-Object'
$filteredCommands = $commands.Name | Where-Object { $jeaDefaultCmdlets -notcontains $_ }

# Import only commands explicitly added in role capabilities and prefix each imported cmdlet with "JEA"
Import-PSSession -Session $jeasession -Prefix 'JEA' -CommandName $filteredCommands

Sie können die Proxy-Cmdlets aus dem impliziten Remotingvorgang auch mithilfe von Export-PSSession beibehalten.You can also persist the proxied cmdlets from implicit remoting using Export-PSSession. Weitere Informationen zum impliziten Remoting finden Sie in der Dokumentation zu Import-PSSession und Import-Module.For more information about implicit remoting, see the documentation for Import-PSSession and Import-Module.

Programmgesteuertes Verwenden von JEAUsing JEA programmatically

JEA kann auch in Automatisierungssystemen und Benutzeranwendungen wie z. B. internen Helpdesk-Apps und Websites verwendet werden.JEA can also be used in automation systems and in user applications, such as in-house helpdesk apps and websites. Dabei ist der Ansatz derselbe wie beim Erstellen von Apps, die mit uneingeschränkten PowerShell-Endpunkten kommunizieren.The approach is the same as that for building apps that talk to unconstrained PowerShell endpoints. Vergewissern Sie sich, dass das Programm für die Verwendung mit JEA-Einschränkungen konzipiert wurde.Ensure the program is designed to work with limitation imposed by JEA.

Für einfache, einmalige Vorgänge können Sie Invoke-Command zum Ausführen von Befehlen in einer JEA-Sitzung verwenden.For simple, one-off tasks, you can use Invoke-Command to run commands in a JEA session.

Invoke-Command -ComputerName 'SERVER01' -ConfigurationName 'JEAMaintenance' -ScriptBlock { Get-Process; Get-Service }

Um festzustellen, welche Befehle zur Verfügung stehen, wenn Sie eine Verbindung mit einer JEA-Sitzung herstellen, führen Sie Get-Command aus, und durchlaufen Sie die Ergebnisse , um die zulässigen Parameter zu überprüfen.To check which commands are available for use when you connect to a JEA session, run Get-Command and iterate through the results to check for the allowed parameters.

$allowedCommands = Invoke-Command -ComputerName 'SERVER01' -ConfigurationName 'JEAMaintenance' -ScriptBlock { Get-Command }
$allowedCommands | Where-Object { $_.CommandType -in 'Function', 'Cmdlet' } | Format-Table Name, Parameters

Wenn Sie eine C#-App erstellen, können Sie einen PowerShell-Runspace erstellen, der eine Verbindung mit einer JEA-Sitzung herstellt. Dazu müssen Sie den Namen der Konfiguration in einem WSManConnectionInfo-Objekt angeben.If you're building a C# app, you can create a PowerShell runspace that connects to a JEA session by specifying the configuration name in a WSManConnectionInfo object.

// using System.Management.Automation;
var computerName = "SERVER01";
var configName   = "JEAMaintenance";
// See https://docs.microsoft.com/dotnet/api/system.management.automation.pscredential
var creds        = // create a PSCredential object here

WSManConnectionInfo connectionInfo = new WSManConnectionInfo(
    false,                 // Use SSL
    computerName,          // Computer name
    5985,                  // WSMan Port
    "/wsman",              // WSMan Path
                           // Connection URI with config name
    string.Format(CultureInfo.InvariantCulture, "http://schemas.microsoft.com/powershell/{0}", configName),
    creds);                // Credentials

// Now, use the connection info to create a runspace where you can run the commands
using (Runspace runspace = RunspaceFactory.CreateRunspace(connectionInfo))
{
    // Open the runspace
    runspace.Open();

    using (PowerShell ps = PowerShell.Create())
    {
        // Set the PowerShell object to use the JEA runspace
        ps.Runspace = runspace;

        // Now you can add and invoke commands
        ps.AddCommand("Get-Command");
        foreach (var result in ps.Invoke())
        {
            Console.WriteLine(result);
        }
    }

    // Close the runspace
    runspace.Close();
}

Verwenden von JEA mit PowerShell DirectUsing JEA with PowerShell Direct

Hyper-V in Windows 10 und Windows Server 2016 beinhaltet PowerShell Direct. Mit dieser Funktion können Hyper-V-Administratoren virtuelle Computer mit PowerShell verwalten, und zwar unabhängig von der Netzwerkkonfiguration oder den Einstellungen für die Remoteverwaltung auf dem virtuellen Computer.Hyper-V in Windows 10 and Windows Server 2016 offers PowerShell Direct, a feature that allows Hyper-V administrators to manage virtual machines with PowerShell regardless of the network configuration or remote management settings on the virtual machine.

Durch die Verwendung von PowerShell Direct mit JEA können Sie einem Hyper-V-Administrator eingeschränkten Zugriff auf Ihren virtuellen Computer gewähren.You can use PowerShell Direct with JEA to give a Hyper-V administrator limited access to your VM. Dies kann hilfreich sein, wenn Sie die Netzwerkverbindung zu Ihrer VM verlieren und zur Reparatur der Netzwerkeinstellungen einen Datacenter-Administrator benötigen.This can be useful if you lose network connectivity to your VM and need a datacenter admin to fix the network settings.

Für die Verwendung von JEA über PowerShell Direct ist keine weitere Konfiguration erforderlich.No additional configuration is required to use JEA over PowerShell Direct. Allerdings muss das Gastbetriebssystem des virtuellen Computers Windows 10, Windows Server 2016 oder höher sein.However, the guest operating system running inside the virtual machine must be Windows 10, Windows Server 2016, or higher. Der Hyper-V-Administrator kann eine Verbindung mit dem JEA-Endpunkt herstellen und den -VMName oder den -VMId-Parameter auf PSRemoting-Cmdlets verwenden:The Hyper-V admin can connect to the JEA endpoint by using the -VMName or -VMId parameters on PSRemoting cmdlets:

# Entering a JEA session using PowerShell Direct when the VM name is unique
Enter-PSSession -VMName 'SQL01' -ConfigurationName 'NICMaintenance' -Credential 'localhost\JEAformyHoster'

# Entering a JEA session using PowerShell Direct using VM ids
$vm = Get-VM -VMName 'MyVM' | Select-Object -First 1
Enter-PSSession -VMId $vm.VMId -ConfigurationName 'NICMaintenance' -Credential 'localhost\JEAformyHoster'

Das Erstellen eines dedizierten Benutzerkontos mit minimalen Berechtigungen wird empfohlen, um das System für die Verwendung durch einen Hyper-V-Administrator zu verwalten.It's recommended you create a dedicated user account with the minimum rights needed to manage the system for use by a Hyper-V administrator. Bedenken Sie, dass sich selbst Benutzer ohne Berechtigungen standardmäßig bei einem Windows-Computer anmelden und PowerShell uneingeschränkt verwenden können.Remember, even an unprivileged user can sign into a Windows machine by default, including using unconstrained PowerShell. Auf diese Weise können sie das Dateisystem durchsuchen und Informationen über Ihr Betriebssystem sammeln.That allows them to browse the file system and learn more about your OS environment. Wenn ein Hyper-V-Administrator gesperrt werden und dessen Zugriff auf eine VM nur über PowerShell Direct mit JEA möglich sein soll, müssen Sie die lokalen Anmelderechte für das JEA-Konto des Hyper-V-Administrators verweigern.To lock down a Hyper-V administrator and limit them to only access a VM using PowerShell Direct with JEA, you must deny local logon rights to the Hyper-V admin's JEA account.