Step by Step: Secure and Control a PowerShell Direct Session with Just Enough Administration #HyperV #PowerShell #JEA

PowerShell Direct allows you to use PowerShell directly between your host operating system and virtual machines guest operating system (Specifically Windows 10 and Windows Server 2016) without having any network configured or any type of network at all, you don’t even need to have a network attached to your virtual machine, and without configuring WinRM.

For more information about PowerShell Direct, please make sure to check the following two posts:

Just Enough Administration (JEA) is a new security feature which has been introduced in Windows PowerShell Version 5.0. JEA provides a role-based access control (RBAC) platform through PowerShell Remoting, which allows specific users to perform specific administrative tasks on servers without giving them administrator rights.

JEA is being developed in parallel to Windows Server 2016 and Windows 10, and is available on older versions of Windows as well through Windows Management Framework 5.0 and beyond.

The good news is, the Hyper-V team brought JEA supports into PowerShell Direct as well.

The reason behind this additional capability is to bring PowerShell Direct into a Cloud environments, traditionally if you want to use PowerShell Direct, you need to have valid credentials both on the host and the virtual machine, so for a hoster or Service Provider cannot use PowerShell Direct to connect to the tenant virtual machine which they don’t have access to, but in Windows Server 2016, Microsoft enabled a new capability where a tenant can now choose to expose PowerShell Direct to their hoster using Just Enough Administration (JEA) platform.

In this post, we will look at how to use JEA with Hyper-V as one of multiple scenarios, we will leverage PowerShell Direct and Hyper-V nested virtualization technologies, then we will delegate and give a specific user(s) to perform a specific Hyper-V administrative tasks on the host without giving them full administrator rights.

Deployment Steps

– Domain Controller (Set up a HyperV Operator security group in your domain and a corresponding non-administrator user who is a member of that group).– Windows Server 2016 TP5 Hyper-V joined to the domain as nested instance.– PowerShell Direct support guest OS (Windows 10 or Windows Server 2016).– Management machine with Windows Management Framework 5.0.– Create and define PowerShell Role Capability File.– Create and declare PowerShell Session Configuration File. – Register Session Configuration File as a PowerShell Endpoint.

Assuming you have all the infrastructure in place and PowerShell Remoting is enabled, let’s jump into JEA configuration.

Step 1: Create and define PowerShell Role Capability File

In Step 1, we will start by creating and designing a PowerShell Role Capability File.

Open Windows PowerShell on the management machine and run the following cmdlet:

New-PSRoleCapabilityFile

PowerShell

1

2

3

New-PSRoleCapabilityFile–Path.\HyperVRole.psrc

ISE.\HyperVRole.psrc

The extension (.psrc) stands for PowerShell Role Capability.

Now in that file, you can start by defining the Visible Cmdlets, Functions, Aliases or External Commands that you want to allow in a JEA session for the user(s). You need to make sure to put that in the right category in that file.

The role capability file must be placed on the Hyper-V host that you want to restrict under C:\Program Files\WindowsPowerShell\Modules in an existing module, since the role capability file is considered as a module. You can certainly design the PSRC file on your own management machine and then copy it over the destination server you want to restrict.

In this example, I created a new folder on the host called HyperVOperator and then I created a special sub-folder called RoleCapabilities. The RoleCapabilities folder name is mandatory.

You can have as many as role capability file under that path, you will see in a bit how to register the endpoint by reference it to the PSRC file name.

Step 2: Create and declare PowerShell Session Configuration File

In Step 2, we need to define and declare the user permission to the Role Capability file that we just created above.

In order to that, we need to create a new PowerShell Session Configuration File.

On the management machine, open Windows PowerShell and run the following cmdlet:

New-PSSessionConfigurationFile

PowerShell

1

2

3

New-PSSessionConfigurationFile-Path.\HyperVSessionConfig.pssc–Full

ISE.\HyperVSessionConfig.pssc

The extension (.pssc) stands for PowerShell Session Configuration.

The Session Configuration file looks similar to the Role Capability File, in that file, you need to update the SessionType value from ‘Default’ to ‘RestrictedRemoteServer’, this is the most important one for a JEA session, so if someone connect to JEA, will be constrained properly, in other words, we are just blacklisting everything and whitelisting only the pieces that we need specifically.

The next important parameter for JEA is the RunAsVirtualAccount set to ‘$True’, that means when I connect to a JEA endpoint, I won’t be using my admin credentials on the remote server, instead, we will be able to connect with unprivileged credentials, and under the hood JEA will spin up a one time virtual local account, this account is fully privileged on the target machine and it’s tight to the connecting user. This virtual account will be limited to that remote machine and cannot be used if it’s compromised outside that box.

You can also enable the session transcripts by specifying the TranscriptDirectory path, so when someone connect to a JEA session, a log file will be created and containing everything that particular user did as if you are standing behind them.

Last but not least, we need to define a user or a security group by updating the RoleDefinitions value with the right permission and specifying the Role Capability File name that we just created in above example which is ‘HyperVRole.psrc’. A best practice is probably to make sure that your role capability files are uniquely named.

