Utilizar a JEA

Artigo
11/08/2024

Este artigo descreve as várias maneiras de se conectar e usar um ponto de extremidade JEA.

Usando o JEA de forma interativa

Se você estiver testando sua configuração de JEA ou tiver tarefas simples para os usuários, poderá usar o JEA da mesma forma que usaria uma sessão de comunicação remota regular do PowerShell. Para tarefas complexas de comunicação remota, recomenda-se o uso de comunicação remota implícita. A comunicação remota implícita permite que os usuários operem com os objetos de dados localmente.

Para usar o JEA interativamente, você precisa:

O nome do computador ao qual você está se conectando (pode ser a máquina local)
O nome do ponto de extremidade 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 for alterado [localhost]: PS> , você saberá que agora está interagindo com a sessão remota do JEA. Você pode executar Get-Command para verificar quais comandos estão disponíveis. Consulte o administrador para saber se há alguma restrição sobre os parâmetros disponíveis ou valores de parâmetros permitidos.

Lembre-se, as sessões JEA operam no NoLanguage modo. Algumas das maneiras como 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 fazer com 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 o uso de comunicação remota implícita ou a criação de funções personalizadas que envolvam a funcionalidade necessária. Para obter mais informações sobre NoLanguageModeo , 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 de proxy de uma máquina remota e interagir com eles como se fossem comandos locais. A comunicação remota implícita é explicada neste Hey, Scripting Guy! postagem no blog. A comunicação remota implícita é útil ao trabalhar com JEA, pois permite que você trabalhe com cmdlets JEA em um modo de linguagem completa. Você pode usar o preenchimento de guias, variáveis, manipular objetos e até mesmo usar scripts locais para automatizar tarefas em um ponto de extremidade JEA. Sempre que você invoca um comando proxy, os dados são enviados para o ponto de extremidade JEA na máquina remota e executados lá.

A comunicação remota implícita funciona importando cmdlets de uma sessão existente do PowerShell. Opcionalmente, você pode optar por prefixar os substantivos de cada cmdlet proxy com uma cadeia de caracteres de sua escolha. O prefixo permite distinguir os comandos que são para o sistema remoto. Um módulo de script temporário contendo todos os comandos de proxy é criado e importado para a duração da 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

Importante

Alguns sistemas podem não conseguir importar uma sessão JEA inteira devido a restrições nos cmdlets JEA padrão. Para contornar isso, importe apenas os comandos necessários da sessão JEA, fornecendo explicitamente seus nomes para o -CommandName parâmetro. Uma atualização futura resolverá o problema com a importação de sessões JEA inteiras em sistemas afetados.

Se você não conseguir importar uma sessão JEA devido a restrições de 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 apenas usará a versão local instalada no seu computador em vez da importada da sessão remota JEA.

# 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 por proxy a partir da comunicação remota implícita usando Export-PSSession. Para obter mais informações sobre comunicação remota implícita, consulte a documentação para 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ários, como aplicativos internos de helpdesk e sites. A abordagem é a mesma da criação de aplicativos que conversam com pontos de extremidade do PowerShell sem restrições. Certifique-se de que o programa foi projetado para funcionar com a limitação imposta pelo JEA.

Para tarefas simples e únicas, 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 os 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 espaço de execução do PowerShell que se conecte 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

O Hyper-V no Windows 10 e no Windows Server 2016 oferece o PowerShell Direct, um recurso que permite que os administradores do Hyper-V 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 conceder a um administrador do 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 sobre o 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 -VMName parâmetros 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 criar uma conta de usuário dedicada com os direitos mínimos necessários para gerenciar o sistema para uso por um administrador do Hyper-V. Lembre-se, até mesmo um usuário sem privilégios pode entrar em uma máquina Windows por padrão, inclusive usando o PowerShell sem restrições. Isso permite que eles naveguem pelo sistema de arquivos e aprendam mais sobre seu ambiente de sistema operacional. Para bloquear um administrador do 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.

Partilhar via

Utilizar a JEA

Usando o JEA de forma interativa

Usando JEA com comunicação remota implícita

Usando o JEA programaticamente

Usando o JEA com o PowerShell Direct

Recursos adicionais