---

NAME
Get-Credential

SYNOPSIS
Gets a credential object based on a user name and password.

SYNTAX
Get-Credential [-Credential] []


DESCRIPTION
The Get-Credential cmdlet creates a credential object for a specified user name and password. You can use the crede
ntial object in security operations.

The cmdlet prompts the user for a password or user name and password. Users are prompted through a dialog box or at
the command line, depending on the system registry setting.


PARAMETERS
-Credential
Specifies a user name for the credential, such as "User01" or "Domain01\User01". The parameter name ("Credentia
l") is optional.

When you submit the command, you will be prompted for a password.

If you enter a user name without a domain, Get-Credential inserts a backslash before the name.

If you omit this parameter, you will be prompted for a user name and a password.

Required? true
Position? 1
Default value None
Accept pipeline input? false
Accept wildcard characters? false


This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer and OutVariable. For more information, type,
"get-help about_commonparameters".

INPUTS
None
You cannot pipe input to this cmdlet.


OUTPUTS
System.Management.Automation.PSCredential
Get-Credential returns a credential object.


NOTES


You can use the PSCredential object that Get-Credential creates in cmdlets that request user authentication, su
ch as those with a Credential parameter.

The Credential parameter is not supported by the providers that are installed with Windows PowerShell. However,
you can use the Credential parameter with Get-WmiObject, because it calls the Microsoft .NET Framework directl
y.


-------------------------- EXAMPLE 1 --------------------------

C:\PS>$c = Get-Credential


Description
-----------
This command gets a credential object and saves it in the $c variable.

When you enter the command, a dialog box appears requesting a user name and password. When you enter the requested
information, the cmdlet creates a PSCredential object representing the credentials of the user and saves it in the
$c variable.

You can use the object as input to cmdlets that request user authentication, such as those with a Credential parame
ter. However, the providers that are installed with Windows PowerShell do not support the Credential parameter.





-------------------------- EXAMPLE 2 --------------------------

C:\PS>$c = Get-Credential

C:\PS>Get-WmiObject Win32_DiskDrive -ComputerName Server01 -Credential $c


Description
-----------
These commands use a credential object from Get-Credential to authenticate a user on a remote computer so they can
use Windows Management Instrumentation (WMI) to manage the computer.

The first command gets a credential object and saves it in the $c variable. The second command uses the credential
object in a Get-WmiObject command. This command gets information about the disk drives on the Server01 computer.





-------------------------- EXAMPLE 3 --------------------------

C:\PS>C:\PS>Get-WmiObject Win32_BIOS -ComputerName Server01 '
-Credential (get-credential Domain01\User01)


Description
-----------
This command shows how to include a Get-Credential command in a Get-WmiObject command.

This command uses the Get-WmiObject cmdlet to get information about the BIOS on the Server01 computer. It uses the
Credential parameter to authenticate the user, Domain01\User01, and a Get-Credential command as the value of the Cr
edential parameter.





-------------------------- EXAMPLE 4 --------------------------

C:\PS>$c = Get-Credential -credential User01

C:\PS>$c.Username

\User01


Description
-----------
This example creates a credential that includes a user name without a domain name. It demonstrates that Get-Credent
ial inserts a backslash before the user name.

The first command gets a credential with the user name User01 and stores it in the $c variable.

The second command displays the value of the Username property of the resulting credential object.





-------------------------- EXAMPLE 5 --------------------------

C:\PS>$credential = $host.ui.PromptForCredential("Need credentials", "Please enter your user name and password.", "
", "NetBiosUserName")


Description
-----------
This command uses the PromptForCredential method to prompt the user for their user name and password. The command s
aves the resulting credentials in the $credential variable.

PromptForCredential is an alternative to using Get-Credential. When you use PromptForCredential, you can specify th
e caption, messages, and user name that appear in the message box.





-------------------------- EXAMPLE 6 --------------------------

C:\PS>Set-ItemProperty 'HKLM:\SOFTWARE\Microsoft\PowerShell\1\ShellIds' ConsolePrompting $true


Description
-----------
When requiring a user name and password, as a default, a dialog box appears to prompt the user. To be prompted at t
he command line, modify the registry by running this command in Windows PowerShell Run as administrator.

Use the same command with "ConsolePrompting $false" to be prompted with a dialog box.






RELATED LINKS
Online version: http://go.microsoft.com/fwlink/?LinkID=113311