Opções de Credenciais nos Dados de ConfiguraçãoCredentials Options in Configuration Data

Aplica-se a: Windows PowerShell 5.0Applies To: Windows PowerShell 5.0

Senhas de Texto Sem Formatação e Usuários do DomínioPlain Text Passwords and Domain Users

As configurações DSC que contêm uma credencial sem criptografia gerarão mensagens de erro sobre senhas de texto sem formatação.DSC configurations containing a credential without encryption will generate an error messages about plain text passwords. Além disso, a DSC gerará um aviso quando usar credenciais de domínio.Also, DSC will generate a warning when using domain credentials. Para suprimir essas mensagens de erro e aviso, use as palavras-chave de dados de configuração DSC:To suppress these error and warning messages use the DSC configuration data keywords:

  • PsDscAllowPlainTextPasswordPsDscAllowPlainTextPassword
  • PsDscAllowDomainUserPsDscAllowDomainUser

Observação: o uso de senhas de texto não criptografado não é seguro.Note: Using plaintext passwords is not secure. É recomendável proteger credenciais usando as técnicas discutidas mais adiante neste tópico.Securing credentials by using the techniques covered later in this topic is recommended.

A seguir, um exemplo de passar credenciais de texto sem formatação: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

Lidando com Credenciais na DSCHandling Credentials in DSC

Os recursos de configuração DSC são executados como Local System por padrão.DSC configuration resources run as Local System by default. Contudo, alguns recursos precisam de uma credencial, como quando o recurso Package precisa instalar um software em uma conta de usuário específica.However, some resources need a credential, for example when the Package resource needs to install software under a specific user account.

Recursos anteriores usaram um nome de propriedade Credential embutido em código para lidar com isso.Earlier resources used a hard-coded Credential property name to handle this. O WMF 5.0 adicionou uma propriedade PsDscRunAsCredential automática para todos os recursos.WMF 5.0 added an automatic PsDscRunAsCredential property for all resources. Para obter informações sobre como usar o PsDscRunAsCredential, confira Executar DSC com as credenciais do usuário.For information about using PsDscRunAsCredential, see Running DSC with user credentials. Recursos mais recentes e recursos personalizados podem usar essa propriedade automática em vez de criar sua própria propriedade para credenciais.Newer resources and custom resources can use this automatic property instead of creating their own property for credentials.

Observe que o design de alguns recursos consiste em usar diversas credenciais por um motivo específico e eles terão suas próprias propriedades de credencial.Note that the design of some resources are to use multiple credentials for a specific reason, and they will have their own credential properties.

Para encontrar as propriedades de credencial disponíveis em um recurso, use Get-DscResource -Name ResourceName -Syntax ou o Intellisense no 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]]
}

Esse exemplo usa um recurso Group do módulo interno de recurso de DSC PSDesiredStateConfiguration.This example uses a Group resource from the PSDesiredStateConfiguration built-in DSC resource module. Pode criar grupos locais e adicionar ou remover membros.It can create local groups and add or remove members. Ele aceita a propriedade Credential e a propriedade PsDscRunAsCredential automática.It accepts both the Credential property and the automatic PsDscRunAsCredential property. No entanto, o recurso usa apenas a propriedade Credential.However, the resource only uses the Credential property.

Para saber mais sobre a propriedade PsDscRunAsCredential, veja Execução do DSC com as credenciais do usuário.For more information about the PsDscRunAsCredential property, see Running DSC with user credentials.

Exemplo: a propriedade de credencial do recurso GroupExample: The Group resource Credential property

A DSC é executada em Local System; portanto, já tem permissões para alterar os usuários locais e grupos.DSC runs under Local System, so it already has permissions to change local users and groups. Se o membro adicionado for uma conta local, nenhuma credencial será necessária.If the member added is a local account, then no credential is necessary. Se o recurso Group adicionar uma conta de domínio ao grupo local, uma credencial será necessária.If the Group resource adds a domain account to the local group, then a credential is necessary.

Não são permitidas consultas anônimas ao Active Directory.Anonymous queries to Active Directory are not allowed. A propriedade Credential do recurso Group é a conta de domínio usada para consultar o Active Directory.The Credential property of the Group resource is the domain account used to query Active Directory. Em geral, pode ser uma conta de usuário genérica, porque, por padrão, os usuários podem ler a maioria dos objetos no 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.

Exemplo de ConfiguraçãoExample Configuration

O exemplo de código a seguir usa DSC para preencher um grupo local com um usuário de domínio: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

Esse código gera uma mensagem de erro e uma de aviso: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'.

Esse exemplo tem dois problemas:This example has two issues:

  1. Um erro explica que senhas de texto sem formatação não são recomendadasAn error explains that plain text passwords are not recommended
  2. Um aviso alerta para não usar uma credencial de domínioA warning advises against using a domain credential

PsDscAllowPlainTextPasswordPsDscAllowPlainTextPassword

A primeira mensagem de erro tem uma URL com a documentação.The first error message has a URL with documentation. Esse link explica como criptografar senhas usando uma estrutura ConfigurationData e um certificado.This link explains how to encrypt passwords using a ConfigurationData structure and a certificate. Para obter mais informações sobre certificados e DSC, leia esta postagem.For more information on certificates and DSC read this post.

Para forçar uma senha de texto sem formatação, o recurso requer a palavra-chave PsDscAllowPlainTextPassword na seção de dados de configuração, conforme segue: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

Observe que NodeName não pode ser igual a um asterisco; um nome de nó específico é obrigatório.Note that NodeName cannot equal asterisk, a specific node name is mandatory.

A Microsoft avisa para evitar senhas de texto sem formatação devido ao risco de segurança significativo.Microsoft advises to avoid plain text passwords due to the significant security risk.

Credenciais de DomínioDomain Credentials

Executar o script de configuração de exemplo novamente (com ou sem criptografia) ainda gera um aviso de que o uso de uma conta de domínio para uma credencial não é recomendado.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. O uso de uma conta local elimina a possível exposição das credenciais de domínio que podem ser usadas em outros servidores.Using a local account eliminates potential exposure of domain credentials that could be used on other servers.

Ao usar credenciais com recursos de DSC, prefira uma conta local a uma conta de domínio, quando possível.When using credentials with DSC resources, prefer a local account over a domain account when possible.

Se houver um '\'' ou um '@' na propriedade `Username` da credencial, a DSC vai tratá-la como uma conta de domínio.</span><span class="sxs-lookup"><span data-stu-id="28986-152">If there is a '\' or '@' in the Username property of the credential, then DSC will treat it as a domain account. Há uma exceção para "localhost", "127.0.0.1" e "::1" na parte do domínio do nome de usuário.There is an exception for "localhost", "127.0.0.1", and "::1" in the domain portion of the user name.

PSDscAllowDomainUserPSDscAllowDomainUser

No exemplo do recurso Group da DSC acima, a consulta de um domínio do Active Directory exige uma conta de domínio.In the DSC Group resource example above, querying an Active Directory domain requires a domain account. Nesse caso, adicione a propriedade PSDscAllowDomainUser ao bloco ConfigurationData conforme segue: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"
        }
    )
}

Agora o script de configuração vai gerar o arquivo MOF sem erros ou avisos.Now the configuration script will generate the MOF file with no errors or warnings.