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!

Comments

  • Anonymous
    January 01, 2003
    Hi Cosmo1,
    I think you may have further questions on this topic, feel free to send me an email (my address is in the script for the tool) and we can follow up offline.
    Thanks!
  • Anonymous
    January 01, 2003
    Hi
    I am not sure about the exact cause of the issue, but if you are trying to use the CSV exported from the tool, there is a known issue right now, where the IsChecked column from the grid should not be in the export. I see in your sample below that it's included. Removing that column may help JEA recognize the CSV file. We may be providing an update to this sample tool soon (for this and other items) and, in the meantime, you could also edit the script, since it's PowerShell based. The non-CSV output in the "Script output" tab should work fine.
    Thanks!
  • Anonymous
    April 08, 2015
    I'm running Win10 (Preview version 9926) and I have completed all the above JEA install and config steps, but my below DSC Config script returns the following error: "The WS-Management Service cannot process the request. The WMI Service or WMI Provider returned an unknown error: HRESULT 0x800706e"

    My Imported csv file looks like:
    ====================
    IsChecked Module Name Parameter ValidateSet ValidatePattern
    FALSE Get-EventLog #NAME? Application
    FALSE Get-Content #NAME? C:UsersPublicJEA_Test.txt


    ======================
    configuration DCS_Config1
    {
    Import-DscResource -module xjea

    xJeaToolKit DCS_Config1
    {
    Name = 'DCS_Config1'
    CommandSpecs = @"
    Module, Name,Parameter,ValidateSet,ValidatePattern
    ,Get-EventLog,-LogName,Application,
    ,Get-Content,-Path,,C:UsersPublicJEA_Test.txt
    ,,,,

    "@
    }

    xJeaEndPoint DCS_Config1EP
    {
    Name = 'localhost'
    Toolkit = 'DCS_Config1'
    DependsOn = '[xJeaToolKit]DCS_Config1'
    #CleanAll = 'True'
    }
    }

    DCS_Config1 -OutputPath .DCS_Config1_MOF
    Start-DscConfiguration -Path .DCS_Config1_MOF -ComputerName localhost -verbose -wait -debug -force

    ======================

    I have tried the following troubleshooting items without any luck. Would you have any ideas what my problem could be?
    - Rebooted many times
    - Logged in as local Admin
    - Winrm quickconfig -force
    - Enable-PSRemoting -force
    - Register-PSSessionConfiguration -Name DCS_Config1 -force
    - Set-PSSessionConfiguration -ShowSecurityDescriptorUI -Name DCS_Config1 -force, and gave this item 'Full Control'

    =============

    Once I create this JEAEndPoint, I'd like to run the following code over it:

    $Session = New-PSSession -ComputerName localhost -ConfigurationName DCS_Config1 -Debug -Verbose
    Get-Process | where {$_.name -like "p*"}
    Enter-PSSession $Session
    Get-PSSession | Remove-PSSession