In this example, the RoleDefinitions will look similar to this one:

RoleDefinitions

PowerShell

1

2

3

4

# User roles (security groups), and the role capabilities that should be applied to them when applied to a session

RoleDefinitions=@{

'contoso.com\JEA_NonAdmin_HyperVOperator'=@{

'RoleCapabilities'='HyperVRole'}}

The complete PowerShell Session Configuration File will look like this:

Session Configuration File

PowerShell

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

31

32

33

34

35

36

37

38

39

40

41

42

43

44

45

46

47

48

49

50

51

52

53

54

55

56

57

58

59

60

61

62

63

64

65

66

67

68

69

70

71

72

73

74

75

76

77

78

79

80

81

82

83

84

85

86

87

88

89

90

91

92

93

94

95

96

97

98

99

100

101

@{

# Version number of the schema used for this document

SchemaVersion='2.0.0.0'

# ID used to uniquely identify this document

GUID='5d6e8ac4-95a6-4250-8e38-12b86a4f5840'

# Author of this document

Author='https://charbelnemnom.com'

# Description of the functionality provided by these settings

Description='Hyper-V PowerShell Session Configuration File'

# Company associated with this document

CompanyName='The Power Elite [MVP]'

# Copyright statement for this document

Copyright='(c) 2016 Charbel Nemnom. All rights reserved.'

# Session type defaults to apply for this session configuration. Can be 'RestrictedRemoteServer' (recommended), 'Empty', or 'Default'

SessionType='RestrictedRemoteServer'

# Directory to place session transcripts for this session configuration

TranscriptDirectory='C:\ProgramData\JEAConfiguration\Transcripts'

# Whether to run this session configuration as the machine's (virtual) administrator account

The Session Configuration File could be saved anywhere and is not necessary to be on the Hyper-V host that you want to restrict unlike the Role Capability File.

Step 3: Register Session Configuration File as a PowerShell Endpoint

In Step 1, we created a Role Capability File and in Step 2, we created a Session Configuration File configured.

In the last step, we will register the session configuration file as a PowerShell Endpoint, by giving the Endpoint a name and assign the right permission. We defined the permission declaratively in the session configuration file and now we will map those to a real ACL.

On the Hyper-V host that you want to restrict, open Windows PowerShell and run the following cmdlet:

If you run Get-Command, you will notice you have access only to the cmdlets that we defined in the Role Capability File.

You may wonder, why the Command Type for certain cmdlets is showing as ‘Cmdlet’ and the others as ‘Function’. The reason behind why ‘Stop-VM‘ and ‘Restart-Service‘ cmdlets are showing as Function is, because JEA is creating a rap proxy function for you that only has the Parameter Validate Set that we defined in the Role Capability File. In this example, we are only allowing to restart the (VMMS) service and Stopping a VMName named (WS2016NANO-HV02).

If we try to restart a different Service name, you will get an error as shown in the following screenshot.

The only parameter available is to restart Hyper-V Virtual Machine Management Service (VMMS).

If you try to stop a different virtual machine name, you will also get an error as shown in the next screenshot.

Auditing JEA

You might end-up with multiple role capability on the host and you may not know which group member that person belongs to. If you want to know what a user can do on that machine, there is actually an auditing function called Get-PSSessionCapability, and this function takes in the Configuration Name and a Username. And this is effectively computing Get-Command as if you were (HyperVOperator), this is an Administrative auditing tool so you can run this and see if someone does have too much access more than you defined.

To try this out, you can run the following command from an administrator PowerShell prompt on the host:

PowerShell Direct with JEA support is really a cool feature for Cloud environments, because it allows a strict control, one of many situations is used for service monitoring and to delegate Hyper-V access without adding the user(s) to the Hyper-V Administrators group, but another great example is, we know that one of the most common support calls in Cloud environment is, when a tenant accidentally breaks their own networking, and now they cannot connect remotely and they need the hoster to go in and fix it, while using Just Enough Administration over PowerShell Direct, you can setup these virtual machines, so that a hoster has the ability to go in and fix networking if needed and nothing else! They cannot access the file system, cannot mess with the services, just giving them access to the commandlets for fixing networking.

As of this writing, JEA is only limited to PowerShell and not compatible with GUI (Hyper-V Manager as an example), if you want JEA to be compatible with GUI, you need to build your own custom GUI which uses a PowerShell JEA Endpoint under the hood.

Charbel Nemnom is a Microsoft Cloud Consultant and Technical Evangelist, totally fan of the latest's IT platform solutions, accomplished hands-on technical professional with over 15 years of broad IT Infrastructure experience serving on and guiding technical teams to optimize performance of mission-critical enterprise systems. Excellent communicator adept at identifying business needs and bridging the gap between functional groups and technology to foster targeted and innovative IT project development. Well respected by peers through demonstrating passion for technology and performance improvement. Extensive practical knowledge of complex systems builds, network design and virtualization.