Referentieopties in configuratiegegevensCredentials Options in Configuration Data

Van toepassing op: Windows PowerShell 5.0Applies To: Windows PowerShell 5.0

Ongecodeerde wachtwoorden en domeingebruikersPlain Text Passwords and Domain Users

DSC-configuraties met een referentie zonder versleuteling wordt een foutbericht over ongecodeerde wachtwoorden worden gegenereerd.DSC configurations containing a credential without encryption will generate an error message about plain text passwords. DSC wordt ook een waarschuwing gegenereerd wanneer met domeinreferenties.Also, DSC will generate a warning when using domain credentials. Als u wilt onderdrukken deze fout- en waarschuwingsberichten de sleutelwoorden gebruiken om DSC configuration gegevens:To suppress these error and warning messages use the DSC configuration data keywords:

  • PsDscAllowPlainTextPasswordPsDscAllowPlainTextPassword
  • PsDscAllowDomainUserPsDscAllowDomainUser

Notitie

Opslaan van/overdragen ongecodeerde wachtwoorden ongecodeerd is doorgaans niet beveiligd.Storing/transmitting plaintext passwords unencrypted is generally not secure. Referenties beveiligen met behulp van de technieken die verderop in dit onderwerp aan bod wordt aanbevolen.Securing credentials by using the techniques covered later in this topic is recommended. De service Azure Automation DSC kunt u om referenties in om te worden gecompileerd in configuraties en veilig opgeslagen centraal te beheren.The Azure Automation DSC service allows you to centrally manage credentials to be compiled in configurations and stored securely. Zie voor informatie: DSC-configuraties compileren / ReferentieassetsFor information, see: Compiling DSC Configurations / Credential Assets

Hier volgt een voorbeeld van het doorgeven van referenties voor tekst zonder opmaak:The following is an example of passing plain text credentials:

#Prompt user for their credentials
#credentials will be unencrypted in the MOF
$promptedCreds = get-credential -Message "Please enter your credentials to generate a DSC MOF:"

# Store passwords in plaintext, in the document itself
# will also be stored in plaintext in the mof
$password = "ThisIsAPlaintextPassword" | ConvertTo-SecureString -asPlainText -Force
$username = "User1"
[PSCredential] $credential = New-Object System.Management.Automation.PSCredential($username,$password)

# DSC requires explicit confirmation before storing passwords insecurely
$ConfigurationData = @{
    AllNodes = @(
        @{
            # The "*" means "all nodes named in ConfigData" so we don't have to repeat ourselves
            NodeName="*"
            PSDscAllowPlainTextPassword = $true
        },
        #however, each node still needs to be explicitly defined for "*" to have meaning
        @{
            NodeName = "TestMachine1"
        },
        #we can also use a property to define node-specific passwords, although this is no more secure
        @{
            NodeName = "TestMachine2";
            UserName = "User2"
            LocalPassword = "ThisIsYetAnotherPlaintextPassword"
        }
        )
}
configuration unencryptedPasswordDemo
{
    Node "TestMachine1"
    {
        # We use the plaintext password to generate a new account
        User User1
        {
            UserName = $username
            Password = $credential
            Description = "local account"
            Ensure = "Present"
            Disabled = $false
            PasswordNeverExpires = $true
            PasswordChangeRequired = $false
        }
        # We use the prompted password to add this account to the local admins group
        Group addToAdmin
        {
            # Ensure the user exists before we add the user to a group
            DependsOn = "[User]User1"
            Credential = $promptedCreds
            GroupName = "Administrators"
            Ensure = "Present"
            MembersToInclude = "User1"
        }
    }

    Node "TestMachine2"
    {
        # Now we'll use a node-specific password to this machine
        $password = $Node.LocalPass | ConvertTo-SecureString -asPlainText -Force
        $username = $node.UserName
        [PSCredential] $nodeCred = New-Object System.Management.Automation.PSCredential($username,$password)

        User User2
        {
            UserName = $username
            Password = $nodeCred
            Description = "local account"
            Ensure = "Present"
            Disabled = $false
            PasswordNeverExpires = $true
            PasswordChangeRequired = $false
        }

        Group addToAdmin
        {
            Credential = $domain
            GroupName = "Administrators"
            DependsOn = "[User]User2"
            Ensure = "Present"
            MembersToInclude = "User2"
        }
    }

}
# We declared the ConfigurationData in a local variable, but we need to pass it in to our configuration function
# We need to invoke the configuration function we created to generate a MOF
unencryptedPasswordDemo -ConfigurationData $ConfigurationData
# We need to pass the MOF to the machines we named.
#-wait: doesn't use jobs so we get blocked at the prompt until the configuration is done
#-verbose: so we can see what's going on and catch any errors
#-force: for testing purposes, I run start-dscconfiguration frequently + want to make sure i'm
#        not blocked by previous configurations that are still running
Start-DscConfiguration ./unencryptedPasswordDemo -verbose -wait -force

Afhandeling van referenties in DSCHandling Credentials in DSC

