PSCredential, SecureString, SecretManagement, and Secret Storage

1. A secret has a lifecycle, not just a data type

A password, token, API key, private key, or connection string is sensitive because possession may grant capability. Security therefore depends on the whole lifecycle: generation, storage, retrieval, use, logging, rotation, revocation, and destruction. A special PowerShell type can reduce accidental exposure, but it cannot erase that lifecycle.

2. PSCredential packages identity plus a SecureString password

PSCredential is a .NET/PowerShell object containing a username and a SecureString password. Many cmdlets accept it so callers do not pass a plaintext password parameter. That is useful interface design, but it does not make a credential invulnerable inside a compromised process.

# Interactive entry avoids placing the password literal in source code.
$cred = Get-Credential -Message 'Enter a disposable training credential'

[pscustomobject]@{
    UserName     = $cred.UserName
    PasswordType = $cred.Password.GetType().FullName
}

# Do not print or serialize the password into logs.

3. SecureString reduces accidental exposure but is not a vault

SecureString obscures secret content from ordinary display and is still used by many PowerShell APIs. Current Microsoft guidance keeps it for compatibility but recommends avoiding password-centric designs for new development where stronger authentication methods are available.

Platform behavior matters: current documentation notes that the contents of SecureString are not encrypted on non-Windows systems. Even on Windows, a process that legitimately receives the secret may need to materialize it for an underlying API. Treat the type as an exposure-reduction mechanism, not a cryptographic vault boundary.

$secure = Read-Host 'Training secret (do not use a real password)' -AsSecureString
$secure.GetType().FullName
$secure.Length

# Avoid this except when an API absolutely requires plaintext:
# $plain = ConvertFrom-SecureString -SecureString $secure -AsPlainText

4. Persisted SecureString data has key-management consequences

ConvertFrom-SecureString can produce an encrypted representation. Without an explicit key, Windows uses DPAPI; with -Key/-SecureKey, AES is used. If you put the AES key next to the encrypted secret, you have merely moved the problem. On non-Windows, do not assume SecureString provides Windows DPAPI semantics.

# Inspect capabilities; do not persist a real credential for this lesson.
Get-Command ConvertFrom-SecureString,ConvertTo-SecureString |
    Select-Object Name,Source,Version

# If an application requires persisted encrypted data, define separately:
# - who owns the decryption key
# - where the key lives
# - how access is audited
# - how rotation and recovery work

5. SecretManagement provides a common vault abstraction

Microsoft.PowerShell.SecretManagement defines common commands such as Get-Secret, Set-Secret, and vault registration so scripts can depend on an abstraction rather than hard-code one vendor. Microsoft.PowerShell.SecretStore is Microsoft's local extension vault.

As of August 2026, Microsoft marks both modules feature complete: they continue to receive security/critical fixes but are no longer under active feature development. The current published versions are SecretManagement 1.1.2 and SecretStore 1.0.6. New architectures should also consider passwordless, federated identity, workload identity, and organization-standard vaults.

Get-Module -ListAvailable Microsoft.PowerShell.SecretManagement,Microsoft.PowerShell.SecretStore |
    Sort-Object Name,Version -Descending |
    Select-Object Name,Version,Path

if (Get-Command Get-SecretVault -ErrorAction SilentlyContinue) {
    Get-SecretVault | Select-Object Name,ModuleName,IsDefault,VaultParameters
}

6. Inject secrets at the boundary instead of embedding them

A reusable function should accept a credential, token provider, or secret value as input. It should not know that the caller read it from a developer prompt, CI secret store, managed identity exchange, or external vault. This is dependency injection applied to secrets.

function Invoke-TrainingApi {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory)]
        [uri]$Uri,

        [Parameter(Mandatory)]
        [string]$BearerToken
    )

    $headers = @{ Authorization = 'Bearer {0}' -f $BearerToken }
    Write-Verbose ('Calling {0}; Authorization header is REDACTED' -f $Uri.Host)

    # Invoke-RestMethod -Uri $Uri -Headers $headers -Method Get
    [pscustomobject]@{ Uri=$Uri.AbsoluteUri; Auth='Bearer ***REDACTED***' }
}

