JEA の使用

この記事では、JEA エンドポイントに接続して使用できるさまざまな方法について説明します。

JEA を対話形式で使用する

JEA 構成をテストしている場合、またはユーザーに対して単純なタスクがある場合は、通常の PowerShell リモート処理セッションと同じ方法で JEA を使用できます。 複雑なリモート処理タスクの場合は、 暗黙的なリモート処理を使用することをお勧めします。 暗黙的なリモート処理を使用すると、ユーザーはデータ オブジェクトをローカルで操作できます。

JEA を対話的に使用するには、次のものが必要です。

• 接続しているコンピューターの名前 (ローカル コンピューターを使用できます)
• そのコンピューターに登録されている JEA エンドポイントの名前
• そのコンピューター上の JEA エンドポイントにアクセスできる資格情報

その情報を使用して、 New-PSSession または Enter-PSSession コマンドレットを使用して JEA セッション を 開始できます。

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

現在のユーザー アカウントが JEA エンドポイントにアクセスできる場合は、 Credential パラメーターを省略できます。

PowerShell プロンプトが [localhost]: PS> に変わると、リモート JEA セッションと対話していることがわかります。 Get-Commandを実行して、使用可能なコマンドを確認できます。 使用可能なパラメーターまたは許可されるパラメーター値に制限があるかどうかを管理者に問い合わせてください。

JEA セッションは NoLanguage モードで動作することを忘れないでください。 通常 PowerShell を使用する方法の一部は使用できない場合があります。 たとえば、変数を使用してデータを格納したり、コマンドレットから返されたオブジェクトのプロパティを調べたりすることはできません。 次の例は、同じコマンドを NoLanguage モードで動作させる 2 つの方法を示しています。

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

このアプローチを困難にするより複雑なコマンド呼び出しの場合は、 暗黙的なリモート処理 を使用するか、必要な機能 をラップするカスタム関数を作成 することを検討してください。 NoLanguageModeの詳細については、「about_Language_Modes」を参照してください。

暗黙的なリモート処理での JEA の使用

PowerShell には暗黙的なリモート処理モデルがあります。これにより、リモート コンピューターからプロキシ コマンドレットをインポートし、ローカル コマンドであるかのように操作できます。 暗黙的なリモート処理については、この「Hey, Scripting Guy!」ブログ投稿で説明されています。 JEA を使用する場合は、完全言語モードで JEA コマンドレットを操作できるため、暗黙的なリモート処理が便利です。 タブ補完、変数、オブジェクトの操作、ローカル スクリプトを使用して JEA エンドポイントに対するタスクを自動化することもできます。 プロキシ コマンドを呼び出すと、データはリモート コンピューター上の JEA エンドポイントに送信され、そこで実行されます。

暗黙的なリモート処理は、既存の PowerShell セッションからコマンドレットをインポートすることによって機能します。 必要に応じて、各プロキシ コマンドレットの名詞の前に任意の文字列を付けることができます。 プレフィックスを使用すると、リモート システム用のコマンドを区別できます。 すべてのプロキシ コマンドを含む一時スクリプト モジュールが作成され、ローカル 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

既定のパラメーターに JEA 制約があるために JEA セッションをインポートできない場合は、次の手順に従って、インポートされたセットから既定のコマンドを除外します。 Select-Objectなどのコマンドは引き続き使用できますが、リモート 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

Export-PSSession を使用して、暗黙的なリモート処理からプロキシされたコマンドレットを保持することもできます。 暗黙的なリモート処理の詳細については、 Import-PSSession と Import-Module のドキュメントを参照してください。

プログラムによる JEA の使用

JEA は、オートメーション システムや、社内のヘルプデスク アプリや Web サイトなどのユーザー アプリケーションでも使用できます。 このアプローチは、制約のない PowerShell エンドポイントと通信するアプリを構築する場合と同じです。 JEA によって課される制限に対応するようにプログラムが設計されていることを確認します。

単純な 1 回限りのタスクでは、 Invoke-Command を使用して JEA セッションでコマンドを実行できます。

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

JEA セッションに接続するときに使用できるコマンドを確認するには、 Get-Command 実行し、結果を反復処理して許可されたパラメーターを確認します。

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

C# アプリをビルドする場合は、 WSManConnectionInfo オブジェクトで構成名を指定することで、JEA セッションに接続する PowerShell 実行空間を作成できます。

// 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();
}

PowerShell Direct での JEA の使用

Windows 10 および Windows Server 2016 の Hyper-V は、Hyper-V 管理者が仮想マシンのネットワーク構成やリモート管理設定に関係なく、PowerShell を使用して仮想マシンを管理できる機能である PowerShell Direct を提供します。

JEA で PowerShell Direct を使用して、Hyper-V 管理者に VM への制限付きアクセスを許可できます。 これは、VM へのネットワーク接続が失われ、データセンター管理者がネットワーク設定を修正する必要がある場合に役立ちます。

PowerShell Direct 経由で JEA を使用するために追加の構成は必要ありません。 ただし、仮想マシン内で実行されているゲスト オペレーティング システムは、Windows 10、Windows Server 2016 以降である必要があります。 Hyper-V 管理者は、PSRemoting コマンドレットの -VMName または -VMId パラメーターを使用して JEA エンドポイントに接続できます。

$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

Hyper-V 管理者が使用するためにシステムを管理するために必要な最小限の権限を持つ専用ユーザー アカウントを作成することをお勧めします。 特権のないユーザーでも、制約のない PowerShell の使用を含め、既定で Windows マシンにサインインできることに注意してください。 これにより、ファイル システムを参照し、OS 環境の詳細を確認できます。 Hyper-V 管理者をロックダウンし、JEA で PowerShell Direct を使用して VM にのみアクセスするように制限するには、Hyper-V 管理者の JEA アカウントに対するローカル ログオン権限を拒否する必要があります。