Get-Credential
Applies To: Windows PowerShell 2.0
Gets a credential object based on a user name and password.
Syntax
Get-Credential [-Credential] <PSCredential> [<CommonParameters>]
Description
The Get-Credential cmdlet creates a credential object for a specified user name and password. You can use the credential 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 <PSCredential>
Specifies a user name for the credential, such as "User01" or "Domain01\User01". The parameter name ("Credential") 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 |
<CommonParameters>
This command supports the common parameters: Verbose, Debug, ErrorAction, ErrorVariable, OutBuffer, OutVariable, WarningAction, and WarningVariable. For more information, see about_CommonParameters.
Inputs and Outputs
The input type is the type of the objects that you can pipe to the cmdlet. The return type is the type of the objects that the cmdlet returns.
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, such 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 directly.
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 parameter. 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 Credential 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-Credential 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 saves the resulting credentials in the $credential variable.
PromptForCredential is an alternative to using Get-Credential. When you use PromptForCredential, you can specify the 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 the 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.