How to use PowerShell JEA for task delegation

Set the PowerShell JEA role capabilities

If you don't have one, create a group that includes HR employees that need limited administrative access. To set up a Just Enough Administration (JEA) constrained endpoint, it takes three steps: create a role capability file, build a session configuration file and register the JEA configuration.

JEA uses role-based access control. Each JEA endpoint, a domain controller in this case, will hold a role called ADUserManager. This role establishes a PowerShell Remoting session to a domain controller and is limited to using the New-ADUser cmdlet with specific parameters.

Administrators can use the PowerShell JEA service to delegate commands with specific parameters to other users to complete basic admin tasks.

First, create a PowerShell module called AdUserManager on the domain controller. Create the folder, the script module and the module manifest.

$roleName = 'AdUserManager'

# Create a folder for the module
$modulePath = Join-Path $env:ProgramFiles "WindowsPowerShell\Modules\$roleName"
$null = New-Item -ItemType Directory -Path $modulePath

# Create an empty script module and module manifest. At least one file in the module folder must have the same name as the folder itself.
$null = New-Item -ItemType File -Path (Join-Path $modulePath "$roleName.psm1")
New-ModuleManifest -Path (Join-Path $modulePath "$roleName.psd1") -RootModule "$roleName.psm1"

Next, create a subfolder called RoleCapabilities inside the module folder, which will hold the configuration for the ADUserManager role.

$rcFolder = Join-Path $modulePath "RoleCapabilities"
$null = New-Item -ItemType Directory $rcFolder

Next, create the role capability file for the hash table with the configuration values for the role. When the role runs in a PowerShell session, it imports the Active Directory module and only shows the New-ADUser cmdlet. We can limit this even further by setting just the specific parameters HR users need to create new users.

$rcCapFilePath = Join-Path -Path $rcFolder -ChildPath "$roleName.psrc"
$roleCapParams = @{
    Path = $rcCapFilePath
    ModulesToImport = 'ActiveDirectory'
    VisibleCmdlets = @{
        Name = 'New-Aduser'
        Parameters = @{ Name = 'GivenName' },
            @{ Name = 'SurName' },
            @{ Name = 'Name' },
            @{ Name = 'AccountPassword' },
            @{ Name = 'ChangePasswordAtLogon' },
            @{ Name = 'Enabled' },
            @{ Name = 'Department' },
            @{ Name = 'Path' }
    },
    @{
        Name = 'Get-AdUser'
        Parameters = @{
            Name = 'Filter'
        }
    }
}
New-PSRoleCapabilityFile @roleCapParams

Build the session configuration file

Next, create the session configuration file, which maps the role definition to a particular session configuration. The commands below set the session configuration and session type to RestrictedRemoteServer to make a constrained endpoint.

In the example below, the session configuration file maps the LAB\AdUserManagers Active Directory group to the role capability file. We use the RunAsVirtualAccount parameter to avoid changing group memberships. 

$sessionFilePath = Join-Path -Path $rcFolder -ChildPath "$roleName.pssc"
$params = @{
    SessionType = 'RestrictedRemoteServer'
    Path = $sessionFilePath
    RunAsVirtualAccount = $true
    RoleDefinitions = @{ 'LAB\ADUserManagers' = @{ RoleCapabilities = $roleName } }
}

New-PSSessionConfigurationFile @params

Next, run a test using the Test-PSSessionConfigurationFile cmdlet.

Test-PSSessionConfigurationFile -Path $sessionFilePath True

It should come back as true.

Register the PowerShell JEA configuration

Next, register the session configuration on the domain controller to allow HR users to establish a remote session to the domain controller.

Register-PSSessionConfiguration -Path $sessionFilePath -Name $roleName -Force

WSManConfig: Microsoft.WSMan.Management\WSMan::localhost\Plugin

Type            Keys                                Name
----            ----                                ----
Container       {Name=ADUserManager}                ADUserManager

You can see the session configuration via Get-PSSessionConfiguration.

Get-PSSessionConfiguration -Name ADUserManager

Name          : AdUserManager
PSVersion     : 5.1
StartupScript :
RunAsUser     :
Permission    : LAB\ADUserManagers AccessAllowed

Test the JEA endpoint

To make sure everything works, create a PSCredential object with the Get-Credential cmdlet and pass that credential along with the name of the registered session configuration.

$nonAdminCred = Get-Credential
$session = Enter-PSSession -ComputerName LABDC -ConfigurationName ADUserManager -Credential $nonAdminCred

You should have a PowerShell remoting session running as the virtual administrator account on the domain controller. Use Get-Command to see all of the commands available. You will see some commands that you did not assign, such as Clear-Host and Get-Help, which is fine, as these are standard commands.