PowerShell 5.0 Just Enough Administration (JEA) Part 1: Understanding JEA and Configuring the Demo Toolkit

The JEA Toolkit for PowerShell 5.0 helps administrators deploy PowerShell Remoting endpoints so that IT staff can run defined sets of tools without needing to elevate to local administrator privileges.

The ability to create constrained endpoints in PowerShell is not new, and you can find out more about the basics in PowerShell Remoting: How to Restrict User Commands on the Petri IT Knowledgebase. But providing a solution that can be used in practice is a bit more complicated and to that end, Microsoft released the Just Enough Administration toolkit for PowerShell 5.0 last summer. PowerShell 5.0 is still in preview, but it’s already included in Windows 10 and can be downloaded for Windows Server as part of the Windows Management Framework 5.0 preview.

How does JEA for PowerShell 5.0 work?

JEA for PowerShell is provided as a Desired State Configuration (DSC) resource that can be used to configure devices with JEA endpoints (toolkits). Each endpoint is a toolkit of well-defined cmdlets, functions, and parameters that connecting users are able to run. For example, you might configure a toolkit for SQL Server administrators that provides access to PowerShell cmdlets and functions required for managing SQL Server, another for IIS administrators, and so on. When a SQL admin connects to a JEA endpoint using PowerShell, they are only able to run the commands defined in the toolset, and nothing more.

Set up PowerShell JEA (Image Credit: Russell Smith)
Set up PowerShell JEA (Image Credit: Russell Smith)

Users connect to JEA endpoints using their own Active Directory (AD) or local accounts, but commands are run using a local administrator account that is unique to the server and to the JEA toolkit. The JEA local administrator account has a randomly generated password that the user connecting to the endpoint doesn’t need to know, and a scheduled task is used to reset the password for the account on a daily basis.

If the password were to be compromised, assuming other security best practices are followed, the hacker wouldn’t be able to access other servers on the network because the account and password is unique to each server. Any off-server tasks, i.e. those that require the user to make a connection to another server, can be run with the user’s own account, as the JEA local administrator account is limited to use on the server where it resides.

Logging

It’s important to know what was executed, when, where, and by whom. PowerShell logs all the required information in the event log, where you can see which user initiated the remote connection to the endpoint, the commands that were run, and under which local account. The JEA toolkit also maintains a separate comma-delimited log with information about the host, PID, date/time, toolkit, and RunSpaceID.

Loading the xJEA DSC resource

Before you can configure JEA endpoints, you’ll need to have PowerShell 5.0 and the xJEA module installed on your servers. Fortunately, PowerShell 5.0’s Install-Module cmdlet makes it easy to download and install the module, which includes the xJEA DSC resource.

Log in to Windows Server 2012 R2, open a PowerShell prompt with local administrative privileges, and run the command below to check you have PowerShell 5.0 installed:

​ $PSVersionTable.PSVersion

Now install the xJEA module using the Install-Module cmdlet:

​ Install-Module xJEA

Install-Module uses NuGet, an open source package manager originally designed for importing libraries into .NET applications. When running Install-Module for the first time, you’ll be prompted if it’s OK to install NuGet, which will then find the latest version of the xJEA DSC resource, download it from the NuGet package gallery, and install it on the system. You can also check the currently installed version of the module by running the Find-Module cmdlet as shown below:

​ Find-Module –Name xJEA

Configuring PowerShell JEA

The xJEA PowerShell module comes with some demo DSC scripts to help you get started. The SetupJEA.ps1 script, which can be found in the C:\Program Files\WindowsPowerShell\Modules\xJea.2.16.6\Examples directory, performs the following tasks:

  • Removes any existing PowerShell Remoting endpoints from the local computer, including the default PowerShell Remoting endpoints.
  • Configures the DSC Local Configuration Manager to apply changes and check every 30 minutes to ensure the machine configuration hasn’t drifted.
  • Turns on debug mode.
Set up the demo JEA endpoint (Image Credit: Russell Smith)
Set up the demo JEA endpoint (Image Credit: Russell Smith)

To run the script, open a PowerShell prompt with local administrator privileges, change the working directory to the Examples folder, and then run the script:

​ cd  ‘C:\Program Files\WindowsPowerShell\Modules\xJea.2.16.6\Examples’ 
.\SetupJEA.ps1

The script contains a DSC configuration (SetupJea), which gets converted into .MOF files so that the DSC Local Configuration Manager can apply and enforce the settings. For more information on working with Desired State Configuration, see Deploying a Desired State Configuration Web Host Using PowerShell on Petri.

Configure a JEA endpoint

The demo scripts set up JEA toolkits without us needing to understand how to work with DSC. The first demo file provided (Demo1.ps1) sets up a toolkit — or JEA endpoint as it’s sometimes referred to — with a limited set of commands for controlling processes, such as the ability to restart a service or stop processes. If you look at the file carefully, you’ll notice that you can even control the parameters that can be specified.

The list of commands accessible to users connecting to the demo endpoint (Image Credit: Russell Smith)
The list of commands accessible to users connecting to the demo endpoint (Image Credit: Russell Smith)

In addition to the default set of cmdlets and functions accessible from all endpoints, the configuration in Demo1.ps1 allows users to stop only processes named calc and notepad (Stop-Process), but restart any service (Restart-Service). Additionally, users will have access to the Get-Process and Get-Service cmdlets. You can see how this is set up in the CommandSpecs section of the script:

​ CommandSpecs = @" 
Name,Parameter,ValidateSet,ValidatePattern 
Get-Process 
Get-Service 
Stop-Process,Name,calc;notepad 
Restart-Service,Name,,^A "
@

Now run the script by typing .\demo1.ps1 in the PowerShell prompt and pressing ENTER. Once the script has completed, you’ll see a list of cmdlets and functions that will be available to users connecting to the JEA endpoint. You can also check that a new endpoint has been created by running the Get-PSSessionConfiguration cmdlet.

Viewing the configured endpoints on the device (Image Credit: Russell Smith)
Viewing the configured endpoints on the device (Image Credit: Russell Smith)

Connect to a JEA endpoint

All that leaves is to connect to the endpoint and check it works as expected. You can connect from the local or a remote server using the Enter-PSSession cmdlet, replacing localhost with the name of the server where the JEA endpoint (demo1ep) was configured:

Using Get-Command to verify the available cmdlets and functions (Image Credit: Russell Smith)
Using Get-Command to verify the available cmdlets and functions (Image Credit: Russell Smith)
​ Enter-PSSession –ComputerName localhost –ConfigurationName demo1ep

Once connected, run Get-Command to show a list of accessible cmdlets and functions. This should be limited as shown above. Open Notepad on the server where the JEA endpoint is configured and stop the process, as shown below:

​ Stop-Process –Name notepad

If you try to stop a different process, such as Server Manager, the cmdlet will fail because it’s not permitted to stop processes other than notepad or calc. Additionally, any cmdlet or function not specified in the output of Get-Command will fail to execute.

Verifying the available JEA endpoint cmdlets (Image Credit: Russell Smith)
Verifying the available JEA endpoint cmdlets (Image Credit: Russell Smith)

In the second part of this series, I’ll show you how to check the logs to get information on what commands were run, when, where and by which users, via the JEA activity log and the Windows Event Log, and how to define your own JEA endpoints.