How to Create a Credential Object in PowerShell

To create a credential object in PowerShell, turn the password into a SecureString and pass it with the user name to [pscredential]::new(). Any cmdlet with a -Credential parameter accepts the result:

$password   = ConvertTo-SecureString 'Demo-Passw0rd!' -AsPlainText -Force
$credential = [pscredential]::new('CONTOSO\svc_backup', $password)

$credential

Output:

UserName                               Password
--------                               --------
CONTOSO\svc_backup System.Security.SecureString

The password above is a throwaway demo value. In a real script, you’d ask for it with Get-Credential or load it from a protected store, both covered below.

I tested every example in PowerShell 7.6 and Windows PowerShell 5.1. A couple of commands behave differently between them, and I’ll show where.

Prompt for a credential with Get-Credential

The simplest and safest way to get a credential is to ask for it. Get-Credential shows a prompt and returns a PSCredential:

$credential = Get-Credential -UserName 'CONTOSO\svc_backup' -Message 'Enter the password for the backup account'

Windows PowerShell 5.1 shows a Windows sign-in dialog. PowerShell 7 asks in the console instead, and it adds a -Title parameter that 5.1 doesn’t have.

Nothing is written to disk, so this is the right choice for scripts that a person runs by hand.

Create a credential without a prompt

For automation, you build the object yourself. The first example used [pscredential]::new(). New-Object does the same thing and works in every version:

$password   = ConvertTo-SecureString 'Demo-Passw0rd!' -AsPlainText -Force
$credential = New-Object System.Management.Automation.PSCredential ('CONTOSO\svc_backup', $password)
$credential.UserName

Output:

CONTOSO\svc_backup

Why ConvertTo-SecureString needs -Force in Windows PowerShell 5.1

Windows PowerShell 5.1 refuses to convert plain text unless you add -Force:

ConvertTo-SecureString 'Demo-Passw0rd!' -AsPlainText

Output in Windows PowerShell 5.1:

ConvertTo-SecureString : The system cannot protect plain text input. To suppress this warning and convert the plain
text to a SecureString, reissue the command specifying the Force parameter. For more information ,type: get-help
ConvertTo-SecureString.
At C:\psfaqs\force51.ps1:1 char:1
+ ConvertTo-SecureString 'Demo-Passw0rd!' -AsPlainText
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : InvalidArgument: (:) [ConvertTo-SecureString], ArgumentException
    + FullyQualifiedErrorId : ImportSecureString_ForceRequired,Microsoft.PowerShell.Commands.ConvertToSecureStringComm
   and

PowerShell 7 dropped that requirement, so the same line works there. Keep -Force in scripts that must run in both.

Read the user name and password back

UserName is plain text. Password stays a SecureString. When an API needs the plain password, GetNetworkCredential() returns it along with the split user and domain:

$credential.UserName
$credential.Password
$credential.GetNetworkCredential().UserName
$credential.GetNetworkCredential().Domain
$credential.GetNetworkCredential().Password

Output:

CONTOSO\svc_backup
System.Security.SecureString
svc_backup
CONTOSO
Demo-Passw0rd!

Only unwrap the password at the moment you need it, and never write it to a log.

Use the credential with other cmdlets

Pass the object to any -Credential parameter. A few common ones:

Invoke-Command -ComputerName SRV01 -Credential $credential -ScriptBlock { Get-Service Spooler }
Enter-PSSession -ComputerName SRV01 -Credential $credential
New-PSDrive -Name Share -PSProvider FileSystem -Root \\FS01\Reports -Credential $credential
Invoke-RestMethod -Uri https://intranet.contoso.com/api/status -Credential $credential

Replace the server names with your own. The credential object is what authenticates each command, so you don’t type the password again.

Save a credential to a file and reuse it

For scheduled tasks, save the credential once with Export-Clixml and load it with Import-Clixml:

$credential | Export-Clixml -Path C:\psfaqs\svc_backup.cred.xml

# later, in another script (same user, same computer)
$saved = Import-Clixml -Path C:\psfaqs\svc_backup.cred.xml
$saved.UserName
$saved.GetNetworkCredential().Password

Output:

CONTOSO\svc_backup
Demo-Passw0rd!

The password in the XML file isn’t plain text. Windows encrypts it with the Data Protection API (DPAPI), tied to your user account and this computer:

Select-String -Path C:\psfaqs\svc_backup.cred.xml -Pattern '<S N="UserName">|<SS N="Password">' |
    ForEach-Object { $_.Line.Trim().Substring(0, [math]::Min(60, $_.Line.Trim().Length)) + '...' }

Output:

<S N="UserName">CONTOSO\svc_backup</S>...
<SS N="Password">01000000d08c9ddf0115d1118c7a00c04fc297eb010...

That’s also the limitation. Only the same user on the same computer can read it back. Save the file while signed in as the account that runs the scheduled task.

Store a password you can move between computers

When several machines need the same secret, encrypt it with your own AES key instead of DPAPI. Whoever has the key file can decrypt it, so lock that file down with NTFS permissions:

# create a 256-bit key once and protect the key file with NTFS permissions
$key = New-Object byte[] 32
[System.Security.Cryptography.RandomNumberGenerator]::Create().GetBytes($key)
[IO.File]::WriteAllBytes('C:\psfaqs\aes.key', $key)

$credential.Password | ConvertFrom-SecureString -Key $key | Set-Content C:\psfaqs\svc_backup.pwd

# on any computer that has the key file
$key2 = [IO.File]::ReadAllBytes('C:\psfaqs\aes.key')
$pw   = Get-Content C:\psfaqs\svc_backup.pwd | ConvertTo-SecureString -Key $key2
[pscredential]::new('CONTOSO\svc_backup', $pw).GetNetworkCredential().Password

Output:

Demo-Passw0rd!

This is more portable, but the key is now the secret. For anything important, use a vault instead.

Is it safe to store credentials in a PowerShell script?

Don’t put a plain-text password in a script, even for a quick test. Scripts end up in email, tickets and source control.

Microsoft’s recommended option is the SecretManagement module with a vault such as SecretStore or Azure Key Vault. Your script then asks the vault for the credential at run time:

Install-Module Microsoft.PowerShell.SecretManagement, Microsoft.PowerShell.SecretStore -Scope CurrentUser
Register-SecretVault -Name LocalVault -ModuleName Microsoft.PowerShell.SecretStore -DefaultVault
Set-Secret -Name SvcBackup -Secret (Get-Credential)

$credential = Get-Secret -Name SvcBackup

I didn’t run these commands on my test PC, because they install modules and create a vault. See Microsoft’s SecretManagement overview for setup details.

Frequently Asked Questions

Related admin tutorials:

• Convert a SecureString to plain text
• Run PowerShell as a different user
• PowerShell random password generator
• Enable WinRM using PowerShell