Get-Credential
Obtém um objeto de credencial com base em um nome de usuário e senha.
Sintaxe
Get-Credential
[-Credential] <PSCredential>
[<CommonParameters>]Get-Credential
-Message <String>
[[-UserName] <String>]
[<CommonParameters>]Description
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 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 aparece para solicitar ao usuário. No entanto, em alguns programas de host, como o console do PowerShell, você pode solicitar ao usuário na linha de comando alterando uma entrada do Registro. Para obter mais informações sobre essa entrada do Registro, consulte as anotações e exemplos.
Exemplos
Exemplo 1
$c = Get-CredentialEsse comando obtém um objeto de credencial e o salva na variável $c.
Quando você insere o comando, uma caixa de diálogo é exibida solicitando um nome de usuário e uma 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 que estão instalados com o PowerShell não dão suporte ao parâmetro de credenciais.
Exemplo 2
$c = Get-Credential -Credential User01
$c.Username
User01Este 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 o armazena na variável $c.
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 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.
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 $trueEste 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 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 solicitação, defina o valor do ConsolePrompting como false ($false) ou use o cmdlet Remove-ItemProperty para excluí-lo.
A entrada do Registro ConsolePrompting funciona em alguns programas de host, como o console do PowerShell. Pode não funcionar em todos os programas de host.
Exemplo 5
Este exemplo demonstra como criar um objeto de credencial idêntico ao retornado por Get-Credential.
$User = "Domain01\User01"
$PWord = Read-Host -Prompt 'Enter a Password' -AsSecureString
$Credential = New-Object -TypeName System.Management.Automation.PSCredential -ArgumentList $User, $PWordO primeiro comando atribui o nome de usuário à variável $User. Verifique se o valor segue o formato "Domínio\Usuário" ou "ComputerName\User".
O segundo comando usa o cmdlet Read-Host para criar uma cadeia de caracteres segura com base na entrada do usuário. O parâmetro Prompt solicita a entrada do usuário e o parâmetro AsSecureString mascara a entrada e a converte em uma cadeia de caracteres segura.
O terceiro comando usa o cmdlet New-Object para criar um objeto PSCredential dos valores armazenados nas variáveis $User 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 de Mensagem 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 lhes dá 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.SecureStringEsse 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.
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, você será solicitado a fornecer uma senha. Se você omitir esse parâmetro, será solicitado que você solicite 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 inserirá mais uma barra invertida antes do nome.
As credenciais são armazenadas em um objeto PSCredential e a senha é armazenada como um SecureString.
Nota
Para obter mais informações sobre proteção de dados SecureString, consulte Quão seguro é SecureString?.
| Tipo: | PSCredential |
| Cargo: | 1 |
| Valor padrão: | None |
| Obrigatório: | True |
| Aceitar a entrada de pipeline: | False |
| Aceitar caracteres curinga: | False |
-Message
Especifica uma mensagem que aparece no prompt de autenticação. Esse parâmetro foi projetado para uso em uma função ou script. Você pode usar a mensagem para explicar ao usuário por que você está solicitando credenciais e como elas serão usadas.
Esse parâmetro foi introduzido no PowerShell 3.0.
| Tipo: | String |
| Cargo: | Named |
| Valor padrão: | None |
| Obrigatório: | True |
| Aceitar a entrada de pipeline: | False |
| Aceitar caracteres curinga: | 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 ou script compartilhado, considere todas as apresentações possíveis.
Esse parâmetro foi introduzido no PowerShell 3.0.
| Tipo: | String |
| Cargo: | 1 |
| Valor padrão: | None (blank) |
| Obrigatório: | False |
| Aceitar a entrada de pipeline: | False |
| Aceitar caracteres curinga: | False |
Entradas
None
Você não pode redirecionar objetos para este cmdlet.
Saídas
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 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 a entrada do registro ConsolePrompting (HKLM:\SOFTWARE\Microsoft\PowerShell\1\ShellIds\ConsolePrompting) e defina seu valor como True.
Se o ConsolePrompting entrada do Registro não existir ou se seu valor for False, o prompt de autenticação será exibido em uma caixa de diálogo. Para obter instruções, consulte os exemplos.
O ConsolePrompting entrada do Registro funciona no console do PowerShell, mas não funciona em todos os programas host.
Por exemplo, ele não tem efeito no ISE (Ambiente de Script Integrado) do PowerShell. Para obter informações sobre o efeito do ConsolePrompting entrada do Registro, consulte os tópicos de ajuda para o programa host.
Não há suporte para o parâmetro de credencial por todos os provedores instalados com o PowerShell.
A partir do PowerShell 3.0, há suporte para cmdlets selecionados, como os cmdlets Get-Content e New-PSDrive.
