Introducing the JEA Toolkit Helper

Note: This tool has been replaced by the "JEA Helper Tool 2.0", which has been designed to work with the latest version of JEA as part of Windows Management Framework (WMF) 5.0 and Window Server 2016 Technical Preview 4 (TP4)

Please refer to the following link, for more information about this updated version:

https://blogs.technet.com/b/privatecloud/archive/2015/12/20/introducing-the-updated-jea-helper-tool.aspx


Just Enough Administration (JEA) is a powerful new feature in PowerShell, in preview today with Windows Management Framework (WMF) 5.0. In a nutshell, JEA enables delegation of a specific set of cmdlets only to specific users on specific endpoints.

If you would like to learn more about JEA, I would recommend reading this white paper, or watching the session from Jeffrey Snover during last TechEd here.

 

When implementing JEA, one of the components to prepare is the “toolkit”, which will define what users can or cannot do through the JEA session. This can be defined in a CSV-like format in the JEA configuration, and can even actually read this configuration from a CSV!

This is what a toolkit looks like:

image

Today, we’re releasing the “JEA Toolkit Helper”, a sample tool to help create those toolkits without having to discover the CSV format.

Features include:

  • Browsing local PowerShell modules and cmdlets, and add/remove them to the “toolkit designer” on the tool’s first tab
  • Export to CSV format, and import existing CSV toolkits (created by the tool, or outside of the tool)
  • Easily update JEA endpoint delegation : The tool lets you use simple user and group definitions, that it will translate to the SDDL format in the toolkit’s configuration
  • Once you have designed or updated the toolkit to match your needs, you can :
    • Paste it to the clipboard and leverage it “manually”
    • Import the toolkit on the local machine
    • Test the toolkit on the local machine
    • Remove the toolkit from the local machine
  • Optionally, you can also connect to a Service Management Automation (SMA) instance, parse existing Runbooks, and add their scoped execution to the toolkit

As always, feedback is welcome! This tool is provided “as is” but, while it has a graphical user interface, it is written in PowerShell, which makes it easy to update/enhance by the community as needed.


Download location

You can get the tool from this location.

BC-DLButtonDark


Requirements and how to use the tool

The zip file you download should contain a single PS1 file (JEAToolkitHelper.ps1) file. You just need to copy it locally, and right-click it to “Run with PowerShell”. If needed, the tool will elevate itself and present the graphical user interface.

From there, you can use the different features, which are detailed in the next section.

From a requirements standpoint:

  • The JEA Toolkit Helper requires WMF 5.0 Preview (recommended version as of today : the September 2014 Preview)
  • JEA can be installed using the “Install-Module xJEA” command line, which will pull the latest version (0.2.16.2 as of today) from the gallery. More specific instructions regarding Install-Module can be found in the JEA white paper.

More details about the features

General layout

The first tab of the tool is where you can “design” a toolkit, either from scratch or by importing/appending an existing CSV file:

image

The second tab will be dynamically updated, as your toolkit evolves. This is also where there are options to import, test and remove the toolkit as needed:

image

 

Designing a toolkit

In the first, tab, you can add/remove rows as needed. Each row can refer to a module, cmdlet, with or without specific properties. If you do not see a module in the module list, it may not be imported, so you can use the option for that. It is also possible to filter the list of cmdlets per module, for easier navigation.

Note that the tool also tries to populate the allowed values for parameters (ValidateSet), It is up to you to edit the suggested list discovered by the tool. For example, here are values discovered for the “Encoding” parameter of the “Out-File” cmdlet:

image

 

Adding SMA Runbooks to a toolkit

If you enabled Service Management Automation (SMA) integration, the list of Runbooks will be populated in the first tab:

image

When selecting one or multiple Runbooks, the Start-SmaRunbook cmdlet will be added to the toolkit, with the right parameters to ensure no other Runbooks can be executed, and pointing to another SMA instance is not allowed:

image

Note : Make sure to review the “Specific configuration for the SMA integration” section at the end of this blog post, for instructions on how to enable the SMA integration.

 

Specifying custom delegations for the toolkit

By default, a JEA endpoint only allows execution by local administrators. There is a “SecurityDescriptorSddl” property that allows to specify a list of custom groups for this.

Instead of having to figure out the right SDDL format to use, the tool lets you specify a list of users/groups. Once you have entered those groups, you can click on “Update Delegation” to update the endpoint configuration in the output script.

For example, this list of users/groups…

clip_image003

…becomes this SDDL in the script output window – The SDDL is added, as well as a comment to explain what groups it stands for:

image

If the groups cannot be found in Active Directory, a warning message will be provided in the main PowerShell script window, and the corresponding group(s) will be ignored.

When saving a toolkit to the CSV format, note the checkbox “Export delegation data as well” on the second tab. This will create a XML file with the group names, so the SDDL can be recreated when the same toolkit is imported later in the tool (with the checkbox “Import delegation data as well, if available” on the first tab.

Import:

image

Export:

image

 

Testing the toolkit on the local machine – with the tool

The tool also includes options to import the toolkit on the local machine, test it, and/or remove it:

image

Toolkit import (cut for brevity):

clip_image010

Toolkit testing:

clip_image012

 

Testing the toolkit on the local machine – manually

In the second pane, you can find a “Copy to Clipboard” option, and the output script has some guidance on how to test the toolkit manually:

image


(Optional) Specific configuration for the SMA integration

To enable the SMA integration, you will need to achieve the following:

1. Install the SMA PowerShell module from the Orchestrator/SMA media:

image

2. Edit the PS1 file and edit the two parameters to point to your SMA instance. Leaving $SMAEndpointWS empty means disabling the SMA integration feature. On the download site, the PS1 is provided with this parameter empty.

image

3. Edit the Microsoft.SystemCenter.ServiceManagementAutomation.psd1 file, from the directory below:

image

In this file, remove the line below:

image

Important : If you do not do this last step, your SMA-enabled toolkit will import just fine, but testing it will fail with an error about “New-SmaPortableModule.ps1”). For more information about SMA portable modules, you can refer to this blog post.


Thanks for reading, we hope you enjoy this tool as you start testing and using JEA!