Partilhar via

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.

Sintaxe

Get-Credential
   [[-Credential] <PSCredential>]
   [<CommonParameters>]
Get-Credential
   [-Message <String>]
   [[-UserName] <String>]
   [-Title <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.

O cmdlet Get-Credential solicita ao usuário uma senha ou um nome de usuário e senha. Você pode usar o parâmetro Message para especificar uma mensagem personalizada para o prompt.

No Windows PowerShell 5.1 e versões anteriores, o Windows apresenta uma caixa de diálogo para solicitar um nome de usuário e senha. No PowerShell 6.0 e posterior, o prompt é apresentado no console para todas as plataformas.

Exemplos

Exemplo 1

$c = Get-Credential

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

Quando introduz o comando, é-lhe pedido um nome de utilizador e uma palavra-passe. 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 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 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")

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 no prompt.

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

Exemplo 4

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
$credentialParams = @{
    TypeName = 'System.Management.Automation.PSCredential'
    ArgumentList = $User, $PWord
}
$Credential = New-Object @credentialParams

O primeiro comando atribui o nome de usuário à variável $User. Verifique se o valor segue o formato "Domínio\Usuário" ou "Nome_do_Computador\Usuário".

O segundo comando usa o cmdlet Read-Host para criar uma cadeia de caracteres segura a partir da 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 a partir dos valores armazenados nas variáveis $User e $PWord.

Exemplo 5

$credentialParams = @{
    Message = "Credential are required for access to the \\Server1\Scripts file share."
    UserName = "Server01\PowerUser"
}
Get-Credential @credentialParams

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

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.

Exemplo 6

Invoke-Command -ComputerName Server01 -ScriptBlock {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

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.

Parâmetros

-Credential

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

Quando você envia o comando e especifica um nome de usuário, é solicitada uma senha. Se omitir este parâmetro, ser-lhe-á pedido um nome de utilizador e uma palavra-passe.

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 num objeto PSCredential e a senha é armazenada como uma SecureString .

Observação

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

Tipo:PSCredential
Position:1
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-Message

Especifica uma mensagem que aparece no prompt de autenticação. Este parâmetro foi projetado para uso em uma função ou script. Você pode usar a mensagem para explicar ao usuário por que está solicitando credenciais e como elas serão usadas.

Esse parâmetro foi introduzido no PowerShell 3.0.

Tipo:String
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-Title

Define o texto da linha de título para o prompt de autenticação no console.

Esse parâmetro foi introduzido no PowerShell 6.0.

Tipo:String
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais: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 senha.

Esse parâmetro foi introduzido no PowerShell 3.0.

Tipo:String
Position:1
Default value:None (blank)
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

Entradas

None

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

Saídas

PSCredential

Este cmdlet retorna um objeto de credencial.

Notas

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.

O parâmetro Credential não é suportado por todos os provedores instalados com o PowerShell. A partir do PowerShell 3.0, ele é suportado em cmdlets selecionados, como os cmdlets Get-Content e New-PSDrive.