Usando JEA

Este artigo descreve várias maneiras de se conectar e usar um endpoint JEA.

Usando o JEA interativamente

Se você estiver testando sua configuração JEA ou tiver tarefas simples para usuários, poderá usar JEA da mesma forma que faria em uma sessão de remoting regular do PowerShell. Para tarefas de comunicação remota complexas, é recomendável usar a comunicação remota implícita. O remoting implícito permite aos usuários operar localmente com os objetos de dados.

Para usar o JEA de maneira interativamente, você precisará:

• O nome do computador ao qual você está se conectando (pode ser o computador local)
• O nome do endpoint JEA registrado nesse computador
• Credenciais que têm acesso ao ponto de extremidade JEA nesse computador

Dadas essas informações, você pode iniciar uma sessão JEA usando os cmdlets New-PSSession ou Enter-PSSession .

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

Se a conta de usuário atual tiver acesso ao ponto de extremidade JEA, você poderá omitir o parâmetro Credential.

Quando o prompt do PowerShell mudar para [localhost]: PS>, você saberá que agora está interagindo com a sessão remota JEA. Você pode executar Get-Command para verificar quais comandos estão disponíveis. Consulte o administrador para saber se há restrições nos parâmetros disponíveis ou valores de parâmetro permitidos.

Lembre-se de que as sessões do JEA operam no modo NoLanguage. Algumas das maneiras que você normalmente usa o PowerShell podem não estar disponíveis. Por exemplo, você não pode usar variáveis para armazenar dados ou inspecionar as propriedades em objetos retornados de cmdlets. O exemplo a seguir mostra duas abordagens para que os mesmos comandos funcionem no NoLanguage modo.

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

Para invocações de comando mais complexas que dificultam essa abordagem, considere usar a comunicação remota implícita ou criar funções personalizadas que encapsulam a funcionalidade necessária. Para obter mais informações sobre NoLanguageMode, consulte about_Language_Modes.

Usando JEA com comunicação remota implícita

O PowerShell tem um modelo de comunicação remota implícito que permite importar cmdlets proxy de um computador remoto e interagir com eles como se fossem comandos locais. A comunicação remota implícita é explicada neste Hey, Scripting Guy!post de blog. A comunicação remota implícita é útil ao trabalhar com JEA porque permite que você trabalhe com cmdlets JEA em um modo de linguagem completo. Você pode usar a conclusão de tabulação, variáveis, manipular objetos e até mesmo usar scripts locais para automatizar tarefas em um endpoint JEA. Sempre que você invoca um comando proxy, os dados são enviados para o ponto de extremidade JEA no computador remoto e executados lá.

O remoting implícito funciona importando cmdlets de uma sessão do PowerShell existente. Opcionalmente, você pode optar por prefixar os substantivos de cada cmdlet proxy com uma cadeia de caracteres de sua escolha. O prefixo permite que você distingue os comandos que são para o sistema remoto. Um módulo de script temporário que contém todos os comandos de proxy é criado e importado durante a sessão local do PowerShell.

# 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

Se não for possível importar uma sessão JEA devido a restrições JEA nos parâmetros padrão, siga as etapas abaixo para filtrar os comandos padrão do conjunto importado. Você pode continuar usando comandos como Select-Object, mas usará apenas a versão local instalada em seu computador em vez da importada da sessão JEA remota.

# 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

Você também pode persistir os cmdlets proxiados do remoting implícito usando Export-PSSession. Para obter mais informações sobre comunicação remota implícita, consulte a documentação de Import-PSSession e Import-Module.

Usando o JEA programaticamente

O JEA também pode ser usado em sistemas de automação e em aplicativos de usuário, como sites e aplicativos auxiliares internos. A abordagem é a mesma para a criação de aplicativos que se comunicam com pontos de extremidade não restritos do PowerShell. Verifique se o programa foi projetado para funcionar com a limitação imposta pelo JEA.

Para tarefas simples e pontuais, você pode usar Invoke-Command para executar comandos em uma sessão JEA.

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

Para verificar quais comandos estão disponíveis para uso quando você se conecta a uma sessão JEA, execute Get-Command e itere pelos resultados para verificar os parâmetros permitidos.

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

Se você estiver criando um aplicativo C#, poderá criar um runspace do PowerShell que se conecta a uma sessão JEA especificando o nome da configuração em um objeto 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();
}

Usando o JEA com o PowerShell Direct

Hyper-V no Windows 10 e no Windows Server 2016 oferece o PowerShell Direct, um recurso que permite que Hyper-V administradores gerenciem máquinas virtuais com o PowerShell, independentemente da configuração de rede ou das configurações de gerenciamento remoto na máquina virtual.

Você pode usar o PowerShell Direct com JEA para fornecer a um administrador de Hyper-V acesso limitado à sua VM. Isso pode ser útil se você perder a conectividade de rede com sua VM e precisar de um administrador de datacenter para corrigir as configurações de rede.

Nenhuma configuração adicional é necessária para usar o JEA no PowerShell Direct. No entanto, o sistema operacional convidado em execução dentro da máquina virtual deve ser Windows 10, Windows Server 2016 ou superior. O administrador do Hyper-V pode se conectar ao ponto de extremidade JEA usando os parâmetros -VMName ou -VMId nos cmdlets 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

É recomendável que você crie uma conta de usuário dedicada com os direitos mínimos necessários para gerenciar o sistema para uso por um administrador Hyper-V. Lembre-se de que até mesmo um usuário sem privilégios pode entrar em um computador Windows por padrão, incluindo o uso do PowerShell sem restrições. Isso permite que eles naveguem pelo sistema de arquivos e aprendam mais sobre o ambiente do sistema operacional. Para bloquear um administrador de Hyper-V e limitá-lo a acessar apenas uma VM usando o PowerShell Direct com JEA, você deve negar direitos de logon local à conta JEA do administrador do Hyper-V.