Merge pull request #2 from PowerShell/staging

sync with master

Author: zjalexander

dsc/configDataCredentials.md

@@ -80,10 +80,8 @@ configuration unencryptedPasswordDemo
             Ensure = "Present"
             MembersToInclude = "User1"
         }
-
     }
 
-    
     Node "TestMachine2"
     {
         # Now we'll use a node-specific password to this machine
@@ -110,7 +108,6 @@ configuration unencryptedPasswordDemo
             Ensure = "Present"
             MembersToInclude = "User2"
         }
-      
     }
 
 }
@@ -158,7 +155,8 @@ This example uses a [Group](https://msdn.microsoft.com/en-us/powershell/dsc/grou
 It can create local groups and add or remove members.
 It accepts both the `Credential` property and the automatic `PsDscRunAsCredential` property.
 However, the resource only uses the `Credential` property.
-Read more about `PsDscRunAsCredential` in the [WMF Release Notes](https://msdn.microsoft.com/en-us/powershell/wmf/dsc_runas).
+
+For more information about the `PsDscRunAsCredential` property, see [Running DSC with user credentials](runAsUser.md).
 
 ## Example: The Group resource Credential property
 

dsc/pullServer.md

@@ -183,7 +183,7 @@ In order to make setting up, validating and managing the pull server easier, the
      Publish-DSCModuleAndMof -Source C:\LocalDepot -Force
 ```
 
-1. A script that validates the Pull Server is configured correctly. [PullServerSetupTests.ps1](https://github.com/PowerShell/xPSDesiredStateConfiguration/blob/dev/Examples/PullServerDeploymentVerificationTest/PullServerSetupTests.ps1).
+1. A script that validates the Pull Server is configured correctly. [PullServerSetupTests.ps1](https://github.com/PowerShell/xPSDesiredStateConfiguration/blob/dev/DSCPullServerSetup/PullServerDeploymentVerificationTest/PullServerSetupTests.ps1).
 
 
 ## Pull client configuration 

jea/index.md

@@ -0,0 +1,12 @@
+---
+manager:  carmonm
+ms.topic:  article
+author:  rpsqrd
+ms.author:  ryanpu
+ms.prod:  powershell
+keywords:  powershell,cmdlet,jea
+ms.date:  2017-03-06
+title:  Just Enough Administration
+ms.technology:  powershell
+redirect_url: https://msdn.microsoft.com/powershell/jea/overview
+---

jea/overview.md

@@ -1,12 +1,11 @@
 ---
-description:  
-manager:  dongill
+manager:  carmonm
 ms.topic:  article
 author:  rpsqrd
 ms.author:  ryanpu
 ms.prod:  powershell
 keywords:  powershell,cmdlet,jea
-ms.date:  2016-12-05
+ms.date:  2017-03-07
 title:  Overview of Just Enough Administration
 ms.technology:  powershell
 ---
@@ -16,7 +15,7 @@ ms.technology:  powershell
 Just Enough Administration (JEA) is a security technology that enables delegated administration for anything that can be managed with PowerShell.
 With JEA, you can:
 
-- **Reduce the number of administrators on your machines** by leveraging virtual accounts that perform privileged actions on behalf of regular users.
+- **Reduce the number of administrators on your machines** by leveraging virtual accounts or group managed service accounts that perform privileged actions on behalf of regular users.
 - **Limit what users can do** by specifying which cmdlets, functions, and external commands they can run.
 - **Better understand what your users are doing** with transcripts and logs that show you exactly which commands a user executed during their session.
 
@@ -49,4 +48,8 @@ To learn more about the requirements to use JEA and to learn how to create, use,
 - [Registering JEA](register-jea.md) - create a JEA endpoint and make it available for users to connect to.
 - [Using JEA](using-jea.md) - learn the various ways you can use JEA.
 - [Security Considerations](security-considerations.md) - review security best practices and implications of JEA configuration options.
-- [Audit and Report on JEA](audit-and-report.md) - learn how to audit and report on JEA endpoints.
+- [Audit and Report on JEA](audit-and-report.md) - learn how to audit and report on JEA endpoints.
+
+## Samples and DSC resource
+
+Sample JEA configurations and the JEA DSC resource can be found in the [JEA GitHub repository](https://github.com/PowerShell/JEA).

jea/prerequisites.md

@@ -5,7 +5,7 @@ author:  rpsqrd
 ms.author:  ryanpu
 ms.prod:  powershell
 keywords:  powershell,cmdlet,jea
-ms.date:  2016-12-05
+ms.date:  2017-03-07
 title:  JEA Prerequisites
 ms.technology:  powershell
 ---
@@ -18,6 +18,7 @@ Just Enough Administration is a feature included with Windows PowerShell 5.0 and
 This topic describes the prerequisites that must be satisfied in order to start using JEA.
 
 ## Install JEA
+
 JEA is available with Windows PowerShell 5.0 and higher, but for full functionality it is recommended that you install the latest version of PowerShell available for your system.
 The following table describes JEA's availability on Windows Server:
 
@@ -44,6 +45,7 @@ To get support for these features, update Windows to version 1607 (Anniversary U
 <sup>2</sup> JEA cannot be configured to use virtual accounts on Windows 7.
 
 ### Check which version of PowerShell is installed
+
 To check which version of PowerShell is installed on your system, check the `$PSVersionTable` variable in a Windows PowerShell prompt.
 
 ```powershell
@@ -58,6 +60,7 @@ You are ready to use JEA if the *Major* version is equal to or greater than **5*
 For the best experience, and to have access to all the latest features, it is recommended that you upgrade to PowerShell version **5.1** when possible.
 
 ### Install Windows Management Framework
+
 If you are running an older version of PowerShell, you will need to update your system with the latest Windows Management Framework (WMF) update.
 Update packages and a link to the latest WMF release notes are available in the [Download Center](https://aka.ms/WMF5).
 
@@ -66,6 +69,7 @@ It is strongly recommended that you test your workload's compatibility with WMF
 Windows 10 users should install the latest feature updates to obtain the current version of Windows PowerShell.
 
 ## Enable PowerShell Remoting
+
 PowerShell Remoting provides the foundation on which JEA is built.
 It is therefore necessary to ensure PowerShell Remoting is enabled and [properly secured](https://msdn.microsoft.com/en-us/powershell/scripting/setup/winrmsecurity) on your system before you can use JEA.
 
@@ -77,6 +81,7 @@ Enable-PSRemoting
 ```
 
 ## Enable PowerShell module and script block logging (optional)
+
 The following steps enable logging for all PowerShell actions on your system.
 PowerShell Module Logging is not required for JEA, however it is strongly recommended that you turn it on to ensure the commands users run are logged in a central location.
 
@@ -102,5 +107,6 @@ You can also enable system-wide PowerShell transcription through Group Policy.
 - [Create a session configuration file](session-configurations.md)
 
 ## See also
+
 - [Additional information about PowerShell Remoting and WinRM security](https://msdn.microsoft.com/en-us/powershell/scripting/setup/winrmsecurity)
 - [*PowerShell ♥ the Blue Team* blog post on security](https://blogs.msdn.microsoft.com/powershell/2015/06/09/powershell-the-blue-team/)

jea/role-capabilities.md

@@ -5,7 +5,7 @@ author:  rpsqrd
 ms.author:  ryanpu
 ms.prod:  powershell
 keywords:  powershell,cmdlet,jea
-ms.date:  2016-12-05
+ms.date:  2017-03-07
 title:  JEA Role Capabilities
 ms.technology:  powershell
 ---
@@ -234,7 +234,6 @@ The most complex merge logic affects cmdlets and functions, which can have their
 
 The rules are as follows:
 
-
 1. If a cmdlet is only made visible in one role, it will be visible to the user with any applicable parameter constraints.
 2. If a cmdlet is made visible in more than one role, and each role has the same constraints on the cmdlet, the cmdlet will be visible to the user with those constraints.
 3. If a cmdlet is made visible in more than one role, and each role allows a different set of parameters, the cmdlet and all of the parameters defined across every role will be visible to the user. If one role doesn't have constraints on the parameters, all parameters will be allowed.
@@ -243,19 +242,29 @@ The rules are as follows:
 6. If a validate pattern is defined for the same cmdlet parameter in more than one role, any values that match any of the patterns will be allowed.
 7. If a validate set is defined in one or more roles, and a validate pattern is defined in another role for the same cmdlet parameter, the validate set is ignored and rule (6) applies to the remaining validate patterns.
 
-The table below shows some examples of this logic in practice using two roles, A and B, which are both assigned to a user in a JEA session.
-
-Rule | Role A VisibleCmdlets                                                                          | Role B VisibleCmdlets                                                                             | Effective user permissions
------|------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------|----------------------------
-1    | `Get-Service`                                                                                  | N/A                                                                                               | `Get-Service`
-1    | N/A                                                                                            | `Get-Service`                                                                                     | `Get-Service`
-2    | `Get-Service`                                                                                  | `Get-Service`                                                                                     | `Get-Service`
-3    | `@{ Name = 'Get-Service'; Parameters = @{ Name = 'DisplayName' }}`                             | `Get-Service`                                                                                     | `Get-Service`
-3    | `@{ Name = 'Get-Service'; Parameters = @{ Name = 'DisplayName' }}`                             | `@{ Name = 'Get-Service'; Parameters = @{ Name = 'Name' }}`                                       | `@{ Name = 'Get-Service'; Parameters = @{ Name = 'DisplayName' }, @{ Name = 'Name' }}`
-4    | `@{ Name = 'Get-Service'; Parameters = @{ Name = 'DisplayName'; ValidateSet = 'DNS Client' }}` | `@{ Name = 'Get-Service'; Parameters = @{ Name = 'DisplayName' }}`                                | `@{ Name = 'Get-Service'; Parameters = @{ Name = 'DisplayName' }}`
-5    | `@{ Name = 'Get-Service'; Parameters = @{ Name = 'DisplayName'; ValidateSet = 'DNS Client' }}` | `@{ Name = 'Get-Service'; Parameters = @{ Name = 'DisplayName'; ValidateSet = 'DHCP Client' }}`   | `@{ Name = 'Get-Service'; Parameters = @{ Name = 'DisplayName'; ValidateSet = 'DNS Client', 'DHCP Client' }}`
-6    | `@{ Name = 'Get-Service'; Parameters = @{ Name = 'DisplayName'; ValidatePattern = 'DNS.*' }}`  | `@{ Name = 'Get-Service'; Parameters = @{ Name = 'DisplayName'; ValidatePattern = 'contoso.*' }}` | `@{ Name = 'Get-Service'; Parameters = @{ Name = 'DisplayName'; ValidatePattern = '(DNS.*)\|(contoso.*)' }}`
-7    | `@{ Name = 'Get-Service'; Parameters = @{ Name = 'DisplayName'; ValidateSet = 'DNS Client' }}` | `@{ Name = 'Get-Service'; Parameters = @{ Name = 'DisplayName'; ValidatePattern = 'contoso.*' }}` | `@{ Name = 'Get-Service'; Parameters = @{ Name = 'DisplayName'; ValidatePattern = '(DNS.*)\|(contoso.*)' }}`
+Below is an example of how roles are merged according to these rules:
+
+```powershell
+# Role A Visible Cmdlets
+$roleA = @{
+    VisibleCmdlets = 'Get-Service',
+                     @{ Name = 'Restart-Service'; Parameters = @{ Name = 'DisplayName'; ValidateSet = 'DNS Client' } }
+}
+
+# Role B Visible Cmdlets
+$roleB = @{
+    VisibleCmdlets = @{ Name = 'Get-Service'; Parameters = @{ Name = 'DisplayName'; ValidatePattern = 'DNS.*' } },
+                     @{ Name = 'Restart-Service'; Parameters = @{ Name = 'DisplayName'; ValidateSet = 'DNS Server' } }
+}
+
+# Resulting permisisons for a user who belongs to both role A and B
+# - The constraint in role B for the DisplayName parameter on Get-Service is ignored becuase of rule #4
+# - The ValidateSets for Restart-Service are merged because both roles use ValidateSet on the same parameter per rule #5
+$mergedAandB = @{
+    VisibleCmdlets = 'Get-Service',
+                     @{ Name = 'Restart-Service'; Parameters = @{ Name = 'DisplayName'; ValidateSet = 'DNS Client', 'DNS Server' } }
+}
+```
 
 
 

jea/security-considerations.md

@@ -5,7 +5,7 @@ author:  rpsqrd
 ms.author:  ryanpu
 ms.prod:  powershell
 keywords:  powershell,cmdlet,jea
-ms.date:  2016-12-05
+ms.date:  2017-03-07
 title:  JEA Security Considerations
 ms.technology:  powershell
 ---
@@ -33,12 +33,11 @@ The connecting user does not know the credentials for the virtual account and ca
 
 By default, virtual accounts belong to the local administrators group on the machine.
 This gives them full rights to manage anything on the system, but no rights to manage resources on the network.
-When authenticating with other machines, the user context will be the local computer account, not the virtual account.
+When authenticating with other machines, the user context will be that of the local computer account, not the virtual account.
 
-On an Active Directory Domain Controller, virtual accounts get *domain admin* privileges by default.
-This is due to the fact that there is no group for local administrators on a domain controller.
-Accordingly, virtual accounts on domain controllers are domain accounts and can be used on other machines.
-When configuring JEA sessions on a domain controller, you must be careful to avoid exposing commands which could be used to manage other computers on the network.
+Domain controllers are a special case since there is no concept of a local administrators group.
+Instead, virtual accounts belong to Domain Admins instead and can manage the directory services on the domain controller.
+The domain identity is still restricted to use on the domain controller where the JEA session was instantiated, and any network access will appear to come from the domain controller computer object instead.
 
 In both cases, you can also explicitly define which security groups the virtual account should belong to.
 This is a good practice when the task you are performing can be done without local/domain admin privileges.
@@ -50,8 +49,8 @@ The table below summarizes the possible configuration options and resulting perm
 
 Computer type                | Virtual account group configuration | Local user context                                      | Network user context
 -----------------------------|-------------------------------------|---------------------------------------------------------|--------------------------------------------------
-Domain controller            | Default                             | Domain user, member of '*DOMAIN*\Domain Admins'         | Domain user, member of '*DOMAIN*\Domain Admins'
-Domain controller            | Domain groups A and B               | Domain user, member of '*DOMAIN*\A', '*DOMAIN*\B'       | Domain user, member of '*DOMAIN*\A', '*DOMAIN*\B'
+Domain controller            | Default                             | Domain user, member of '*DOMAIN*\Domain Admins'         | Computer account
+Domain controller            | Domain groups A and B               | Domain user, member of '*DOMAIN*\A', '*DOMAIN*\B'       | Computer account
 Member server or workstation | Default                             | Local user, member of '*BUILTIN*\Administrators'        | Computer account
 Member server or workstation | Local groups C and D                | Local user, member of '*COMPUTER*\C' and '*COMPUTER*\D' | Computer account
 
@@ -70,9 +69,8 @@ The effective permissions of the gMSA are defined by the security groups (local
 When a JEA endpoint is configured to use a gMSA account, the actions of all JEA users will appear to come from the same group managed service account.
 The only way you can trace actions back to a specific user is to identify the set of commands run in a PowerShell session transcript.
 
-**Pass-thru credentials** 
-If you do not specify a run as account, PowerShell will use the connecting user's credential to run commands on the remote server.
-This configuration is not recommended for JEA as it would require you to grant the connecting user direct access to privileged management groups.
+**Pass-thru credentials** are used when you do not speicfy a run as account and want PowerShell to use the connecting user's credential to run commands on the remote server.
+This configuration is *not* recommended for JEA as it would require you to grant the connecting user direct access to privileged management groups.
 If the connecting user already has admin privileges, they can avoid JEA altogether and manage the system via other, unconstrained means.
 See the section below on how [JEA does not protect against admins](#jea-does-not-protect-against-admins) for more information.