Get-Credential

Get-Credential
    [-Credential] <PSCredential>
    [<CommonParameters>]

Get-Credential
    [[-UserName] <String>]
    -Message <String>
    [<CommonParameters>]

O cmdlet Get-Credential cria um objeto de credencial para um nome de usuário e senha especificados. Você pode usar o objeto de credencial em operações de segurança.

A partir do Windows PowerShell 3.0, você pode usar o parâmetro Message para especificar uma mensagem personalizada na caixa de diálogo que solicita ao usuário seu nome e senha.

O cmdlet Get-Credential solicita ao usuário uma senha ou um nome de usuário e senha. Por padrão, uma caixa de diálogo de autenticação é exibida para avisar o usuário. No entanto, em alguns programas host, como o console do Windows PowerShell, você pode avisar o usuário na linha de comando alterando uma entrada do Registro. Para obter mais informações sobre essa entrada do Registro, consulte as notas e exemplos.

$c = Get-Credential

Este comando obtém um objeto de credencial e o salva na variável $c.

Quando você insere o comando, uma caixa de diálogo aparece solicitando um nome de usuário e senha. Quando você insere as informações solicitadas, o cmdlet cria um objeto PSCredential que representa as credenciais do usuário e o salva na variável $c.

Você pode usar o objeto como entrada para cmdlets que solicitam autenticação de usuário, como aqueles com um parâmetro Credential. No entanto, alguns provedores instalados com o Windows PowerShell não oferecem suporte ao parâmetro Credential.

$c = Get-Credential
Get-WmiObject Win32_DiskDrive -ComputerName Server01 -Credential $c

Esses comandos usam um objeto de credencial que o cmdlet Get-Credential retorna para autenticar um usuário em um computador remoto para que ele possa usar o WMI (Instrumentação de Gerenciamento do Windows) para gerenciar o computador.

O primeiro comando obtém um objeto de credencial e o salva na variável $c. O segundo comando usa o objeto credential em um comando Get-WmiObject. Este comando obtém informações sobre as unidades de disco no computador Server01.

Get-WmiObject Win32_BIOS -ComputerName Server01 -Credential (Get-Credential -Credential Domain01\User01)

Este comando mostra como incluir um comando Get-Credential em um comando Get-WmiObject .

Este comando usa o cmdlet Get-WmiObject para obter informações sobre o BIOS no computador Server01. Ele usa o parâmetro Credential para autenticar o usuário, Domain01\User01 e um comando Get-Credential como o valor do parâmetro Credential.

PS> $c = Get-Credential -credential User01
PS> $c.Username
User01

Este exemplo cria uma credencial que inclui um nome de usuário sem um nome de domínio.

O primeiro comando obtém uma credencial com o nome de usuário User01 e a armazena na variável $c.

O segundo comando exibe o valor da propriedade Username do objeto de credencial resultante.

$Credential = $host.ui.PromptForCredential("Need credentials", "Please enter your user name and password.", "", "NetBiosUserName")

Este comando usa o método PromptForCredential para solicitar ao usuário seu nome de usuário e senha. O comando salva as credenciais resultantes na variável $Credential.

O método PromptForCredential é uma alternativa ao uso do cmdlet Get-Credential. Ao usar PromptForCredential, você pode especificar a legenda, as mensagens e o nome de usuário que aparecem na caixa de mensagem.

Set-ItemProperty "HKLM:\SOFTWARE\Microsoft\PowerShell\1\ShellIds" -Name ConsolePrompting -Value $true

Este exemplo mostra como modificar o registro para que o usuário seja solicitado na linha de comando, em vez de usar uma caixa de diálogo.

O comando cria o ConsolePrompting entrada do Registro e define seu valor como True. Para executar esse comando, inicie o Windows PowerShell com a opção "Executar como administrador".

Para usar uma caixa de diálogo para solicitar, defina o valor de ConsolePrompting como false ($false) ou use o cmdlet Remove-ItemProperty para excluí-lo.

