- Reference
- Module:
- Microsoft.PowerShell.Security
Gets a credential object based on a user name and password.
Syntax
Get-Credential [[-Credential] <PSCredential>] [<CommonParameters>]
Get-Credential [-Message <String>] [[-UserName] <String>] [-Title <String>] [<CommonParameters>]
Description
The Get-Credential
cmdlet creates a credential object for a specified user name and password. Youcan use the credential object in security operations.
The Get-Credential
cmdlet prompts the user for a password or a user name and password. You can usethe Message parameter to specify a customized message for the prompt.
In Windows PowerShell 5.1 and earlier, Windows presents a dialog box to prompt for a user name andpassword. In PowerShell 6.0 and later, the prompt is presented in the console for all platforms.
Examples
Example 1
$c = Get-Credential
This command gets a credential object and saves it in the $c
variable.
When you enter the command, you are prompted for a user name and password. When you enterthe requested information, the cmdlet creates a PSCredential object representing the credentialsof 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 aCredential parameter. However, some providers that are installed with PowerShell do not supportthe Credential parameter.
Example 2
$c = Get-Credential -credential User01$c.UsernameUser01
This example creates a credential that includes a user name without a domain 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 credentialobject.
Example 3
$Credential = $host.ui.PromptForCredential("Need credentials", "Please enter your user name and password.", "", "NetBiosUserName")
This command uses the PromptForCredential method to prompt the user for their user name andpassword. The command saves the resulting credentials in the $Credential
variable.
The PromptForCredential method is an alternative to using the Get-Credential
cmdlet. When youuse PromptForCredential, you can specify the caption, messages, and user name that appear in theprompt.
For more information, see thePromptForCredentialdocumentation in the SDK.
Example 4
This example demonstrates how to create a credential object identical to the one returned byGet-Credential
.
$User = "Domain01\User01"$PWord = Read-Host -Prompt 'Enter a Password' -AsSecureString$Credential = New-Object -TypeName System.Management.Automation.PSCredential -ArgumentList $User, $PWord
The first command assigns the username to the $User
variable. Ensure the value followsthe "Domain\User" or "ComputerName\User" format.
The second command uses the Read-Host
cmdlet to create a secure string from user input. ThePrompt parameter requests user input, and the AsSecureString parameter masks the input andconverts it to a secure string.
The third command uses the New-Object
cmdlet to create a PSCredential object from the valuesstored in the $User
and $PWord
variables.
Example 5
Get-Credential -Message "Credential are required for access to the \\Server1\Scripts file share." -User Server01\PowerUserPowerShell Credential RequestCredential are required for access to the \\Server1\Scripts file share.Password for user Server01\PowerUser:
This command uses the Message and UserName parameters of the Get-Credential
cmdlet. Thiscommand format is designed for shared scripts and functions. In this case, the message tells theuser why credentials are needed and gives them confidence that the request is legitimate.
Example 6
Invoke-Command -ComputerName Server01 {Get-Credential Domain01\User02}PowerShell Credential Request : PowerShell Credential RequestWarning: 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 : Server01RunspaceId : 422bdf52-9886-4ada-ab2f-130497c6777fPSShowComputerName : TrueUserName : Domain01\User01Password : System.Security.SecureString
This command gets a credential from the Server01 remote computer. The command uses theInvoke-Command
cmdlet to run a Get-Credential
command on the remote computer. The output showsthe remote security message that Get-Credential
includes in the authentication prompt.
Parameters
-Credential
Specifies a user name for the credential, such as User01 or Domain01\User01. The parametername, -Credential
, is optional.
When you submit the command and specify a user name, you're prompted for a password. If you omitthis parameter, you're prompted for a user name and a password.
Starting in PowerShell 3.0, if you enter a user name without a domain, Get-Credential
no longerinserts a backslash before the name.
Credentials are stored in a PSCredentialobject and the password is stored as a SecureString.
Note
For more information about SecureString data protection, seeHow secure is SecureString?.
Type: | PSCredential |
Position: | 1 |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Message
Specifies a message that appears in the authentication prompt. This parameter is designed for use ina function or script. You can use the message to explain to the user why you are requestingcredentials and how they will be used.
This parameter was introduced in PowerShell 3.0.
Type: | String |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Title
Sets the text of the title line for the authentication prompt in the console.
This parameter was introduced in PowerShell 6.0.
Type: | String |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-UserName
Specifies a user name. The authentication prompt requests a password for the user name. By default,the user name is blank and the authentication prompt requests both a user name and password.
This parameter was introduced in PowerShell 3.0.
Type: | String |
Position: | 1 |
Default value: | None (blank) |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
Inputs
None
You can't pipe objects to this cmdlet.
Outputs
PSCredential
This cmdlet returns a credential object.
Notes
You can use the PSCredential object that Get-Credential
creates in cmdlets that request userauthentication, such as those with a Credential parameter.
The Credential parameter is not supported by all providers that are installed with PowerShell.Beginning in PowerShell 3.0, it is supported on select cmdlets, such as the Get-Content
and New-PSDrive
cmdlets.
- PromptForCredential