7. Environment variables are convenient injection channels, not secret vaults

CI systems commonly expose a secret to a step through an environment variable. That can be practical, but the value exists as plaintext in the process environment, may be inherited by child processes, and can leak through debug dumps or careless logging. Use the narrowest scope and shortest lifetime possible.

# Training placeholder only.
$env:TRAINING_API_TOKEN = 'not-a-real-secret'
try {
    $token = $env:TRAINING_API_TOKEN
    if ([string]::IsNullOrWhiteSpace($token)) { throw 'Token was not injected.' }

    [pscustomobject]@{
        Present  = $true
        Length   = $token.Length
        Redacted = ('{0}…{1}' -f $token.Substring(0,2), $token.Substring($token.Length-2))
    }
}
finally {
    Remove-Item Env:TRAINING_API_TOKEN -ErrorAction SilentlyContinue
}

8. Choose storage according to threat model and runtime

9. Redaction must happen before data reaches a log sink

Do not rely on “we will delete the log later.” A secret may already have reached a console transcript, CI artifact, SIEM, support ticket, or chat message. Build structured logging so sensitive fields are never emitted in the first place.

function Protect-LogValue {
    param([AllowNull()][string]$Value)
    if ([string]::IsNullOrEmpty($Value)) { return '[empty]' }
    return ('***REDACTED*** (length={0})' -f $Value.Length)
}

$fakeToken = 'training-only-value'
[pscustomobject]@{
    TimestampUtc = [datetime]::UtcNow
    Event        = 'ApiAuthPrepared'
    Token        = Protect-LogValue $fakeToken
} | ConvertTo-Json -Compress

10. Lab — secret-injection contract with no real secret

The lab simulates a CI runner. A fake secret enters through a process-scoped environment variable, is validated, passed to a function, redacted in diagnostics, and removed during cleanup.

function Get-TrainingCredentialEnvelope {
    [CmdletBinding()]
    param([Parameter(Mandatory)][string]$EnvironmentVariableName)

    $value = [Environment]::GetEnvironmentVariable($EnvironmentVariableName, 'Process')
    if ([string]::IsNullOrWhiteSpace($value)) {
        throw "Required secret '$EnvironmentVariableName' was not injected."
    }

    [pscustomobject]@{
        Name        = $EnvironmentVariableName
        SecretValue = $value          # return to trusted caller, never format/log it
        AuditValue  = '***REDACTED***'
    }
}

$env:TRAINING_SECRET = 'local-placeholder-only'
try {
    $envelope = Get-TrainingCredentialEnvelope -EnvironmentVariableName TRAINING_SECRET
    [pscustomobject]@{ Name=$envelope.Name; AuditValue=$envelope.AuditValue }
}
finally {
    Remove-Item Env:TRAINING_SECRET -ErrorAction SilentlyContinue
}

11. Common secret-handling failures

12. Verification checklist

• You can describe PSCredential and SecureString without overstating their protection.
• You know SecureString content is not encrypted on non-Windows systems.
• You understand the current feature-complete status of SecretManagement/SecretStore.
• You can inject a fake secret without embedding it in source.
• You can redact before logging.
• You can compare environment variables, CI stores, OS stores, and vaults by threat model.

13. Knowledge check

14. Summary and next bridge

Credentials and secrets should enter automation through explicit interfaces, exist for the shortest practical lifetime, and never appear in source or diagnostics. PSCredential and SecureString help with interfaces and accidental display, while vaults and workload identity address broader lifecycle problems. Lesson 3 now handles the other side of the boundary: untrusted inputs that must remain data rather than turning into code.

15. Authoritative references

• Microsoft Learn — PowerShell security features
• Microsoft Learn — ConvertTo-SecureString
• Microsoft Learn — SecretManagement/SecretStore overview
• Microsoft Learn — SecretManagement security concepts