A entrada do Registro ConsolePrompting funciona em alguns programas host, como o console do Windows PowerShell. Pode não funcionar em todos os programas host.

Este exemplo mostra como criar um objeto de credencial idêntico ao objeto que Get-Credential retorna sem avisar o usuário. Este método requer uma palavra-passe de texto simples, o que pode violar as normas de segurança em algumas empresas.

PS> $User = "Domain01\User01"
PS> $PWord = ConvertTo-SecureString -String "P@sSwOrd" -AsPlainText -Force
PS> $Credential = New-Object -TypeName System.Management.Automation.PSCredential -ArgumentList $User, $PWord

O primeiro comando salva o nome da conta de usuário no parâmetro $User. O valor deve ter o formato "Domain\User" ou "ComputerName\User".

O segundo comando usa o cmdlet ConvertTo-SecureString para criar uma cadeia de caracteres segura a partir de uma senha de texto sem formatação. O comando usa o parâmetro AsPlainText para indicar que a cadeia de caracteres é texto sem formatação e o parâmetro Force para confirmar que você entende os riscos do uso de texto sem formatação.

O terceiro comando usa o cmdlet New-Object para criar um objeto PSCredential a partir dos valores nas variáveis $User e $PWord.

PS> Get-Credential -Message "Credential are required for access to the \\Server1\Scripts file share." -User Server01\PowerUsers
Windows PowerShell Credential Request
Credential are required for access to the \\Server1\Scripts file share.
Password for user ntdev\juneb:

Este comando usa os parâmetros Message e UserName do cmdlet Get-Credential. Esse formato de comando foi projetado para scripts e funções compartilhados. Nesse caso, a mensagem informa ao usuário por que as credenciais são necessárias e dá a ele confiança de que a solicitação é legítima.

PS> Invoke-Command -ComputerName Server01 {Get-Credential Domain01\User02}

Windows PowerShell Credential Request : Windows PowerShell Credential Request
Warning: This credential is being requested by a script or application on the SERVER01 remote computer. Enter your credentials only if you
 trust the remote computer and the application or script requesting it.

Enter your credentials.
Password for user Domain01\User02: ***************

PSComputerName     : Server01
RunspaceId         : 422bdf52-9886-4ada-ab2f-130497c6777f
PSShowComputerName : True
UserName           : Domain01\User01
Password           : System.Security.SecureString

Este comando obtém uma credencial do computador remoto Server01. O comando usa o cmdlet Invoke-Command para executar um comando Get-Credential no computador remoto. A saída mostra a mensagem de segurança remota que Get-Credential inclui no prompt de autenticação.

Este cmdlet suporta os parâmetros comuns: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction e -WarningVariable. Para obter mais informações, consulte about_CommonParameters.

Não é possível canalizar a entrada para este cmdlet.

Get-Credential retorna um objeto de credencial.

Você pode usar o objeto PSCredential que Get-Credential cria em cmdlets que solicitam autenticação de usuário, como aqueles com um parâmetro Credential.

Por padrão, o prompt de autenticação aparece em uma caixa de diálogo. Para exibir o prompt de autenticação na linha de comando, adicione o ConsolePrompting entrada do Registro (HKLM:\SOFTWARE\Microsoft\PowerShell\1\ShellIds\ConsolePrompting) e defina seu valor como True. Se a entrada do Registro ConsolePrompting não existir ou se seu valor for False, o prompt de autenticação aparecerá em uma caixa de diálogo. Para obter instruções, consulte os exemplos.

A entrada do Registro ConsolePrompting funciona no console do Windows PowerShell, mas não funciona em todos os programas host.

Por exemplo, ele não tem efeito no ISE (Ambiente de Script Integrado) do Windows PowerShell. Para obter informações sobre o efeito da entrada do Registro ConsolePrompting, consulte os tópicos de ajuda do programa host.

O parâmetro Credential não é suportado por todos os provedores instalados com o Windows PowerShell. A partir do Windows PowerShell 3.0, ele tem suporte no cmdlet selecionado, como os cmdlets Get-WmiObject e New-PSDrive.