Utilisation de JEA

Cet article décrit les différentes façons dont vous pouvez vous connecter et utiliser un point de terminaison JEA.

Utilisation interactive de JEA

Si vous testez votre configuration JEA ou que vous avez des tâches simples pour les utilisateurs, vous pouvez utiliser JEA de la même façon qu’une session de communication à distance PowerShell standard. Pour les tâches de communication à distance complexes, il est recommandé d’utiliser la communication à distance implicite. Le remoting implicite permet aux utilisateurs de travailler avec les objets de données localement.

Pour utiliser JEA de façon interactive, vous avez besoin des éléments suivants :

• Nom de l’ordinateur auquel vous vous connectez (il peut s’agir de l’ordinateur local)
• Nom du point de terminaison JEA inscrit sur cet ordinateur
• Informations d'authentification qui ont accès au point de terminaison JEA sur cet ordinateur

Étant donné ces informations, vous pouvez démarrer une session JEA à l’aide des applets de commande New-PSSession ou Enter-PSSession .

$sessionParams = @{
    ComputerName      = 'localhost'
    ConfigurationName = 'JEAMaintenance'
    Credential        = Get-Credential
}
Enter-PSSession @sessionParams

Si le compte d’utilisateur actuel a accès au point de terminaison JEA, vous pouvez omettre le paramètre Credential .

Lorsque l'invite PowerShell change pour devenir [localhost]: PS>, vous savez que vous interagissez maintenant avec la session JEA distante. Vous pouvez exécuter Get-Command pour vérifier quelles commandes sont disponibles. Consultez votre administrateur pour savoir s’il existe des restrictions sur les paramètres disponibles ou les valeurs de paramètres autorisées.

N’oubliez pas que les sessions JEA fonctionnent en NoLanguage mode. Certaines des façons dont vous utilisez généralement PowerShell peuvent ne pas être disponibles. Par exemple, vous ne pouvez pas utiliser de variables pour stocker des données ou inspecter les propriétés sur les objets retournés par les applets de commande. L’exemple suivant montre deux approches pour que les mêmes commandes fonctionnent en mode NoLanguage.

# 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'

Pour les appels de commandes plus complexes qui rendent cette approche difficile, envisagez d’utiliser la communication à distance implicite ou de créer des fonctions personnalisées qui encapsulent les fonctionnalités dont vous avez besoin. Pour plus d’informations sur NoLanguageMode, consultez about_Language_Modes.

Utilisation de JEA avec téléadministration implicite

PowerShell a un modèle de communication à distance implicite qui vous permet d’importer des applets de commande proxy à partir d’une machine distante et d’interagir avec eux comme s’ils étaient des commandes locales. La communication à distance implicite est expliquée dans ce Hey, Scripting Guy !billet de blog. La communication à distance implicite est utile lors de l’utilisation de JEA, car elle vous permet d’utiliser des applets de commande JEA en mode langage complet. Vous pouvez utiliser l’achèvement de tabulation, les variables, manipuler des objets et même utiliser des scripts locaux pour automatiser les tâches sur un point de terminaison JEA. Chaque fois que vous appelez une commande proxy, les données sont envoyées au point de terminaison JEA sur l’ordinateur distant et exécutées là-bas.

Le remoting implicite fonctionne en important des cmdlets à partir d’une session PowerShell existante. Vous pouvez éventuellement choisir de préfixer les noms de chaque applet de commande proxy avec une chaîne de votre choix. Le préfixe vous permet de distinguer les commandes qui sont pour le système distant. Un module de script temporaire contenant toutes les commandes proxy est créé et importé pendant la durée de votre session PowerShell locale.

# 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

Si vous ne parvenez pas à importer une session JEA à cause des contraintes JEA concernant les paramètres par défaut, suivez les étapes ci-dessous pour exclure les commandes par défaut de l'ensemble importé. Vous pouvez continuer à utiliser des commandes comme Select-Object, mais vous allez simplement utiliser la version locale installée sur votre ordinateur au lieu de celle importée à partir de la session JEA distante.

# 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

Vous pouvez également conserver les applets de commande proxiées à partir de la communication à distance implicite à l’aide de Export-PSSession. Pour plus d’informations sur la communication à distance implicite, consultez la documentation relative à Import-PSSession et Import-Module.

Utilisation de JEA de manière programmatique

JEA peut également être utilisé dans les systèmes d’automatisation et dans les applications utilisateur, telles que les applications de support technique internes et les sites web. L’approche est la même que pour la création d’applications qui communiquent avec des points de terminaison PowerShell sans contrainte. Assurez-vous que le programme est conçu pour fonctionner avec des limitations imposées par JEA.

Pour des tâches simples et ponctuelles, vous pouvez utiliser Invoke-Command pour exécuter des commandes dans une session JEA.

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

Pour savoir quelles commandes sont disponibles à utiliser lorsque vous vous connectez à une session JEA, exécutez Get-Command et parcourez les résultats pour vérifier les paramètres autorisés.

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

Si vous créez une application C#, vous pouvez créer un runspace PowerShell qui se connecte à une session JEA en spécifiant le nom de configuration dans un objet WSManConnectionInfo .

// using System.Management.Automation;
var computerName = "SERVER01";
var configName   = "JEAMaintenance";
// See https://learn.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();
}

Utilisation de JEA avec PowerShell Direct

Hyper-V dans Windows 10 et Windows Server 2016 offre PowerShell Direct, fonctionnalité qui permet aux administrateurs Hyper-V de gérer des machines virtuelles avec PowerShell, quelle que soit la configuration réseau ou les paramètres de gestion à distance sur la machine virtuelle.

Vous pouvez utiliser PowerShell Direct avec JEA pour accorder à un administrateur Hyper-V un accès limité à votre machine virtuelle. Cela peut être utile si vous perdez la connectivité réseau à votre machine virtuelle et si vous avez besoin d’un administrateur de centre de données pour corriger les paramètres réseau.

Aucune configuration supplémentaire n’est requise pour utiliser JEA sur PowerShell Direct. Toutefois, le système d’exploitation invité s’exécutant à l’intérieur de la machine virtuelle doit être Windows 10, Windows Server 2016 ou version ultérieure. L’administrateur Hyper-V peut se connecter au point de terminaison JEA en utilisant soit les paramètres -VMName soit -VMId sur les applets de commande PSRemoting :

$sharedParams = @{
    ConfigurationName = 'NICMaintenance'
    Credential        = Get-Credential -UserName 'localhost\JEAformyHoster'
}
# Entering a JEA session using PowerShell Direct when the VM name is unique
Enter-PSSession -VMName 'SQL01' @sharedParams

# Entering a JEA session using PowerShell Direct using VM ids
$vm = Get-VM -VMName 'MyVM' | Select-Object -First 1
Enter-PSSession -VMId $vm.VMId @sharedParams

Il est recommandé de créer un compte d’utilisateur dédié avec les droits minimum nécessaires pour gérer le système à utiliser par un administrateur Hyper-V. N’oubliez pas que même un utilisateur non privilégié peut se connecter à un ordinateur Windows par défaut, notamment à l’aide de PowerShell sans contraintes. Cela leur permet de parcourir le système de fichiers et d’en savoir plus sur votre environnement de système d’exploitation. Pour verrouiller un administrateur Hyper-V et les limiter à accéder uniquement à une machine virtuelle à l’aide de PowerShell Direct avec JEA, vous devez refuser les droits d’ouverture de session locale au compte JEA de l’administrateur Hyper-V.