Run as-configuratie-DSC-resources Local System standaard.DSC configuration resources run as Local System by default. Sommige resources moeten echter een referentie, bijvoorbeeld wanneer de Package resource nodig heeft voor het installeren van software met een specifiek gebruikersaccount.However, some resources need a credential, for example when the Package resource needs to install software under a specific user account.

Eerdere bronnen gebruikt een vastgelegde Credential naam voor het afhandelen van deze eigenschap.Earlier resources used a hard-coded Credential property name to handle this. WMF 5.0 toegevoegd automatisch PsDscRunAsCredential eigenschap voor alle resources.WMF 5.0 added an automatic PsDscRunAsCredential property for all resources. Voor informatie over het gebruik van PsDscRunAsCredential, Zie DSC uitgevoerd met gebruikersreferenties.For information about using PsDscRunAsCredential, see Running DSC with user credentials. Nieuwere resources en aangepaste resources kunnen u deze automatische eigenschap gebruiken in plaats van hun eigen eigenschap voor referenties maken.Newer resources and custom resources can use this automatic property instead of creating their own property for credentials.

Notitie

Het ontwerp van sommige resources zijn meerdere referenties gebruiken om een bepaalde reden en hebben hun eigen referentie-eigenschappen.The design of some resources are to use multiple credentials for a specific reason, and they will have their own credential properties.

De beschikbare referentie vinden gebruiken eigenschappen van een resource Get-DscResource -Name ResourceName -Syntax of de Intellisense in de ISE (CTRL+SPACE).To find the available credential properties on a resource use either Get-DscResource -Name ResourceName -Syntax or the Intellisense in the ISE (CTRL+SPACE).

PS C:\> Get-DscResource -Name Group -Syntax
Group [String] #ResourceName
{
    GroupName = [string]
    [Credential = [PSCredential]]
    [DependsOn = [string[]]]
    [Description = [string]]
    [Ensure = [string]{ Absent | Present }]
    [Members = [string[]]]
    [MembersToExclude = [string[]]]
    [MembersToInclude = [string[]]]
    [PsDscRunAsCredential = [PSCredential]]
}

In dit voorbeeld wordt een groep resource uit de PSDesiredStateConfiguration ingebouwde DSC-resource-module.This example uses a Group resource from the PSDesiredStateConfiguration built-in DSC resource module. Deze kan lokale groepen maken en leden toevoegen of verwijderen.It can create local groups and add or remove members. De cmdlet accepteert zowel de Credential eigenschap en de automatische PsDscRunAsCredential eigenschap.It accepts both the Credential property and the automatic PsDscRunAsCredential property. De resource alleen gebruikt echter de Credential eigenschap.However, the resource only uses the Credential property.

Voor meer informatie over de PsDscRunAsCredential eigenschap, Zie DSC uitgevoerd met gebruikersreferenties.For more information about the PsDscRunAsCredential property, see Running DSC with user credentials.

Voorbeeld: De bron van referentie-eigenschapExample: The Group resource Credential property

DSC wordt uitgevoerd onder Local System, zodat het al machtigingen heeft voor lokale gebruikers en groepen te wijzigen.DSC runs under Local System, so it already has permissions to change local users and groups. Als het lid dat wordt toegevoegd een lokaal account is, zijn er is geen referentie is nodig.If the member added is a local account, then no credential is necessary. Als de Group resource wordt een domeinaccount toegevoegd aan de lokale groep en vervolgens een referentie op die nodig is.If the Group resource adds a domain account to the local group, then a credential is necessary.

Anonieme query's naar Active Directory zijn niet toegestaan.Anonymous queries to Active Directory are not allowed. De Credential eigenschap van de Group resource wordt het domeinaccount dat wordt gebruikt om te zoeken in Active Directory.The Credential property of the Group resource is the domain account used to query Active Directory. Voor de meeste doeleinden mogelijk een algemene gebruikersaccount standaard gebruikers kunnen lezen de meeste van de objecten in Active Directory.For most purposes this could be a generic user account, because by default users can read most of the objects in Active Directory.

VoorbeeldconfiguratieExample Configuration

De volgende voorbeeldcode maakt gebruik van DSC voor het vullen van een lokale groep met een domeingebruiker:The following example code uses DSC to populate a local group with a domain user:

Configuration DomainCredentialExample
{
    param
    (
        [PSCredential] $DomainCredential
    )
    Import-DscResource -ModuleName PSDesiredStateConfiguration

    node localhost
    {
        Group DomainUserToLocalGroup
        {
            GroupName        = 'ApplicationAdmins'
            MembersToInclude = 'contoso\alice'
            Credential       = $DomainCredential
        }
    }
}

$cred = Get-Credential -UserName contoso\genericuser -Message "Password please"
DomainCredentialExample -DomainCredential $cred

Deze code genereert een fout en de waarschuwing weergegeven:This code generates both an error and warning message:

ConvertTo-MOFInstance : System.InvalidOperationException error processing
property 'Credential' OF TYPE 'Group': Converting and storing encrypted
passwords as plain text is not recommended. For more information on securing
credentials in MOF file, please refer to MSDN blog:
http://go.microsoft.com/fwlink/?LinkId=393729

