Get-Credential

  • Referência
Módulo:
Microsoft.PowerShell.Security

Obtém um objeto de credencial com base em um nome de usuário e senha.

Syntax

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

Description

O Get-Credential cmdlet cria um objeto de credencial para um nome de usuário e senha especificados. É possível utilizar o objeto de credencial em operações de segurança.

A partir do 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 Get-Credential cmdlet solicita ao usuário uma senha ou um nome de usuário e senha. Por padrão, aparecerá uma caixa de diálogo de autenticação para solicitar o usuário. No entanto, em alguns programas host, como o console do 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 observações e os exemplos.

Exemplos

Exemplo 1

$c = Get-Credential

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

Ao digita o comando, será exibida uma caixa de diálogo 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 $c variável.

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

Exemplo 2

$c = Get-Credential -credential User01
$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 $c na variável. O segundo comando exibe o valor da propriedade Username do objeto de credencial resultante.

Exemplo 3

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

Esse 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 $Credential variável.

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

Para obter mais informações, consulte a documentação do PromptForCredential no SDK.

Exemplo 4

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 por meio de uma caixa de diálogo.

O comando cria a entrada do Registro ConsolePrompting e define seu valor como True. Para executar esse comando, inicie o 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 Remove-ItemProperty cmdlet para excluí-lo.

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

Exemplo 5

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 senha de texto sem formatação, que pode violar os padrões de segurança em algumas empresas.

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

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

O segundo comando usa o ConvertTo-SecureString cmdlet 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 de usar texto sem formatação.

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

Exemplo 6

Get-Credential -Message "Credential are required for access to the \\Server1\Scripts file share." -User Server01\PowerUser

PowerShell Credential Request
Credential are required for access to the \\Server1\Scripts file share.
Password for user Server01\PowerUser:

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

Exemplo 7

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

PowerShell Credential Request : 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

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

Parâmetros

-Credential

Especifica um nome de usuário para a credencial, como User01 ou Domain01\User01. O nome do parâmetro, -Credential, é opcional.

Ao enviar o comando e especificar um nome de usuário, será solicitada uma senha. Se você omitir esse parâmetro, será solicitado um nome de usuário e uma senha.

A partir do PowerShell 3.0, se você inserir um nome de usuário sem um domínio, Get-Credential não insere mais uma barra invertida antes do nome.

As credenciais são armazenadas em um objeto PSCredential e a senha é armazenada como um SecureString.

Observação

Para obter mais informações sobre a proteção de dados do SecureString , consulte Quão seguro é o SecureString?.

Type:PSCredential
Position:1
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-Message

Especifica uma mensagem que aparece no prompt de autenticação. Esse parâmetro é projetado para o uso em uma função ou script. É possível utilizar a mensagem para explicar ao usuário por que você está solicitando credenciais e como elas serão utilizadas.

Esse parâmetro foi introduzido no PowerShell 3.0.

Type:String
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-UserName

Especifica um nome de usuário. O prompt de autenticação solicita uma senha para o nome de usuário. Por padrão, o nome de usuário está em branco e o prompt de autenticação solicita um nome de usuário e uma senha.

Quando o prompt de autenticação aparece em uma caixa de diálogo, o usuário pode editar o nome de usuário especificado. No entanto, o usuário não pode alterar o nome de usuário quando o prompt aparece na linha de comando. Ao usar esse parâmetro em uma função compartilhada ou um script, considere todas as apresentações possíveis.

Esse parâmetro foi introduzido no PowerShell 3.0.

Type:String
Position:1
Default value:None (blank)
Required:False
Accept pipeline input:False
Accept wildcard characters:False

Entradas

None

Não é possível canalizar objetos para esse cmdlet.

Saídas

PSCredential

Esse cmdlet retorna um objeto de credencial.

Observações

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

Por padrão, o prompt de autenticação aparece na caixa de diálogo. Para exibir o prompt de autenticação na linha de comando, adicione a entrada do Registro ConsolePrompting (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 PowerShell, mas não funciona em todos os programas host.

Por exemplo, ele não tem efeito no PowerShell Integrated Scripting Environment (ISE). 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 PowerShell. A partir do PowerShell 3.0, há suporte para cmdlets selecionados, como cmdlets Get-Content e New-PSDrive .