en-US/CredUICredential.dll-Help.xml
|
<?xml version="1.0" encoding="utf-8"?>
<helpItems xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" schema="maml" xmlns="http://msh"> <command:command> <command:details> <command:name>Get-CredUICredential</command:name> <maml:description> <maml:para>Gets a credential object based on a user name and password. It uses Windows native dialogs even on PowerShell 7.x, instead of the terminal.</maml:para> </maml:description> <command:verb>Get</command:verb> <command:noun>CredUICredential</command:noun> </command:details> <maml:description> <maml:para>The `Get-CredUICredential` cmdlet creates a credential object for a specified user name and password. You can use the credential object in security operations. `Get-CredUICredential` always prompts with the modern (Vista+) Windows credential dialog: the same dialog Windows itself shows for UAC elevation and RDP logins. Unlike `Get-Credential`, it never falls back to a terminal prompt, and there is no registry entry that changes this. This cmdlet aims to be a drop-in alternative to `Get-Credential`. Its parameters and its output are the same, with a few additions: `-ShowSaveCheckbox`, `-RetryNormalUser`, `-RetryAdminUser`, and `-MaxAttempts`. Refer to the `Get-Credential` documentation for advanced usages. This module is a maintained fork of the archived [Get-WinCredential](https://github.com/zbalkan/Get-WinCredential) by Zafer Balkan. The code is based on the [Credential Management API examples by Alan Dean](https://www.developerfusion.com/code/4693/using-the-credential-management-api/). The module is a binary module built for .NET 10, so it needs a PowerShell host running on .NET 10. That means **PowerShell 7.6 or later**, on Windows.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Get-CredUICredential</maml:name> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="0" aliases="none"> <maml:name>Credential</maml:name> <maml:description /> <command:parameterValue required="true" variableLength="false">PSCredential</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.PSCredential</maml:name> </dev:type> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Get-CredUICredential</maml:name> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="0" aliases="none"> <maml:name>UserName</maml:name> <maml:description /> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> </dev:type> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Message</maml:name> <maml:description /> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> </dev:type> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Title</maml:name> <maml:description /> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> </dev:type> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>ShowSaveCheckbox</maml:name> <maml:description /> <dev:type> <maml:name>System.Management.Automation.SwitchParameter</maml:name> </dev:type> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Get-CredUICredential</maml:name> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="0" aliases="none"> <maml:name>UserName</maml:name> <maml:description /> <command:parameterValue required="true" variableLength="false">string</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> </dev:type> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>RetryNormalUser</maml:name> <maml:description /> <dev:type> <maml:name>System.Management.Automation.SwitchParameter</maml:name> </dev:type> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Message</maml:name> <maml:description /> <command:parameterValue required="true" variableLength="false">string</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> </dev:type> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Title</maml:name> <maml:description /> <command:parameterValue required="true" variableLength="false">string</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> </dev:type> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>ShowSaveCheckbox</maml:name> <maml:description /> <dev:type> <maml:name>System.Management.Automation.SwitchParameter</maml:name> </dev:type> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>MaxAttempts</maml:name> <maml:description /> <command:parameterValue required="true" variableLength="false">int</command:parameterValue> <dev:type> <maml:name>System.Int32</maml:name> </dev:type> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Get-CredUICredential</maml:name> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="0" aliases="none"> <maml:name>UserName</maml:name> <maml:description /> <command:parameterValue required="true" variableLength="false">string</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> </dev:type> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>RetryAdminUser</maml:name> <maml:description /> <dev:type> <maml:name>System.Management.Automation.SwitchParameter</maml:name> </dev:type> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Message</maml:name> <maml:description /> <command:parameterValue required="true" variableLength="false">string</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> </dev:type> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Title</maml:name> <maml:description /> <command:parameterValue required="true" variableLength="false">string</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> </dev:type> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>ShowSaveCheckbox</maml:name> <maml:description /> <dev:type> <maml:name>System.Management.Automation.SwitchParameter</maml:name> </dev:type> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>MaxAttempts</maml:name> <maml:description /> <command:parameterValue required="true" variableLength="false">int</command:parameterValue> <dev:type> <maml:name>System.Int32</maml:name> </dev:type> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="0" aliases="none"> <maml:name>Credential</maml:name> <maml:description> <maml:para>Specifies a PSCredential object. If a value is supplied, it is returned unchanged and no dialog is shown.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">System.Management.Automation.PSCredential</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.PSCredential</maml:name> </dev:type> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="none"> <maml:name>MaxAttempts</maml:name> <maml:description> <maml:para>How many times the user may submit the dialog when `-RetryNormalUser` or `-RetryAdminUser` is used. Must be between 1 and 10. The default is 3. Cancel does not count as an attempt.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">System.Int32</command:parameterValue> <dev:type> <maml:name>System.Int32</maml:name> </dev:type> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="none"> <maml:name>Message</maml:name> <maml:description> <maml:para>Specifies the message that is displayed in the dialog box that prompts the user for credentials. Describe which script or function is requesting the credential.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> </dev:type> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="none"> <maml:name>RetryAdminUser</maml:name> <maml:description> <maml:para>Shows the dialog again until the password logs on as a member of this computer's Administrators group, the user cancels, or `-MaxAttempts` is used up. Mutually exclusive with `-RetryNormalUser`. Validation is a network logon against this computer or its domain; a failed attempt counts toward account lockout. A locked, disabled, or expired account stops immediately with an error rather than prompting again.</maml:para> </maml:description> <dev:type> <maml:name>System.Management.Automation.SwitchParameter</maml:name> </dev:type> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="none"> <maml:name>RetryNormalUser</maml:name> <maml:description> <maml:para>Shows the dialog again until the password logs on, the user cancels, or `-MaxAttempts` is used up. An administrator account is accepted. Mutually exclusive with `-RetryAdminUser`. Validation is a network logon against this computer or its domain; a failed attempt counts toward account lockout. A locked, disabled, or expired account stops immediately with an error rather than prompting again.</maml:para> </maml:description> <dev:type> <maml:name>System.Management.Automation.SwitchParameter</maml:name> </dev:type> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="none"> <maml:name>ShowSaveCheckbox</maml:name> <maml:description> <maml:para>Adds the native Save check box to the dialog box. Windows does not allow this checkbox's label to be customized, and checking it does not save anything by itself. When this switch is used, the cmdlet returns an object with Credential and Checkbox properties instead of a bare PSCredential.</maml:para> </maml:description> <dev:type> <maml:name>System.Management.Automation.SwitchParameter</maml:name> </dev:type> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="none"> <maml:name>Title</maml:name> <maml:description> <maml:para>Specifies the caption of the dialog box that prompts the user for credentials. This can be helpful with password management tools, such as KeePass, that match a window title to a password.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> </dev:type> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="0" aliases="none"> <maml:name>UserName</maml:name> <maml:description> <maml:para>Specifies the user name to pre-populate in the dialog's user name field. The user can still edit it or type a different name; this only sets the initial value.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> </dev:type> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>None</maml:name> </dev:type> <maml:description> <maml:para>You cannot pipe input to this cmdlet.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.Management.Automation.PSCredential</maml:name> </dev:type> <maml:description> <maml:para>A credential object containing the user name and password entered in the dialog box, or the Credential object that was passed in. Returned unless ShowSaveCheckbox is used.</maml:para> </maml:description> </command:returnValue> <command:returnValue> <dev:type> <maml:name>System.Management.Automation.PSObject</maml:name> </dev:type> <maml:description> <maml:para>Returned only when ShowSaveCheckbox is used. Has a Credential property (the PSCredential entered in the dialog box) and a Checkbox property (a boolean indicating whether the Save check box was checked).</maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para>This module is a maintained fork of the archived Get-WinCredential module by Zafer Balkan. `-RetryNormalUser` and `-RetryAdminUser` call `LogonUser` against this computer (or its domain). They cannot tell whether the password would work on some other host. Cancel still writes nothing; exhausting `-MaxAttempts` or a non-retryable logon error writes a non-terminating error.</maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>--------- Example 1 ---------</maml:title> <maml:introduction> <maml:para>Get-CredUICredential Gets a credential object and saves it in the `$creds` variable.</maml:para> </maml:introduction> <dev:code /> <dev:remarks /> </command:example> <command:example> <maml:title>--------- Example 2 ---------</maml:title> <maml:introduction> <maml:para>Get-CredUICredential -Message "Type your credentials" Shows the dialog with a custom message.</maml:para> </maml:introduction> <dev:code /> <dev:remarks /> </command:example> <command:example> <maml:title>--------- Example 3 ---------</maml:title> <maml:introduction> <maml:para>Get-CredUICredential -Title "Creds" -Message "Type your credentials" Shows the dialog with a custom window caption as well. The caption is useful with password managers such as KeePass that match a window title to decide which stored credentials to auto-type.</maml:para> </maml:introduction> <dev:code /> <dev:remarks /> </command:example> <command:example> <maml:title>--------- Example 4 ---------</maml:title> <maml:introduction> <maml:para>Get-CredUICredential -Credential $creds Returns `$creds` unchanged, without showing a dialog. This is what makes the cmdlet usable behind a `[Parameter()][PSCredential]$Credential` of your own: pass it through, and the user is only prompted when they did not supply one. Note that, exactly as with `Get-Credential`, the `Credential` parameter does not accept pipeline input. `$creds | Get-CredUICredential` does not bind.</maml:para> </maml:introduction> <dev:code /> <dev:remarks /> </command:example> <command:example> <maml:title>--------- Example 5 ---------</maml:title> <maml:introduction> <maml:para>$result = Get-CredUICredential -ShowSaveCheckbox $result.Credential $result.Checkbox Shows the dialog with a Save check box. Since there are now two things to report, the cmdlet returns an object with `Credential` and `Checkbox` properties instead of a bare `PSCredential`. The checkbox's label cannot be customized, and checking it does not save anything by itself; persisting the credential is left to the caller.</maml:para> </maml:introduction> <dev:code /> <dev:remarks /> </command:example> <command:example> <maml:title>--------- Example 6 ---------</maml:title> <maml:introduction> <maml:para>Get-CredUICredential -RetryNormalUser Shows the dialog, then checks the password against this computer (or its domain). A wrong password brings the dialog back with Windows' "incorrect" banner, up to three times by default. Cancel writes nothing; using up the attempts writes an error and returns nothing.</maml:para> </maml:introduction> <dev:code /> <dev:remarks /> </command:example> <command:example> <maml:title>--------- Example 7 ---------</maml:title> <maml:introduction> <maml:para>Get-CredUICredential -RetryAdminUser -MaxAttempts 5 Same as `-RetryNormalUser`, but the account must also be a member of the local Administrators group. A valid non-admin account is treated like a wrong password: the dialog comes back, this time saying elevation is required.</maml:para> </maml:introduction> <dev:code /> <dev:remarks /> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version</maml:linkText> <maml:uri>https://github.com/AlexCMarty/CredUICredential/blob/main/CredUICredential.md</maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> </helpItems> |