At line:11 char:9
+   Group
At line:297 char:16
+     $aliasId = ConvertTo-MOFInstance $keywordName $canonicalizedValue
+                ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : InvalidOperation: (:) [Write-Error], InvalidOperationException
    + FullyQualifiedErrorId : FailToProcessProperty,ConvertTo-MOFInstance

WARNING: It is not recommended to use domain credential for node 'localhost'.
In order to suppress the warning, you can add a property named
'PSDscAllowDomainUser' with a value of $true to your DSC configuration data
for node 'localhost'.

In dit voorbeeld heeft twee problemen:This example has two issues:

  1. Een fout wordt uitgelegd ongecodeerde wachtwoorden worden niet aanbevolenAn error explains that plain text passwords are not recommended
  2. Een waarschuwing adviseert tegen het gebruik van een domeinreferentieA warning advises against using a domain credential

PsDscAllowPlainTextPasswordPsDscAllowPlainTextPassword

Het eerste foutbericht heeft een URL met documentatie.The first error message has a URL with documentation. Deze koppeling wordt uitgelegd hoe u voor het versleutelen van wachtwoorden met een ConfigurationData structuur en een certificaat.This link explains how to encrypt passwords using a ConfigurationData structure and a certificate. Voor meer informatie over certificaten en DSC lezen van dit bericht.For more information on certificates and DSC read this post.

Als u een wachtwoord als tekst zonder opmaak, de bron is vereist de PsDscAllowPlainTextPassword -sleutelwoord in de configuratiegegevens sectie als volgt:To force a plain text password, the resource requires the PsDscAllowPlainTextPassword keyword in the configuration data section as follows:

Configuration DomainCredentialExample
{
    param
    (
        [PSCredential] $DomainCredential
    )
    Import-DscResource -ModuleName PSDesiredStateConfiguration

    node localhost
    {
        Group DomainUserToLocalGroup
        {
            GroupName        = 'ApplicationAdmins'
            MembersToInclude = 'contoso\alice'
            Credential       = $DomainCredential
        }
    }
}

$cd = @{
    AllNodes = @(
        @{
            NodeName = 'localhost'
            PSDscAllowPlainTextPassword = $true
        }
    )
}

$cred = Get-Credential -UserName contoso\genericuser -Message "Password please"
DomainCredentialExample -DomainCredential $cred -ConfigurationData $cd

Notitie

NodeName kan niet gelijk zijn aan sterretje, de naam van een specifiek knooppunt is verplicht.NodeName cannot equal asterisk, a specific node name is mandatory.

Microsoft adviseert om te voorkomen dat ongecodeerde wachtwoorden vanwege de aanzienlijke beveiligingsrisico met zich mee.Microsoft advises to avoid plain text passwords due to the significant security risk.

Een uitzondering hierop is wanneer u de service Azure Automation DSC lezen omdat de gegevens wordt altijd versleuteld (in doorvoer in rust in de service en in rust in het knooppunt) opgeslagen.An exception would be when using the Azure Automation DSC service, only because the data is always stored encrypted (in transit, at rest in the service, and at rest on the node).

DomeinreferentiesDomain Credentials

De voorbeeld-configuratiescript opnieuw uitgevoerd (met of zonder versleuteling), nog steeds de waarschuwing die gebruik van een domein-account voor een referentie wordt niet aanbevolen genereert.Running the example configuration script again (with or without encryption), still generates the warning that using a domain account for a credential is not recommended. Met een lokale account elimineert mogelijke blootstelling van domeinreferenties die kan worden gebruikt op andere servers.Using a local account eliminates potential exposure of domain credentials that could be used on other servers.

Als u referenties met DSC-resources, liever dan een lokale account via een domeinaccount, indien mogelijk.When using credentials with DSC resources, prefer a local account over a domain account when possible.

Als er een '' of '@' in de Username eigenschap van de referentie en vervolgens de DSC zal worden beschouwd als een domeinaccount.If there is a '' or '@' in the Username property of the credential, then DSC will treat it as a domain account. Er is een uitzondering voor "localhost", "127.0.0.1" en ":: 1" in het domeingedeelte van de gebruikersnaam.There is an exception for "localhost", "127.0.0.1", and "::1" in the domain portion of the user name.

PSDscAllowDomainUserPSDscAllowDomainUser

In de DSC Group resource voorbeeld hierboven opvragen van een Active Directory-domein vereist een domeinaccount.In the DSC Group resource example above, querying an Active Directory domain requires a domain account. In dit geval toevoegen de PSDscAllowDomainUser eigenschap in op de ConfigurationData blokkeren als volgt:In this case add the PSDscAllowDomainUser property to the ConfigurationData block as follows:

$cd = @{
    AllNodes = @(
        @{
            NodeName = 'localhost'
            PSDscAllowDomainUser = $true
            # PSDscAllowPlainTextPassword = $true
            CertificateFile = "C:\PublicKeys\server1.cer"
        }
    )
}

Het configuratiescript wordt nu het MOF-bestand zonder fouten of waarschuwingen gegenereerd.Now the configuration script will generate the MOF file with no errors or warnings.