NOTE: This page is no longer being updated. To install the latest version of DSC Resource Kit, please use the PowerShell Gallery. If you need to report issues or would like to contribute to development, check out our GitHub Repositories.

.

Introduction

The xJea module is a part of the Windows PowerShell Desired State Configuration (DSC) Resource Kit, which is a collection of DSC Resources produced by the PowerShell Team. This module focuses on enabling the Just Enough Administration (JEA) scenarios presented at TechEd 2014 , and contains the following resources:

  • xJeaEndPoint, which allows creation of PowerShell JEA Endpoints that leverage one or more JEA Toolkits and properties of the endpoints including access control.
  • xJeaToolKit, which allows creation of a JEA Toolkit that defines which applications, scripts, and commands should be available within a PowerShell constrained endpoint configuration.

All of the resources in the DSC Resource Kit are provided AS IS, and are not supported through any Microsoft standard support program or service. The ""x" in xJea stands for experimental , which means that these resources will be fix forward and monitored by the module owner(s).

Please leave comments, feature requests, and bug reports in the Q & A tab for this module.

If you would like to modify xJea module, feel free. When modifying, please update the module name, resource friendly name, and MOF class name (instructions below). As specified in the license, you may copy or modify this resource as long as they are used on the Windows Platform.

For more information about Windows PowerShell Desired State Configuration, check out the blog posts on the PowerShell Blog ( this is a good starting point). There are also great community resources, such as PowerShell.org, or PowerShell Magazine. For more information on the DSC Resource Kit, check out this blog post.

Installation

To install xJea module

  • Unzip the content under $env:ProgramFiles\WindowsPowerShell\Modules folder

To confirm installation:

  • Run Get-DSCResource to see that xJeaEndPoint and xJeaToolKit are among the DSC Resources listed

Requirements

This module requires the use of Windows Management Framework (WMF) 5.0 preview , which is compatible only with Windows 8.1 and Windows Server 2012 r2. Please read the installation instructions that are present on both the download page and the release notes for WMF 5.0.

Description

The xJea module contains the following DSC Resources:

  • xJeaEndPoint, which allows creation of PowerShell JEA Endpoints that leverage one or more JEA Toolkits and properties of the endpoints including access control.
  • xJeaToolKit, which allows creation of a JEA Toolkit that defines which applications, scripts, and commands should be available within a PowerShell constrained endpoint configuration.

Details

xJeaEndPoint resource has following properties:

  • Name:   Sets a name for the registered endpoint. This will be used by operators to choose which endpoint they should connect to
  • Toolkit: The JEA toolkits that should be available from this endpoint
  • SecurityDescriptorSddl:   An SDDL that defines access for the session.
  • Group:   List of local groups that this Endpoint's JeaSessionAccount should be a member of
  • Ensure:   Specifies whether the given JEA Endpoint is present or absent
  • CleanAll:   Boolean value that when set to True will remove all endpoint configurations from the endpoint server

xJeaEndToolkit resource has following properties:

  • Name:   Name of the JEA toolkit to be generated
  • CommandSpecs:   Comma separated value formated list of command specifications
  • ScriptDirectory:   Array of script directories that can be run
  • Applications:   Array listing the executables that are allowed to run
  • Ensure:   Specifies whether the given JEA Endpoint is present or absent

Renaming Requirements

When making changes to these resources, we suggest the following practice:

  1. Update the following names by replacing MSFT with your company/community name and replacing the "x" with "c" (short for "Community") or another prefix of your choice:
    • Module name (ex: xJea becomes cJea)
    • Resource folder (ex: MSFT_xJeaEndToolkit becomes Contoso_cJeaEndToolkit)
    • Resource Name (ex: MSFT_xJeaEndToolkit becomes Contoso_cJeaEndToolkit)
    • Resource Friendly Name (ex: xJeaEndToolkit becomes cJeaEndToolkit)
    • MOF class name (ex: MSFT_xJeaEndToolkit becomes Contoso_cJeaEndToolkit)
    • Filename for the <resource>.schema.mof (ex: MSFT_xJeaEndToolkit.schema.mof becomes Contoso_cJeaEndToolkit.schema.mof)
  2. Update module and metadata information in the module manifest
  3. Update any configuration that use these resources

We reserve resource and module names without prefixes ("x" or "c") for future use (e.g. "MSFT_**RealResourceName**" or "**RealResourceName**"). If the next version of Windows Server ships with a "**RealResourceName**" resource, we don't want to break any configurations that use any community modifications. Please keep a prefix such as "c" on all community modifications.

Versions

0.2.16.1

  • Initial release with the following resources
    • xJeaEndPoint
    • xJeaEndToolKit

Example: creating a new Toolkit

Create a new JEAToolkit configuration in the script and set the properties, as in the example below.
In this example, the toolkit is created using a CSV file for ease of authoring. The result would allow a connected user to run “Get-EventLog”, “Get-Content” with only the “-Name” parameter, “ipconfig”, and nothing else.

PowerShell
Edit|Remove
JeaToolkit ExampleToolkit 
 { 
   Name = "Auditor toolkit" 
   CommandSpecs = Get-Content “C:\AuditorToolkit\Toolkit.csv” -Raw 
   applications = "ipconfig" 
 }

 

This would load the contents of a CSV file that can be created using Microsoft Excel, or any text editor. An example of the content is given below.
Save the 4 lines below as "Toolkit.csv", then open it in Excel for easy editing.

Module,Name,Parameter,ValidateSet,ValidatePattern
,Get-EventLog,'-LogName',Application,
,Get-Content,'-Path',,C:\\logs*.txt
SMBShare,Get-*,,,

Example: To create a new JEA EndPoint

This example will create a new JEAEndPoint configuration in the DSC configuration script and set each of the properties.

PowerShell
Edit|Remove
JeaEndPoint AuditorEndPoint 
                 { 
                   Name = 'Auditor EndPoint' 
                   Ensure = 'Present' 
                   Toolkit = ‘AuditorToolkit’ 
                  DependsOn = '[JeaToolkit]AuditorToolkit' 
                 } 
                
 

For Additional Samples

This module contains a whitepaper explaining the use of these resources. From an elevated PS prompt, run

  import-Module -name 'xjea' -Verbose

You should see the functions: Show-JeaExamples, and Show-JeaWhitePaper. Run Show-JeaWhitpaper to see examples and additional information.