From 16b9d88f91069ee24ebb10c86ab0a95e6ac03c67 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Mon, 22 Jun 2026 15:27:19 -0500 Subject: [PATCH] Add docs from Learn prior to archiving the project --- .../Get-Secret.md | 161 +++++++++ .../Get-SecretInfo.md | 134 ++++++++ .../Get-SecretVault.md | 99 ++++++ .../Microsoft.PowerShell.SecretManagement.md | 64 ++++ .../Register-SecretVault.md | 253 +++++++++++++++ .../Remove-Secret.md | 166 ++++++++++ .../Set-Secret.md | 305 ++++++++++++++++++ .../Set-SecretInfo.md | 209 ++++++++++++ .../Set-SecretVaultDefault.md | 176 ++++++++++ .../Test-SecretVault.md | 78 +++++ .../Unlock-SecretVault.md | 112 +++++++ .../Unregister-SecretVault.md | 174 ++++++++++ learn-docs/README.md | 5 + .../understanding-secretmanagement.md | 58 ++++ .../get-started/using-secretstore.md | 111 +++++++ .../how-to/manage-secretstore.md | 158 +++++++++ .../how-to/using-azure-keyvault.md | 49 +++ .../how-to/using-secrets-in-automation.md | 95 ++++++ learn-docs/SecretManagement/overview.md | 72 +++++ .../SecretManagement/security-concepts.md | 45 +++ 20 files changed, 2524 insertions(+) create mode 100644 learn-docs/Microsoft.PowerShell.SecretManagement/Get-Secret.md create mode 100644 learn-docs/Microsoft.PowerShell.SecretManagement/Get-SecretInfo.md create mode 100644 learn-docs/Microsoft.PowerShell.SecretManagement/Get-SecretVault.md create mode 100644 learn-docs/Microsoft.PowerShell.SecretManagement/Microsoft.PowerShell.SecretManagement.md create mode 100644 learn-docs/Microsoft.PowerShell.SecretManagement/Register-SecretVault.md create mode 100644 learn-docs/Microsoft.PowerShell.SecretManagement/Remove-Secret.md create mode 100644 learn-docs/Microsoft.PowerShell.SecretManagement/Set-Secret.md create mode 100644 learn-docs/Microsoft.PowerShell.SecretManagement/Set-SecretInfo.md create mode 100644 learn-docs/Microsoft.PowerShell.SecretManagement/Set-SecretVaultDefault.md create mode 100644 learn-docs/Microsoft.PowerShell.SecretManagement/Test-SecretVault.md create mode 100644 learn-docs/Microsoft.PowerShell.SecretManagement/Unlock-SecretVault.md create mode 100644 learn-docs/Microsoft.PowerShell.SecretManagement/Unregister-SecretVault.md create mode 100644 learn-docs/README.md create mode 100644 learn-docs/SecretManagement/get-started/understanding-secretmanagement.md create mode 100644 learn-docs/SecretManagement/get-started/using-secretstore.md create mode 100644 learn-docs/SecretManagement/how-to/manage-secretstore.md create mode 100644 learn-docs/SecretManagement/how-to/using-azure-keyvault.md create mode 100644 learn-docs/SecretManagement/how-to/using-secrets-in-automation.md create mode 100644 learn-docs/SecretManagement/overview.md create mode 100644 learn-docs/SecretManagement/security-concepts.md diff --git a/learn-docs/Microsoft.PowerShell.SecretManagement/Get-Secret.md b/learn-docs/Microsoft.PowerShell.SecretManagement/Get-Secret.md new file mode 100644 index 0000000..495868c --- /dev/null +++ b/learn-docs/Microsoft.PowerShell.SecretManagement/Get-Secret.md @@ -0,0 +1,161 @@ +--- +external help file: Microsoft.PowerShell.SecretManagement.dll-Help.xml +Module Name: Microsoft.PowerShell.SecretManagement +ms.date: 05/23/2025 +online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.secretmanagement/get-secret?view=ps-modules&wt.mc_id=ps-gethelp +schema: 2.0.0 +--- + +# Get-Secret + +## SYNOPSIS +Finds and returns a secret by name from registered vaults. + +## SYNTAX + +### NameParameterSet (Default) + +``` +Get-Secret [-Name] [[-Vault] ] [-AsPlainText] [] +``` + +### InfoParameterSet + +``` +Get-Secret [-InputObject] [-AsPlainText] [] +``` + +## DESCRIPTION + +This cmdlet finds and returns the first secret that matches the provided name. If a vault name is +specified, only that vault is searched. Otherwise, it searches all vaults and returns the first +matching result. If the vault registry has a default vault, the cmdlet searches that vault before +any other registered vault. Secrets that are **String** or **SecureString** types are returned as +**SecureString** objects by default. + +## EXAMPLES + +### Example 1 + +```powershell +Get-Secret -Name Secret1 -Vault CredMan +Get-Secret -Name Secret1 -Vault CredMan -AsPlainText +``` + +```output +System.Security.SecureString +PlainTextSecretString +``` + +This example searches for a secret with the name `Secret1`, which is a **String** type secret. The +first command returns the secret as a **SecureString** object. The second command uses the +**AsPlainText** parameter to return the secret as a **String** object instead, displaying in the +console as plain text. + +### Example 2 + +```powershell +Get-SecretInfo -Name Secret2 -Vault SecretStore | + Get-Secret -AsPlainText +``` + +This example retrieves secret information for the secret named `Secret2` in the vault named +`SecretStore`. It then sends the result through the pipeline to `Get-Secret`, which searches for the +secret and returns it as plain text. + +## PARAMETERS + +### -AsPlainText + +Specifies that a secret whose type is **String** or **SecureString** should be returned as a +**String** (in plain text) instead of a **SecureString**. If the secret being retrieved isn't a +**String** or **SecureString**, this parameter has no effect. + +> [!CAUTION] +> To ensure security, you should avoid using plaintext strings whenever possible. + +```yaml +Type: System.Management.Automation.SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -InputObject + +Specifies a **SecretInformation** object representing a vault secret instead of specifying the +**Name** and **Vault** parameters. You can get a **SecretInformation** object with the +`Get-SecretInfo` cmdlet. + +```yaml +Type: Microsoft.PowerShell.SecretManagement.SecretInformation +Parameter Sets: InfoParameterSet +Aliases: + +Required: True +Position: 0 +Default value: None +Accept pipeline input: True (ByValue) +Accept wildcard characters: False +``` + +### -Name + +Specifies the name of the secret to retrieve. Wildcard characters aren't permitted. + +```yaml +Type: System.String +Parameter Sets: NameParameterSet +Aliases: + +Required: True +Position: 0 +Default value: None +Accept pipeline input: True (ByValue) +Accept wildcard characters: False +``` + +### -Vault + +Specifies the name of the registered vault to retrieve the secret from. If no vault name is +specified, then all registered vaults are searched. If the vault registry has a default vault and +this parameter isn't specified, then the default vault is searched before the other registered +vaults. + +```yaml +Type: System.String +Parameter Sets: NameParameterSet +Aliases: + +Required: False +Position: 1 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### System.String + +### Microsoft.PowerShell.SecretManagement.SecretInformation + +## OUTPUTS + +### System.Object + +## NOTES + +## RELATED LINKS diff --git a/learn-docs/Microsoft.PowerShell.SecretManagement/Get-SecretInfo.md b/learn-docs/Microsoft.PowerShell.SecretManagement/Get-SecretInfo.md new file mode 100644 index 0000000..ee8fd51 --- /dev/null +++ b/learn-docs/Microsoft.PowerShell.SecretManagement/Get-SecretInfo.md @@ -0,0 +1,134 @@ +--- +external help file: Microsoft.PowerShell.SecretManagement.dll-Help.xml +Module Name: Microsoft.PowerShell.SecretManagement +ms.date: 05/23/2025 +online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.secretmanagement/get-secretinfo?view=ps-modules&wt.mc_id=ps-gethelp +schema: 2.0.0 +--- + +# Get-SecretInfo + +## SYNOPSIS +Finds and returns metadata information about secrets in registered vaults. + +## SYNTAX + +``` +Get-SecretInfo [[-Name] ] [[-Vault] ] [] +``` + +## DESCRIPTION + +This cmdlet finds and returns information about secrets in registered vaults. By default, it returns +information for every secret in all registered vaults. + +## EXAMPLES + +### Example 1 + +```powershell +Get-SecretInfo -Name * +``` + +```output +Name Type VaultName +---- ---- --------- +Secret1 String LocalStore +Secret2 ByteArray LocalStore +Secret3 SecureString LocalStore +Secret4 PSCredential LocalStore +Secret5 Hashtable LocalStore +Secret6 ByteArray CredMan +``` + +This example specifies the **Name** parameter as a single wildcard (`*`) character to return +metadata for all stored secrets. There are two registered vaults, `LocalStore` and `CredMan`. There +are six **SecretInformation** objects returned from the two vaults. + +The output objects every valid type a secret can be: + +- **ByteArray** +- **Hashtable** +- **PSCredential** +- **SecureString** +- **String** + +### Example 2 + +```powershell +Get-SecretInfo -Name SecretWithMetadata | Select-Object -ExpandProperty Metadata +``` + +```output +Key Value +--- ----- +Environment Development +Expiration 5/1/2022 12:00:00 AM +GroupNumber 7 +``` + +This example retrieves the `SecretWithMetadata` secret and displays its metadata. The entries in the +hashtable show every valid type metadata values can be: + +- **String** +- **DateTime** +- **Int** + +## PARAMETERS + +### -Name + +Specifies the name of a secret. This cmdlet only gets metadata for secrets that have the specified +name. Enter a name or name pattern. Wildcard characters are permitted. + +If the **Name** parameter isn't specified, this cmdlet returns the metadata for all stored secrets. + +```yaml +Type: System.String +Parameter Sets: (All) +Aliases: + +Required: False +Position: 0 +Default value: None +Accept pipeline input: False +Accept wildcard characters: True +``` + +### -Vault + +Specifies the name of a vault to search for secret metadata. Wildcard characters aren't permitted. + +If the **Vault** parameter isn't specified, this cmdlet searches for metadata in all registered +vaults. + +```yaml +Type: System.String +Parameter Sets: (All) +Aliases: + +Required: False +Position: 1 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### None + +## OUTPUTS + +### Microsoft.PowerShell.SecretManagement.SecretInformation + +## NOTES + +## RELATED LINKS diff --git a/learn-docs/Microsoft.PowerShell.SecretManagement/Get-SecretVault.md b/learn-docs/Microsoft.PowerShell.SecretManagement/Get-SecretVault.md new file mode 100644 index 0000000..5550aa9 --- /dev/null +++ b/learn-docs/Microsoft.PowerShell.SecretManagement/Get-SecretVault.md @@ -0,0 +1,99 @@ +--- +external help file: Microsoft.PowerShell.SecretManagement.dll-Help.xml +Module Name: Microsoft.PowerShell.SecretManagement +ms.date: 05/23/2025 +online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.secretmanagement/get-secretvault?view=ps-modules&wt.mc_id=ps-gethelp +schema: 2.0.0 +--- + +# Get-SecretVault + +## SYNOPSIS +Finds and returns registered vault information. + +## SYNTAX + +``` +Get-SecretVault [[-Name] ] [] +``` + +## DESCRIPTION + +This cmdlet finds and returns information about registered vaults. By default, it returns +information for every registered vault. + +## EXAMPLES + +### Example 1 + +```powershell +Get-SecretVault +``` + +```output +VaultName ModuleName IsDefaultVault +--------- ---------- -------------- +CredMan Microsoft.PowerShell.CredManStore False +LocalStore Microsoft.PowerShell.SecretStore True +``` + +This example runs the command without any parameters to return information on all registered vaults. +The `LocalStore` vault is shown to be set as the default vault. + +### Example 2 + +```powershell +Get-SecretVault -Name LocalStore | Format-List -Property * +``` + +```output +Name : LocalStore +ModuleName : Microsoft.PowerShell.SecretStore +ModulePath : C:\Users\User01\Documents\PowerShell\Modules\Microsoft.PowerShell.SecretStore +Description : Personal secrets for non-production use. +VaultParameters : {} +IsDefault : True +``` + +This example shows additional information about the `LocalStore` vault. + +## PARAMETERS + +### -Name + +Specifies the name of a vault. This cmdlet only gets information for vaults that have the specified +name. Enter a name or name pattern. Wildcard characters are permitted. + +If the **Name** parameter isn't specified, this cmdlet returns the information for all registered +vaults. + +```yaml +Type: System.String[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: 0 +Default value: None +Accept pipeline input: False +Accept wildcard characters: True +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### None + +## OUTPUTS + +### Microsoft.PowerShell.SecretManagement.SecretVaultInfo + +## NOTES + +## RELATED LINKS diff --git a/learn-docs/Microsoft.PowerShell.SecretManagement/Microsoft.PowerShell.SecretManagement.md b/learn-docs/Microsoft.PowerShell.SecretManagement/Microsoft.PowerShell.SecretManagement.md new file mode 100644 index 0000000..2833afe --- /dev/null +++ b/learn-docs/Microsoft.PowerShell.SecretManagement/Microsoft.PowerShell.SecretManagement.md @@ -0,0 +1,64 @@ +--- +Module Name: Microsoft.PowerShell.SecretManagement +Module Guid: a5c858f6-4a8e-41f1-b1ee-0ff8f6ad69d3 +ms.date: 05/23/2025 +Download Help Link: https://aka.ms/ps-modules-help +Help Version: 0.1.0.0 +Locale: en-US +--- + +# Microsoft.PowerShell.SecretManagement Module + +## Description + +PowerShell SecretManagement module provides a convenient way for a user to store and retrieve +secrets. The secrets are stored in SecretManagement extension vaults. An extension vault is a +PowerShell module that has been registered to SecretManagement, and exports five module functions +required by SecretManagement. An extension vault can store secrets locally or remotely. Extension +vaults are registered to the current logged in user context, and are available only to that user. + +## Microsoft.PowerShell.SecretManagement Cmdlets + +### [Get-Secret](Get-Secret.md) + +Finds and returns a secret by name from registered vaults. + +### [Get-SecretInfo](Get-SecretInfo.md) + +Finds and returns metadata information about secrets in registered vaults. + +### [Get-SecretVault](Get-SecretVault.md) + +Finds and returns registered vault information. + +### [Register-SecretVault](Register-SecretVault.md) + +Registers a SecretManagement extension vault module for the current user. + +### [Remove-Secret](Remove-Secret.md) + +Removes a secret from a specified registered extension vault. + +### [Set-Secret](Set-Secret.md) + +Adds a secret to a SecretManagement registered vault. + +### [Set-SecretInfo](Set-SecretInfo.md) + +Adds or replaces additional secret metadata to a secret currently stored in a vault. + +### [Set-SecretVaultDefault](Set-SecretVaultDefault.md) + +Sets the provided vault name as the default vault for the current user. + +### [Test-SecretVault](Test-SecretVault.md) + +Runs an extension vault self test. + +### [Unlock-SecretVault](Unlock-SecretVault.md) + +Unlocks an extension vault so that it can be access in the current session. + +### [Unregister-SecretVault](Unregister-SecretVault.md) + +Un-registers an extension vault from SecretManagement for the current user. diff --git a/learn-docs/Microsoft.PowerShell.SecretManagement/Register-SecretVault.md b/learn-docs/Microsoft.PowerShell.SecretManagement/Register-SecretVault.md new file mode 100644 index 0000000..c5ff83a --- /dev/null +++ b/learn-docs/Microsoft.PowerShell.SecretManagement/Register-SecretVault.md @@ -0,0 +1,253 @@ +--- +external help file: Microsoft.PowerShell.SecretManagement.dll-Help.xml +Module Name: Microsoft.PowerShell.SecretManagement +ms.date: 05/23/2025 +online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.secretmanagement/register-secretvault?view=ps-modules&wt.mc_id=ps-gethelp +schema: 2.0.0 +--- + +# Register-SecretVault + +## SYNOPSIS +Registers a SecretManagement extension vault module for the current user. + +## SYNTAX + +``` +Register-SecretVault [-ModuleName] [[-Name] ] [-VaultParameters ] + [-DefaultVault] [-AllowClobber] [-PassThru] [-Description ] [-WhatIf] [-Confirm] + [] +``` + +## DESCRIPTION + +This cmdlet adds a **SecretManagement** extension vault to the current user's vault registry. An +extension vault is a PowerShell module that conforms to the required extension vault format. This +cmdlet verifies that the specified module meets conformance requirements before adding it to the +extension vault registry. Extension vaults are registered to the current user and don't affect +other user vault registrations. + +The first vault registered with this cmdlet is automatically defined as the default vault even if +the **DefaultVault** parameter isn't specified. + +## EXAMPLES + +### Example 1 + +```powershell +Register-SecretVault -Name LocalStore -ModuleName Microsoft.PowerShell.SecretStore -DefaultVault +Get-SecretVault +``` + +```output +VaultName ModuleName IsDefaultVault +--------- ---------- -------------- +CredMan Microsoft.PowerShell.CredManStore False +LocalStore Microsoft.PowerShell.SecretStore True +``` + +This example registers a **Microsoft.PowerShell.SecretStore** extension vault for the current user. +It uses the **DefaultVault** parameter to make the registered vault the default vault for the user. +`Get-SecretVault` lists all registered vaults for the user, verifying the vault was registered and +set as the default vault. + +### Example 2 + +```powershell +$parameters = @{ + Name = 'Azure' + ModuleName = 'Az.KeyVault' + VaultParameters = @{ + AZKVaultName = 'AzureKeyVault' + SubscriptionId = (Get-AzContext).Subscription.Id + } + DefaultVault = $true +} +Register-SecretVault @parameters +Get-SecretVault +``` + +```Output +Name ModuleName IsDefaultVault +---- ---------- -------------- +Azure Az.KeyVault True +``` + +This example registers an **Az.KeyVault** extension vault for the current user. The +[Az.KeyVault](https://www.powershellgallery.com/packages/Az.KeyVault/) module needs to be installed +on prior. For the **VaultParameters**: + +- `AZKVaultName` specifies the name of the Key Vault on Azure +- `SubscriptionId` specifies the ID of the subscription where the Key Vault is created in + +## PARAMETERS + +### -AllowClobber + +If specified, allows the cmdlet to overwrite an existing registered extension vault with the same +name. + +```yaml +Type: System.Management.Automation.SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -DefaultVault + +If specified, sets the new extension vault as the default vault for the current user. + +```yaml +Type: System.Management.Automation.SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Description + +Describes the vault. This value is included in the vault registry information. + +```yaml +Type: System.String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ModuleName + +Specifies the name of the PowerShell module that implements the extension vault. Enter the name of a +module or the path to the module. If you specify a name, PowerShell searches for it in the known +module paths. If you specify a path, PowerShell searches that path for the module. + +```yaml +Type: System.String +Parameter Sets: (All) +Aliases: + +Required: True +Position: 1 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Name + +Specifies the name of the extension vault. If no name is specified, the module name is used as the +vault name. + +```yaml +Type: System.String +Parameter Sets: (All) +Aliases: + +Required: False +Position: 0 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -PassThru + +Indicates that the cmdlet should return the **SecretVaultInfo** object for the successfully +registered extension vault. By default this cmdlet doesn't return any output. + +```yaml +Type: System.Management.Automation.SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -VaultParameters + +Specifies a **Hashtable** object containing optional key-value pairs used as parameters by the +extension vault. These parameters are optional. Consult the documentation of the vault extension +module to see what values are required. + +```yaml +Type: System.Collections.Hashtable +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Confirm + +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: System.Management.Automation.SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -WhatIf + +Shows what would happen if the cmdlet runs. The cmdlet isn't run. + +```yaml +Type: System.Management.Automation.SwitchParameter +Parameter Sets: (All) +Aliases: wi + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### None + +## OUTPUTS + +### None + +## NOTES + +## RELATED LINKS diff --git a/learn-docs/Microsoft.PowerShell.SecretManagement/Remove-Secret.md b/learn-docs/Microsoft.PowerShell.SecretManagement/Remove-Secret.md new file mode 100644 index 0000000..d5e6f0f --- /dev/null +++ b/learn-docs/Microsoft.PowerShell.SecretManagement/Remove-Secret.md @@ -0,0 +1,166 @@ +--- +external help file: Microsoft.PowerShell.SecretManagement.dll-Help.xml +Module Name: Microsoft.PowerShell.SecretManagement +ms.date: 05/23/2025 +online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.secretmanagement/remove-secret?view=ps-modules&wt.mc_id=ps-gethelp +schema: 2.0.0 +--- + +# Remove-Secret + +## SYNOPSIS +Removes a secret from a specified registered extension vault. + +## SYNTAX + +### NameParameterSet (Default) + +``` +Remove-Secret [-Name] [-Vault] [-WhatIf] [-Confirm] [] +``` + +### InfoParameterSet + +``` +Remove-Secret [-InputObject] [-WhatIf] [-Confirm] [] +``` + +## DESCRIPTION + +Removes a secret by name from a registered extension vault. Both the secret name and extension vault +name must be provided. + +## EXAMPLES + +### Example 1 + +```powershell +Remove-Secret -Name secretTest -Vault CredMan +Get-Secret -Name secretTest -Vault CredMan +``` + +```output +Get-Secret: The secret secretTest wasn't found. +``` + +This example removes the `secretTest` secret from the `CredMan` vault. The `Get-Secret` command +verifies that the secret no longer exists in the vault. + +### Example 2 + +```powershell +Get-SecretInfo -Name Secret2 -Vault CredMan | Remove-Secret +Get-Secret -Name Secret2 -Vault CredMan +``` + +```output +Get-Secret: The secret Secret2 wasn't found. +``` + +This example removes the `Secret2` secret from the `CredMan` vault. `Get-SecretInfo` retrieves the +information for the secret and sends the result through the pipeline to `Remove-Secret`. +`Get-Secret` verifies that the secret no longer exists in the vault. + +## PARAMETERS + +### -InputObject + +Specifies a **SecretInformation** object that describes a vault secret. + +```yaml +Type: Microsoft.PowerShell.SecretManagement.SecretInformation +Parameter Sets: InfoParameterSet +Aliases: + +Required: True +Position: 0 +Default value: None +Accept pipeline input: True (ByValue) +Accept wildcard characters: False +``` + +### -Name + +Specifies the name of the secret to remove. Wildcard characters (`*`) aren't permitted. + +```yaml +Type: System.String +Parameter Sets: NameParameterSet +Aliases: + +Required: True +Position: 0 +Default value: None +Accept pipeline input: True (ByValue) +Accept wildcard characters: False +``` + +### -Vault + +Specifies the name of the vault to remove the secret from. Wildcard characters (`*`) aren't +permitted. + +```yaml +Type: System.String +Parameter Sets: NameParameterSet +Aliases: + +Required: True +Position: 1 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Confirm + +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: System.Management.Automation.SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -WhatIf + +Shows what would happen if the cmdlet runs. The cmdlet isn't run. + +```yaml +Type: System.Management.Automation.SwitchParameter +Parameter Sets: (All) +Aliases: wi + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### System.String + +### Microsoft.PowerShell.SecretManagement.SecretInformation + +## OUTPUTS + +### None + +## NOTES + +## RELATED LINKS diff --git a/learn-docs/Microsoft.PowerShell.SecretManagement/Set-Secret.md b/learn-docs/Microsoft.PowerShell.SecretManagement/Set-Secret.md new file mode 100644 index 0000000..fb4a3ce --- /dev/null +++ b/learn-docs/Microsoft.PowerShell.SecretManagement/Set-Secret.md @@ -0,0 +1,305 @@ +--- +external help file: Microsoft.PowerShell.SecretManagement.dll-Help.xml +Module Name: Microsoft.PowerShell.SecretManagement +ms.date: 05/23/2025 +online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.secretmanagement/set-secret?view=ps-modules&wt.mc_id=ps-gethelp +schema: 2.0.0 +--- + +# Set-Secret + +## SYNOPSIS +Adds a secret to a SecretManagement registered vault. + +## SYNTAX + +### SecureStringParameterSet (Default) + +``` +Set-Secret [-Name] -SecureStringSecret [[-Vault] ] + [[-Metadata] ] [-NoClobber] [-WhatIf] [-Confirm] [] +``` + +### ObjectParameterSet + +``` +Set-Secret [-Name] -Secret [[-Vault] ] [[-Metadata] ] + [-NoClobber] [-WhatIf] [-Confirm] [] +``` + +### SecretInfoParameterSet + +``` +Set-Secret -SecretInfo [-Vault] [-NoClobber] [-WhatIf] [-Confirm] + [] +``` + +## DESCRIPTION + +This cmdlet adds a secret value by name to a vault. When no vault name is specified, the secret is +added to the default vault. If a secret with that name exists, it's overwritten. Additional data +can be included with the secret if supported by the extension vault. + +The default parameter set takes a **SecureString** object. If you run the command without specifying +the secret value, the cmdlet prompts you to enter a **SecureString**. The text of the string isn't +visible in the console. + +## EXAMPLES + +### Example 1 + +```powershell +Set-Secret -Name Secret1 -Secret "SecretValue" +Get-Secret -Name Secret1 +``` + +```output +System.Security.SecureString +``` + +This example adds a secret named `Secret1` with a plain text value of `SecretValue`. Since no vault +name was specified, the secret is added to the current user's default vault. `Get-Secret` shows the +secret was added. + +### Example 2 + +```powershell +PS C:\> Set-Secret -Name Secret2 -Vault LocalStore + +cmdlet Set-Secret at command pipeline position 1 +Supply values for the following parameters: +SecureStringSecret: *********** + +PS C:\> Get-Secret -Name Secret2 +System.Security.SecureString +``` + +This example adds a secret named `Secret2` to the `LocalStore` vault. Since no secret value was +provided, the cmdlet prompts for a **SecureString** value. The console hides the string value as it +is typed. `Get-Secret` shows the secret was added. + +### Example 3 + +```powershell +$Metadata = @{ Expiration = ([datetime]::new(2022, 5, 1)) } +Set-Secret -Name TargetSecret -Secret $targetToken -Vault LocalStore -Metadata $Metadata +Get-SecretInfo -Name TargetSecret | Select-Object Name,Metadata +``` + +```output +Name Metadata +---- -------- +TargetSecret {[Expiration, 5/1/2022 12:00:00 AM]} +``` + +This example adds a secret named `TargetSecret` to the `LocalStore` vault with metadata indicating +the secret's expiration date. `Get-SecretInfo` retrieves the metadata for the newly created secret. + +### Example 4 + +```powershell +$Metadata = @{ Expiration = ([datetime]::new(2022, 5, 1)) } +Set-Secret -Name PublishSecret -Secret $targetToken -Vault LocalStore2 -Metadata $Metadata +``` + +```output +Set-Secret: Can't store secret PublishSecret. Vault LocalStore2 doesn't support secret metadata. +``` + +This example adds a secret named `PublishSecret` to the `LocalStore2` vault with extra metadata. +However, vault `LocalStore2` doesn't support secret metadata and the operation returns an error. + +## PARAMETERS + +### -Metadata + +Specifies a **Hashtable** containing key-value pairs to associate with the secret in the vault. The +specified extension vault might not support secret metadata. If the vault doesn't support metadata, +the operation fails and returns an error. The values of any metadata in the hashtable must be one of +the following types: + +- **string** +- **int** +- **DateTime** + +Metadata isn't stored securely in a vault. Metadata shouldn't contain sensitive information. + +```yaml +Type: System.Collections.Hashtable +Parameter Sets: SecureStringParameterSet, ObjectParameterSet +Aliases: + +Required: False +Position: 1 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Name + +Specifies the name of the secret to add or update. Wildcard characters (`*`) aren't permitted. + +```yaml +Type: System.String +Parameter Sets: SecureStringParameterSet, ObjectParameterSet +Aliases: + +Required: True +Position: 0 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -NoClobber + +Causes the command to return an error if a secret with the same name already exists in the vault. By +default, this cmdlet updates the secret with the new value if it already exists. + +```yaml +Type: System.Management.Automation.SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Secret + +Specifies the value of the secret. The object must be one of the supported types: + +- **Byte[]** +- **String** +- **SecureString** +- **PSCredential** +- **Hashtable** + +```yaml +Type: System.Object +Parameter Sets: ObjectParameterSet +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: True (ByValue) +Accept wildcard characters: False +``` + +### -SecretInfo + +Specifies a **SecretInformation** object describing a stored secret returned by `Get-SecretInfo`. +This enables copying secrets from one extension vault to another. + +```yaml +Type: Microsoft.PowerShell.SecretManagement.SecretInformation +Parameter Sets: SecretInfoParameterSet +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: True (ByValue) +Accept wildcard characters: False +``` + +### -SecureStringSecret + +Specifies the value of the secret as a **SecretString** object. + +```yaml +Type: System.Security.SecureString +Parameter Sets: SecureStringParameterSet +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: True (ByValue) +Accept wildcard characters: False +``` + +### -Vault + +Specifies the name of the vault to add or update the secret in. Wildcard characters (`*`) aren't +permitted. By default, the secret is added or updated in the current user's default vault. + +```yaml +Type: System.String +Parameter Sets: SecureStringParameterSet, ObjectParameterSet +Aliases: + +Required: False +Position: 2 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Confirm + +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: System.Management.Automation.SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -WhatIf + +Shows what would happen if the cmdlet runs. The cmdlet isn't run. + +```yaml +Type: System.Management.Automation.SwitchParameter +Parameter Sets: (All) +Aliases: wi + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### System.Collections.Hashtable + +## OUTPUTS + +### None + +## NOTES + +When you run `Set-Secret` with the **Name** parameter to specify the name of the secret, the cmdlet +calls `GetSecret()` that's implemented by the vault extension. `Set-Secret` passes through the name +as provided by the user. The vault extension looks up the secret by that name. If `GetSecret()` +returns a match, `Set-Secret` overwrites the secret unless you use the **NoClobber** parameter. The +vault extension always writes the secret information it receives. + +It's up to the vault extension implementation to decide whether or not to use a case-sensitive +comparison on the name. For example, secret names in the **Microsoft.PowerShell.SecretStore** +extension vault are case-insensitive. If the name you pass to `Set-Secret` differs only by case with +the name of an existing secret in a SecretStore vault, the name is overwritten with the new value +you provided. + +## RELATED LINKS diff --git a/learn-docs/Microsoft.PowerShell.SecretManagement/Set-SecretInfo.md b/learn-docs/Microsoft.PowerShell.SecretManagement/Set-SecretInfo.md new file mode 100644 index 0000000..4ea32be --- /dev/null +++ b/learn-docs/Microsoft.PowerShell.SecretManagement/Set-SecretInfo.md @@ -0,0 +1,209 @@ +--- +external help file: Microsoft.PowerShell.SecretManagement.dll-Help.xml +Module Name: Microsoft.PowerShell.SecretManagement +ms.date: 05/23/2025 +online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.secretmanagement/set-secretinfo?view=ps-modules&wt.mc_id=ps-gethelp +schema: 2.0.0 +--- + +# Set-SecretInfo + +## SYNOPSIS +Adds or replaces additional secret metadata to a secret currently stored in a vault. + +## SYNTAX + +### NameParameterSet (Default) + +``` +Set-SecretInfo [-Name] [-Metadata] [[-Vault] ] + [-WhatIf] [-Confirm] [] +``` + +### InfoParameterSet + +``` +Set-SecretInfo [-Metadata] -InputObject + [-WhatIf] [-Confirm] [] +``` + +## DESCRIPTION + +This cmdlet adds additional secret metadata to an existing secret. Metadata support is an optional +feature for an extension vault. The command throws an error if a vault doesn't support secret +metadata. Metadata is a Hashtable object containing Name/Value pairs. The metadata is stored +unencrypted. You shouldn't store sensitive information in the metadata. + +## EXAMPLES + +### Example 1 + +```powershell +Set-SecretInfo -Name Secret1 -Vault Vault1 -Metadata @{ + Expiration = ([datetime]::new(2022, 5, 1)) +} +Get-SecretInfo -Name Secret1 -Vault Vault1 | + Select-Object Name,Metadata +``` + +```output +Name Metadata +---- -------- +Secret1 {[Expiration, 5/1/2022 12:00:00 AM]} +``` + +This example adds metadata to the `Secret1` secret stored in `Vault1` vault. `Get-SecretInfo` +retrieves the metadata for `Secret1` to show the added metadata. + +### Example 2 + +```powershell +Set-SecretInfo -Name Secret2 -Vault Vault2 -Metadata @{ + Expiration = ([datetime]::new(2022, 5, 1)) +} +``` + +```output +Set-SecretInfo: Can't set secret metadata Secret2. Vault Vault2 doesn't support secret metadata. +``` + +This example adds metadata to the `Secret2` secret stored in `Vault2` vault. However, `Vault2` does +not support metadata. The command fails and returns an error. + +### Example 3 + +```powershell +Get-SecretInfo -Name Secret3 | + Set-SecretInfo -Metadata @{ Created = (Get-Date) } +``` + +This example pipes a **SecretInformation** object to the `Set-SecretInfo` command and adds metadata +to the associated secret. + +## PARAMETERS + +### -InputObject + +This parameter takes a **SecretInformation** object that defines the secret to be updated. + +```yaml +Type: Microsoft.PowerShell.SecretManagement.SecretInformation +Parameter Sets: InfoParameterSet +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: True (ByValue) +Accept wildcard characters: False +``` + +### -Metadata + +Specifies a **Hashtable** containing key-value pairs to associate with the secret in the vault. The +specified extension vault may not support secret metadata. If the vault doesn't support metadata, +the operation fails and returns an error. The values of any metadata in the hashtable must be one of +the following types: + +- **string** +- **int** +- **DateTime** + +Metadata isn't stored securely in a vault. Metadata shouldn't contain sensitive information. + +```yaml +Type: System.Collections.Hashtable +Parameter Sets: NameParameterSet, System.Collections.Hashtable +Aliases: + +Required: True +Position: 1 +Default value: None +Accept pipeline input: True (ByValue) +Accept wildcard characters: False +``` + +### -Name + +Specifies the name of the secret to add metadata to. Wildcard characters (`*`) aren't permitted. + +```yaml +Type: System.String +Parameter Sets: NameParameterSet +Aliases: + +Required: True +Position: 0 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Vault + +Specifies the name of the vault containing the secret to add or update the metadata for. Wildcard +characters (`*`) aren't permitted. By default, this cmdlet looks for the secret in the current +user's default vault. + +```yaml +Type: System.String +Parameter Sets: NameParameterSet +Aliases: + +Required: False +Position: 2 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Confirm + +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: System.Management.Automation.SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -WhatIf + +Shows what would happen if the cmdlet runs. The cmdlet isn't run. + +```yaml +Type: System.Management.Automation.SwitchParameter +Parameter Sets: (All) +Aliases: wi + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### System.Collections.Hashtable + +## OUTPUTS + +### None + +## NOTES + +## RELATED LINKS diff --git a/learn-docs/Microsoft.PowerShell.SecretManagement/Set-SecretVaultDefault.md b/learn-docs/Microsoft.PowerShell.SecretManagement/Set-SecretVaultDefault.md new file mode 100644 index 0000000..069e6c4 --- /dev/null +++ b/learn-docs/Microsoft.PowerShell.SecretManagement/Set-SecretVaultDefault.md @@ -0,0 +1,176 @@ +--- +external help file: Microsoft.PowerShell.SecretManagement.dll-Help.xml +Module Name: Microsoft.PowerShell.SecretManagement +ms.date: 05/23/2025 +online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.secretmanagement/set-secretvaultdefault?view=ps-modules&wt.mc_id=ps-gethelp +schema: 2.0.0 +--- + +# Set-SecretVaultDefault + +## SYNOPSIS +Sets the provided vault name as the default vault for the current user. + +## SYNTAX + +### NameParameterSet (Default) + +``` +Set-SecretVaultDefault [-Name] [-WhatIf] [-Confirm] [] +``` + +### SecretVaultParameterSet + +``` +Set-SecretVaultDefault [-SecretVault] [-WhatIf] [-Confirm] [] +``` + +### ClearParameterSet + +``` +Set-SecretVaultDefault [-ClearDefault] [-WhatIf] [-Confirm] [] +``` + +## DESCRIPTION + +This cmdlet updates the vault registry to set the provided vault name as the default vault. Only one +registered vault can be the default vault. + +## EXAMPLES + +### Example 1 + +```powershell +PS C:\> Get-SecretVault + +VaultName ModuleName IsDefaultVault +--------- ---------- -------------- +CredMan Microsoft.PowerShell.CredManStore False +LocalStore Microsoft.PowerShell.SecretStore True + +PS C:\> Set-SecretVaultDefault -Name CredMan +PS C:\> Get-SecretVault + +VaultName ModuleName IsDefaultVault +--------- ---------- -------------- +CredMan Microsoft.PowerShell.CredManStore True +LocalStore Microsoft.PowerShell.SecretStore False + +PS C:\> Set-SecretVaultDefault -ClearDefault +PS C:\> Get-SecretVault + +VaultName ModuleName IsDefaultVault +--------- ---------- -------------- +CredMan Microsoft.PowerShell.CredManStore False +LocalStore Microsoft.PowerShell.SecretStore False +``` + +This example shows how to set and unset the default vault for the current user. The first command +gets information about all registered vaults and shows that the `LocalStore` is the default vault +for the user. The second command makes the `CredMan` vault the default vault. The third command +shows that the `CredMan` vault is now default, and `LocalStore` vault is no longer default. The +fourth command uses the **ClearDefault** parameter to remove the default designation from any +registered vault. The last command shows that there is no default vault. + +## PARAMETERS + +### -ClearDefault + +Sets the **IsDefault** property to `$false` for all registered vaults. + +```yaml +Type: System.Management.Automation.SwitchParameter +Parameter Sets: ClearParameterSet +Aliases: + +Required: False +Position: 0 +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Name + +Specifies the name of a registered vault to set as the default vault. Wildcard characters (`*`) are +not permitted. + +```yaml +Type: System.String +Parameter Sets: NameParameterSet +Aliases: + +Required: True +Position: 0 +Default value: None +Accept pipeline input: True (ByValue) +Accept wildcard characters: False +``` + +### -SecretVault + +Specifies a **SecretVaultInfo** object representing the registered vault to set as the default +vault. + +```yaml +Type: Microsoft.PowerShell.SecretManagement.SecretVaultInfo +Parameter Sets: SecretVaultParameterSet +Aliases: + +Required: True +Position: 0 +Default value: None +Accept pipeline input: True (ByPropertyName, ByValue) +Accept wildcard characters: False +``` + +### -Confirm + +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: System.Management.Automation.SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -WhatIf + +Shows what would happen if the cmdlet runs. The cmdlet isn't run. + +```yaml +Type: System.Management.Automation.SwitchParameter +Parameter Sets: (All) +Aliases: wi + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### None + +## OUTPUTS + +### None + +## NOTES + +## RELATED LINKS diff --git a/learn-docs/Microsoft.PowerShell.SecretManagement/Test-SecretVault.md b/learn-docs/Microsoft.PowerShell.SecretManagement/Test-SecretVault.md new file mode 100644 index 0000000..9cad9b1 --- /dev/null +++ b/learn-docs/Microsoft.PowerShell.SecretManagement/Test-SecretVault.md @@ -0,0 +1,78 @@ +--- +external help file: Microsoft.PowerShell.SecretManagement.dll-Help.xml +Module Name: Microsoft.PowerShell.SecretManagement +ms.date: 05/23/2025 +online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.secretmanagement/test-secretvault?view=ps-modules&wt.mc_id=ps-gethelp +schema: 2.0.0 +--- + +# Test-SecretVault + +## SYNOPSIS +Runs an extension vault self test. + +## SYNTAX + +``` +Test-SecretVault [[-Name] ] [] +``` + +## DESCRIPTION + +This cmdlet runs an extension vault self-test, by running the internal vault `Test-SecretVault` +command. It returns `$true` if all tests succeeded, and `$false` otherwise. Information on failing +tests is written to the error stream as error records. For more information during the test run use +the **Verbose** parameter. + +## EXAMPLES + +### Example 1 + +```powershell +PS C:\> Test-SecretVault -Name CredMan -Verbose +VERBOSE: Invoking command Test-SecretVault on module Microsoft.PowerShell.CredManStore.Extension +VERBOSE: Vault CredMan succeeded validation test +True +``` + +This example runs the self-tests on the `CredMan` extension vault. All tests succeeded. + +## PARAMETERS + +### -Name + +Specifies the name of one or more vaults to test. Enter a name or name pattern. Wildcard characters +(`*`) are permitted. + +If the **Name** parameter isn't specified, this cmdlet runs the tests for all registered vaults. + +```yaml +Type: System.String[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: 1 +Default value: None +Accept pipeline input: True (ByPropertyName, ByValue) +Accept wildcard characters: True +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### None + +## OUTPUTS + +### System.Boolean + +## NOTES + +## RELATED LINKS diff --git a/learn-docs/Microsoft.PowerShell.SecretManagement/Unlock-SecretVault.md b/learn-docs/Microsoft.PowerShell.SecretManagement/Unlock-SecretVault.md new file mode 100644 index 0000000..bc7c22b --- /dev/null +++ b/learn-docs/Microsoft.PowerShell.SecretManagement/Unlock-SecretVault.md @@ -0,0 +1,112 @@ +--- +external help file: Microsoft.PowerShell.SecretManagement.dll-Help.xml +Module Name: Microsoft.PowerShell.SecretManagement +ms.date: 05/23/2025 +online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.secretmanagement/unlock-secretvault?view=ps-modules&wt.mc_id=ps-gethelp +schema: 2.0.0 +--- + +# Unlock-SecretVault + +## SYNOPSIS +Unlocks an extension vault so that it can be accessed in the current session. + +## SYNTAX + +``` +Unlock-SecretVault [-Name] [-Password] [] +``` + +## DESCRIPTION + +This cmdlet unlocks an extension vault using the provided **Password**. This allows a vault that +requires password authentication to operate without first having to prompt the user. Not all +extension vaults require password authentication. The cmdlet returns a warning if the extension +vault doesn't support unlocking via password. + +## EXAMPLES + +### Example 1 + +```powershell +Unlock-SecretVault -Name SecretStore -Password $SecurePassword +Get-SecretInfo -Vault SecretStore +``` + +```Output +Name Type VaultName +---- ---- --------- +Secret1 SecureString SecretStore +Secret2 SecureString SecretStore +``` + +This example uses the command to unlock the `SecretStore` vault. It then runs the `Get-SecretInfo` +command on the vault without being prompted for the vault password. + +### Example 2 + +```powershell +Unlock-SecretVault -Name CredMan -Password $SecurePassword +``` + +```Output +WARNING: Can't unlock extension vault 'CredMan': The vault doesn't support the Unlock-SecretVault +function. +``` + +This example uses the command to unlock the `CredMan` vault. But the vault doesn't support unlocking +so the command has no effect. A warning is displayed informing that `CredMan` vault doesn't support +unlocking. + +## PARAMETERS + +### -Name + +Name of the vault to unlock. + +```yaml +Type: System.String +Parameter Sets: (All) +Aliases: + +Required: True +Position: 0 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Password + +Password used to unlock the vault. + +```yaml +Type: System.Security.SecureString +Parameter Sets: (All) +Aliases: + +Required: True +Position: 1 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### None + +## OUTPUTS + +### System.Object + +## NOTES + +## RELATED LINKS diff --git a/learn-docs/Microsoft.PowerShell.SecretManagement/Unregister-SecretVault.md b/learn-docs/Microsoft.PowerShell.SecretManagement/Unregister-SecretVault.md new file mode 100644 index 0000000..69d536d --- /dev/null +++ b/learn-docs/Microsoft.PowerShell.SecretManagement/Unregister-SecretVault.md @@ -0,0 +1,174 @@ +--- +external help file: Microsoft.PowerShell.SecretManagement.dll-Help.xml +Module Name: Microsoft.PowerShell.SecretManagement +ms.date: 05/23/2025 +online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.secretmanagement/unregister-secretvault?view=ps-modules&wt.mc_id=ps-gethelp +schema: 2.0.0 +--- + +# Unregister-SecretVault + +## SYNOPSIS +Un-registers an extension vault from SecretManagement for the current user. + +## SYNTAX + +### NameParameterSet + +``` +Unregister-SecretVault [-Name] [-WhatIf] [-Confirm] [] +``` + +### SecretVaultParameterSet + +``` +Unregister-SecretVault [-SecretVault] [-WhatIf] [-Confirm] [] +``` + +## DESCRIPTION + +This cmdlet un-registers the specified extension vault. Once un-registered, the vault is no longer +available to **SecretManagement** for the current user. + +## EXAMPLES + +### Example 1 + +```powershell +PS C:\> Get-SecretVault + +VaultName ModuleName IsDefaultVault +--------- ---------- -------------- +CredMan Microsoft.PowerShell.CredManStore False +LocalStore Microsoft.PowerShell.SecretStore True + +PS C:\> Unregister-SecretVault LocalStore +PS C:\> Get-SecretVault + +VaultName ModuleName IsDefaultVault +--------- ---------- -------------- +CredMan Microsoft.PowerShell.CredManStore False + +PS C:\> Get-Secret -Name Secret5 +Get-Secret: The secret Secret5 wasn't found. + +PS C:\> Register-SecretVault -Name SecretStore -ModuleName Microsoft.PowerShell.SecretStore -DefaultVault +PS C:\> Get-SecretVault + +VaultName ModuleName IsDefaultVault +--------- ---------- -------------- +CredMan Microsoft.PowerShell.CredManStore False +SecretStore Microsoft.PowerShell.SecretStore True + +PS C:\> Get-Secret -Name Secret5 +System.Security.SecureString +``` + +The first command lists the registered vaults for the current user. The second command un-registers +the `LocalStore` vault. The third command verifies that the vault no longer appears in the registry. +The fourth command attempts to retrieve `Secret5`, but it's not found since its vault was +un-registered. The fifth command re-registers the vault under a different name and sets it as the +user's default vault. The sixth command verifies that the vault has been re-registered as +`SecretStore` and is the default vault. Finally, the last command retrieves `Secret5` from the +re-registered vault. + +### Example 2 + +```powershell +PS C:\> Get-SecretVault | Unregister-SecretVault +PS C:\> Get-SecretVault + +``` + +This example un-registers all extension vaults for the current user. The second command shows that +no vaults are registered. + +This example un-registers all extension vaults for the current user. `Get-SecretVault` retrieves all +registered vaults for the current user and sends the result through the pipeline to +`Unregister-SecretVault`. `Get-SecretVault` shows that the secret no longer exists in the vault. + +## PARAMETERS + +### -Name + +Specifies the name of the vault to un-register. Enter a name or name pattern. Wildcard characters +(`*`) are permitted. + +```yaml +Type: System.String[] +Parameter Sets: NameParameterSet +Aliases: + +Required: True +Position: 0 +Default value: None +Accept pipeline input: True (ByValue) +Accept wildcard characters: True +``` + +### -SecretVault + +Specifies a **SecretVaultInfo** object representing the vault to un-register. + +```yaml +Type: Microsoft.PowerShell.SecretManagement.SecretVaultInfo +Parameter Sets: SecretVaultParameterSet +Aliases: + +Required: True +Position: 0 +Default value: None +Accept pipeline input: True (ByPropertyName, ByValue) +Accept wildcard characters: False +``` + +### -Confirm + +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: System.Management.Automation.SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -WhatIf + +Shows what would happen if the cmdlet runs. The cmdlet isn't run. + +```yaml +Type: System.Management.Automation.SwitchParameter +Parameter Sets: (All) +Aliases: wi + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### Microsoft.PowerShell.SecretManagement.SecretVaultInfo + +## OUTPUTS + +### None + +## NOTES + +## RELATED LINKS diff --git a/learn-docs/README.md b/learn-docs/README.md new file mode 100644 index 0000000..8530124 --- /dev/null +++ b/learn-docs/README.md @@ -0,0 +1,5 @@ +# Documentation archive + +This folder contains the last version of the documentation published to the learn.microsoft.com +website for this module. The content is being archived here for reference and to support users that +want to continue using this module after the project is archived. diff --git a/learn-docs/SecretManagement/get-started/understanding-secretmanagement.md b/learn-docs/SecretManagement/get-started/understanding-secretmanagement.md new file mode 100644 index 0000000..933d3b9 --- /dev/null +++ b/learn-docs/SecretManagement/get-started/understanding-secretmanagement.md @@ -0,0 +1,58 @@ +--- +description: Explains concepts and usage of the SecretManagement module +ms.date: 06/28/2023 +title: Understanding the SecretManagement module +--- +# Understanding the SecretManagement module + +The purpose of the **SecretManagement** module is to provide secure storage and access of secrets +through registered extension vaults. The registered extension vaults are PowerShell modules that +conform to **SecretManagement** module requirements. The extension vaults perform the actual work of +authentication and securely storing and retrieving secrets. An extension vault can store secrets +locally or remotely for a cloud-based store. + +The **SecretManagement** module provides commands for registering vault extensions, and accessing +vault secrets. This greatly reduces the temptation to hardcode secrets directly into production +source code. Instead, the **SecretManagement** module allows you to dynamically retrieve secrets at +runtime. + +Extension vaults are registered for the current user context. Vault registration is stored +separately from vault data files. The file location depends on the platform operating system. + +- For Windows platforms the location is: + `$env:LOCALAPPDATA\Microsoft\PowerShell\secretmanagement\secretvaultregistry\` +- For Non-Windows platforms the location is: `$HOME/.secretmanagement/secretvaultregistry/` + +## Getting started with SecretManagement + +Once you have **SecretManagement** installed you can run `Get-SecretVault` to see what secret vaults +you have registered. If this is your first time using the module, this command returns nothing. Once +you have a vault registered you can use the **SecretManagement** cmdlets to view, get, set, and +remove secrets. To see an example of registering a vault, see +[Get started with the SecretStore module][04]. + +The **SecretManagement** module helps users manage secrets by providing a common set of cmdlets to +interface with secrets across vaults. For a full list of cmdlets, see the +[Microsoft.PowerShell.SecretManagement][01] module page in the documentation. + +## Building an extension vault + +The value of the **SecretManagement** interface comes from the underlying vault and becomes more +useful with each extension vault module. For more information on the design of SecretManagement and +how to build extension vaults, see the [design document][02] in the **SecretManagement** repository. +This document describes a reference implementation **TestVault** module. Also, reviewing the source +code of the [SecretStore][03] module may serve as an example for extension vault authors looking to +build off of existing vaults. + +## Windows Managed Accounts + +**SecretManagement** doesn't currently work for Windows managed accounts. The module depends on both +`$env:LOCALAPPDATA` folders to store registry information and Windows Data Protection APIs (DPAPI) +for safely handling secrets with the .NET **SecureString** type. Windows managed accounts do not +have profiles or `$env:LOCALAPPDATA` folders and DPAPI doesn't support managed accounts. + + +[01]: /powershell/module/microsoft.powershell.secretmanagement +[02]: https://github.com/PowerShell/SecretManagement/blob/master/Docs/ARCHITECTURE.md +[03]: https://github.com/PowerShell/SecretStore +[04]: using-secretstore.md diff --git a/learn-docs/SecretManagement/get-started/using-secretstore.md b/learn-docs/SecretManagement/get-started/using-secretstore.md new file mode 100644 index 0000000..a214667 --- /dev/null +++ b/learn-docs/SecretManagement/get-started/using-secretstore.md @@ -0,0 +1,111 @@ +--- +description: How to install and use the SecretManagement and SecretStore modules +ms.date: 11/10/2023 +title: Get started with the SecretStore module +--- +# Get started with the SecretStore module + +The **SecretManagement** and **SecretStore** modules are available from the PowerShell Gallery and +can be installed using **PowerShellGet** commands. + +```powershell +# Install with PowerShellGet 2.x +Install-Module Microsoft.PowerShell.SecretManagement +Install-Module Microsoft.PowerShell.SecretStore +``` + +or + +```powershell +# Install with PSResourceGet 1.x +Install-PSResource Microsoft.PowerShell.SecretManagement +Install-PSResource Microsoft.PowerShell.SecretStore +``` + +Once you have installed the modules, you can load the modules and begin using or creating new +secrets. + +```powershell +Import-Module Microsoft.PowerShell.SecretManagement +Import-Module Microsoft.PowerShell.SecretStore +``` + +## Create a vault and add a secret + +First you must register the vault. The **Name** parameter is a friendly name and can be any valid +string. + +```powershell +Register-SecretVault -Name SecretStore -ModuleName Microsoft.PowerShell.SecretStore -DefaultVault +``` + +The **DefaultVault** parameter makes this the default vault. + +Now you can create a secret. + +```powershell +Set-Secret -Name TestSecret -Secret "TestSecretPassword" +``` + +This example passes a plaintext string for the value of the secret. The secret value can be one of +five supported types: + +- **byte[]** +- **String** +- **SecureString** +- **PSCredential** +- **Hashtable** + +The first time you access the vault you must provide a password for the new vault. This password is +used to lock and unlock the vault. + +```Output +Vault SecretStore requires a password. +Enter password: +******** +Enter password again for verification: +******** +``` + +Run `Get-Secret` to retrieve the secret. Using the **AsPlainText** switch returns the secret as an +unencrypted string. + +```powershell +PS> Get-Secret -Name TestSecret -AsPlainText +TestSecretPassword +``` + +To get the list of all of your secrets, you can run: + +```powershell +PS> Get-SecretInfo + +Name Type VaultName +---- ---- --------- +TestSecret String SecretStore +``` + +## Notes + +When you run `Set-Secret` with the **Name** parameter to specify the name of the secret, the cmdlet +calls `GetSecret()` that's implemented by the vault extension. `Set-Secret` passes through the name +as provided by the user. The vault extension looks up the secret by that name. If `GetSecret()` +returns a match, `Set-Secret` overwrites the secret unless you use the **NoClobber** parameter. The +vault extension always writes the secret information it receives. + +It's up to the vault extension implementation to decide whether or not to use a case-sensitive +comparison on the name. For example, secret names in the **Microsoft.PowerShell.SecretStore** +extension vault are case-insensitive. If the name you pass to `Set-Secret` differs only by case with +the name of an existing secret in a SecretStore vault, the name is overwritten with the new value +you provided. + +## Related links + +- [Register-SecretVault][02] +- [Get-Secret][01] +- [Set-Secret][03] + + +[01]: xref:Microsoft.PowerShell.SecretManagement.Get-Secret +[02]: xref:Microsoft.PowerShell.SecretManagement.Register-SecretVault +[03]: xref:Microsoft.PowerShell.SecretManagement.Set-Secret diff --git a/learn-docs/SecretManagement/how-to/manage-secretstore.md b/learn-docs/SecretManagement/how-to/manage-secretstore.md new file mode 100644 index 0000000..5ee5318 --- /dev/null +++ b/learn-docs/SecretManagement/how-to/manage-secretstore.md @@ -0,0 +1,158 @@ +--- +description: Explains how to manage a local SecretStore vault +ms.date: 06/28/2023 +title: Managing a SecretStore vault +--- +# Managing a SecretStore vault + +The **SecretStore** module is an extension vault for the PowerShell **SecretManagement** module. It +stores secrets, locally, in files for the current user account context, and uses .NET crypto APIs to +encrypt file contents. The **SecretStore** module has several configuration options. In the default +configuration, a password is required to store and access secrets, and provides the strongest +protection. **SecretStore** also supports the storage of metadata about secrets. + +## Registering a new vault + +Before you can create new secret you must register a vault. The **Name** parameter is a friendly +name and can be any valid string. + +```powershell +Register-SecretVault -Name SecretStore -ModuleName Microsoft.PowerShell.SecretStore -DefaultVault +``` + +> [!IMPORTANT] +> The **SecretManagement** module allows an extension vault to be registered multiple times, because +> it's possible that an extension vault may support different contexts via the registration +> **VaultParameters**. However, the **SecretStore** vault currently _always_ operates in the logged on +> user scope. Registering multiple **SecretStore** vaults with different names just results in +> duplication of the same store. + +Use the following command to see a list of registered vaults: + +```powershell +Get-SecretVault + +Name ModuleName IsDefaultVault +---- ---------- -------------- +Edge SecretManagement.Chromium False +SecretStore Microsoft.PowerShell.SecretStore True +``` + +In this example there are two vaults registered using different extension modules. + +## Configuring a vault + +Use the `Get-SecretStoreConfiguration` cmdlet to see a vault's configuration. + +```powershell +Get-SecretStoreConfiguration + + Scope Authentication PasswordTimeout Interaction + ----- -------------- --------------- ----------- +CurrentUser Password 900 Prompt +``` + +**SecretStore** vaults have the following configuration settings: + +- **Authentication** - `Password` (default) or `None` +- **PasswordTimeout** - `900` seconds (default) +- **Interaction** - `Prompt` (default) or `None` + +The default configuration requires a password, sets the session password timeout to 15 minutes, and +prompts the user for a password to unlock the vault. + +For non-interactive automation scenarios, the **Interaction** can be configured as `None` to +suppress user prompting. If a password is required, vault commands return +**Microsoft.PowerShell.SecretStore.PasswordRequiredException** exception if there is no valid +session password. The `Unlock-SecretStore` cmdlet can be used to provide the password for the +current PowerShell session. The vault remains unlocked until the timeout expires. + +Vault configuration and data are stored in separate files. The file location depends on the platform +operating system. + +- For Windows platforms the location is: `$env:LOCALAPPDATA\Microsoft\PowerShell\secretmanagement\localstore\` +- For Non-Windows platforms the location is: `$HOME/.secretmanagement/localstore/` + +### Changing the configuration + +You can change the configuration of a vault using the `Set-SecretStoreConfiguration` cmdlet. The +cmdlet provides the parameters **Authentication**, **PasswordTimeout**, and **Interaction** that are +used to change the corresponding configuration properties. There is also a **Default** parameter to +reset the configuration back to the default values. + +There are two ways to set the password on the vault. + +1. The `Set-SecretStoreConfiguration` cmdlet has the **Password** parameter that takes a + **SecureString** value. +1. The `Set-SecretStorePassword` cmdlet changes the vault password. The cmdlet takes no parameters + and can only be used interactively. You are prompted the for old and new passwords. + +### Adding metadata + +The **SecretStore** module allows you to add non-sensitive metadata to your secrets. The metadata +can be used to document the intended purpose of a secret. For example, to indicate that a secret +is intended for a particular subscription or application scenario. You could also add metadata +about the secret's creation date, expiration time, or other information used to manage the secret +lifecycle. + +The metadata can be any arbitrary key-value pair. The **SecretStore** module supports the following +value types for metadata: + +- **string** +- **int** +- **DateTime** + +To create a new secret with metadata: + +```powershell +$metadata = @{ + Purpose = 'Testing' + Expires = (Get-Date).AddDays(30) + Limit = 5 +} +Set-Secret -Name TestSecret -Secret NewSecret -Metadata $metadata +``` + +To view secret metadata you can then run the command: + +```powershell +Get-SecretInfo -Name TestSecret | Format-List * + +Name : TestSecret +Type : String +VaultName : SecretStore +Metadata : {[Limit, 5], [Expires, 6/23/2022 1:45:09 PM], [Purpose, Testing]} +``` + +You can also set metadata for an existing secret using the `Set-SecretInfo` cmdlet: + +```powershell +Set-SecretInfo TestSecret -Metadata @{Purpose = "showing the new cmdlet"} +Get-SecretInfo -Name TestSecret | Select-Object Metadata + +Metadata +-------- +{[Purpose, showing the new cmdlet]} +``` + +> [!CAUTION] +> This overwrites any existing metadata with the new values. + +### Resetting or removing a vault + +The `Reset-SecretStore` cmdlet resets the **SecretStore** vault by deleting all secret data and +configuring the store with default options. It is intended to be used only when the required +password is lost or data files become corrupted. The default configuration options can be overridden +by specifying individual command configuration option parameters. + +## Related links + +- [Get-SecretInfo](xref:Microsoft.PowerShell.SecretManagement.Get-SecretInfo) +- [Get-SecretStoreConfiguration](xref:Microsoft.PowerShell.SecretStore.Get-SecretStoreConfiguration) +- [Register-SecretVault](xref:Microsoft.PowerShell.SecretManagement.Register-SecretVault) +- [Reset-SecretStore](xref:Microsoft.PowerShell.SecretStore.Reset-SecretStore) +- [Set-Secret](xref:Microsoft.PowerShell.SecretManagement.Set-Secret) +- [Set-SecretInfo](xref:Microsoft.PowerShell.SecretManagement.Set-SecretInfo) +- [Set-SecretStoreConfiguration](xref:Microsoft.PowerShell.SecretStore.Set-SecretStoreConfiguration) +- [Set-SecretStorePassword](xref:Microsoft.PowerShell.SecretStore.Set-SecretStorePassword) +- [Unlock-SecretStore](xref:Microsoft.PowerShell.SecretStore.Unlock-SecretStore) diff --git a/learn-docs/SecretManagement/how-to/using-azure-keyvault.md b/learn-docs/SecretManagement/how-to/using-azure-keyvault.md new file mode 100644 index 0000000..69ffedf --- /dev/null +++ b/learn-docs/SecretManagement/how-to/using-azure-keyvault.md @@ -0,0 +1,49 @@ +--- +description: This article explains how to use an Azure Key Vault module, as a SecretManagement extension vault, in an automation scenario to securely retrieve and use passwords or other secret material. +ms.date: 12/05/2023 +title: Use Azure Key Vault in automation +--- +# Use Azure Key Vault in automation + +This article provides an example for using Azure Key Vault in an automation scenario. Azure Key +Vault provides you a way to securely store and retrieve the passwords, tokens and other secrets, +that are stored outside of the local machine, and use them in your automation pipeline. + +## Set up the host that runs the automation + +Beginning with **Az.KeyVault** 3.3.0, the module includes a **SecretManagement** extension that +allows you to use the **SecretManagement** cmdlets to interact with secrets stored in Azure Key +Vault. + +First, you should create a Key Vault in your Azure subscription and add your secrets. For more +information, see +[Quickstart: Set and retrieve a key from Azure Key Vault using Azure PowerShell][azkv-quick]. + +To use the Azure Key Vault with **SecretManagement** first ensure that you have the +[Az.KeyVault][Az.KeyVault] module. + +Next, register the vault using your **AZKVaultName** and **SubscriptionId**. These commands must be +run in the user context of the automation account on the automation host. + +```powershell +Install-Module -Name Microsoft.PowerShell.SecretManagement -Repository PSGallery -Force +Install-Module Az.KeyVault -Repository PSGallery -Force +Import-Module Microsoft.PowerShell.SecretManagement +Import-Module Az.KeyVault + +$VaultParameters = @{ + AZKVaultName = $vaultName + SubscriptionId = $subID +} +Register-SecretVault -Module Az.KeyVault -Name AzKV -VaultParameters $VaultParameters +``` + +## Use Azure Key Vault secrets in automation + +Now that you have registered your Azure Key Vault with **SecretManagement** you can view secrets +with `Get-SecretInfo`, get secrets with `Get-Secret`, create and update secrets with `Set-Secret`, +and remove secrets with `Remove-Secret`. + + +[azkv-quick]: /azure/key-vault/keys/quick-create-powershell +[Az.KeyVault]: https://www.powershellgallery.com/packages/Az.KeyVault diff --git a/learn-docs/SecretManagement/how-to/using-secrets-in-automation.md b/learn-docs/SecretManagement/how-to/using-secrets-in-automation.md new file mode 100644 index 0000000..b7112e5 --- /dev/null +++ b/learn-docs/SecretManagement/how-to/using-secrets-in-automation.md @@ -0,0 +1,95 @@ +--- +description: This article explains how to use a SecretStore vault in an automation scenario to securely retrieve an use passwords or other secret material. +ms.date: 03/06/2024 +title: Use the SecretStore in automation +--- +# Use the SecretStore in automation + +This article provides an example for using a **Microsoft.PowerShell.SecretStore** vault in an +automation scenario. A **SecretStore** vault provides you a way to securely store and retrieve the +passwords, tokens and other secrets you need to use in your automation pipeline on the local +machine. + +## Set up the host that runs the automation + +For this example you must first install and configure the SecretManagement modules. This example +assumes that your automation host is running Windows. These commands must be run in the user context +of the automation account on the host. + +```powershell +Install-Module -Name Microsoft.PowerShell.SecretStore -Repository PSGallery -Force +Install-Module -Name Microsoft.PowerShell.SecretManagement -Repository PSGallery -Force +Import-Module Microsoft.PowerShell.SecretStore +Import-Module Microsoft.PowerShell.SecretManagement +``` + +## Configure the SecretStore vault + +You must also create a password as a **SecureString** that's used to secure the SecretStore vault. +The automation system you use might have a way to securely provide a password that you can use to +secure the vault. For example, GitHub provides a way to securely store and use secrets in GitHub +Actions. For more information, see [Using secrets in GitHub Actions][01]. + +In this example, the password is a **SecureString** that is securely exported to an XML file and +encrypted by Windows Data Protection (DPAPI). The following command prompts you for a password. In +this example the **UserName** is unimportant. + +```powershell +PS> $credential = Get-Credential -UserName 'SecureStore' + +PowerShell credential request +Enter your credentials. +Password for user SecureStore: ************** +``` + +Once you have the password you can save it to an encrypted XML file. + +```powershell +$securePasswordPath = 'C:\automation\passwd.xml' +$credential.Password | Export-Clixml -Path $securePasswordPath +``` + +Next you must configure the **SecretStore** vault. The configuration sets user interaction to +`None`, so that **SecretStore** never prompts the user. The configuration requires a password, and +the password is passed in as a **SecureString** object. The `-Confirm:false` parameter is used so +that PowerShell does not prompt for confirmation. + +```powershell +Register-SecretVault -Name SecretStore -ModuleName Microsoft.PowerShell.SecretStore -DefaultVault +$password = Import-CliXml -Path $securePasswordPath + +$storeConfiguration = @{ + Authentication = 'Password' + PasswordTimeout = 3600 # 1 hour + Interaction = 'None' + Password = $password + Confirm = $false +} +Set-SecretStoreConfiguration @storeConfiguration +``` + +Now that you have the vault installed and configured, you can use `Set-Secret` to add the secrets +you need for your automation scripts. + +## Use secrets in automation + +The **SecretStore** password must be provided in a secure fashion. Here the password is being +imported from a file that was encrypted using Windows Data Protection (DPAPI). + +> [!NOTE] +> This is a Windows-only solution, but another option is to use a secure variable provided by a CI +> system like GitHub Actions. + +The automation script needs to unlock the vault to retrieve the secrets needed in the script. The +`Unlock-SecretStore` cmdlet is used to unlock the **SecretStore** for this session. The password +timeout was configured for 1 hour. The vault remains unlocked in the session for that amount of +time. After the timeout, the vault must be unlocked again before secrets can be accessed. + +```powershell +$password = Import-CliXml -Path $securePasswordPath +Unlock-SecretStore -Password $password +$automationPassword = Get-Secret -Name CIJobSecret +``` + + +[01]: https://docs.github.com/actions/security-guides/using-secrets-in-github-actions diff --git a/learn-docs/SecretManagement/overview.md b/learn-docs/SecretManagement/overview.md new file mode 100644 index 0000000..53d4e98 --- /dev/null +++ b/learn-docs/SecretManagement/overview.md @@ -0,0 +1,72 @@ +--- +description: Overview of the SecretManagement and SecretStore modules +ms.date: 06/28/2023 +title: Overview of the SecretManagement and SecretStore modules +--- +# Overview of the SecretManagement and SecretStore modules + +The **SecretManagement** module helps users manage secrets by providing a common set of cmdlets that +interface with secrets vaults. **SecretManagement** provides an extensible model where local and +remote vaults can be registered for use. This allows you to separate the specific details for +accessing and managing the vault from your scripts that need secrets. + +Since **SecretManagement** is a module abstraction layer in PowerShell, it becomes useful once +extension vaults are registered. There are trade-offs between security, usability, and specificity +for any vault so it's up to the user to configure **SecretManagement** to integrate with the vaults +that best match their requirements, as well as to assess the extent to which they trust any vault +extensions not developed by Microsoft. + +**SecretManagement** doesn't impose authentication requirements for extension vaults. This allows +each individual vault to provide its own mechanism. Some may require a password or token, while +others may leverage current account credentials. + +**SecretManagement** enables the following key scenarios: + +- Sharing a script across your organization without knowing the local vault of all the users +- Running your deployment script in local, test, and production environments with the change of only + a single parameter, **Vault** +- Changing the backend of the authentication method to meet specific security or organizational + needs without needing to update all your scripts + +## Extension Vault Ecosystem + +**SecretManagement** becomes useful once you install and register extension vaults. Extension +vaults, which are PowerShell modules with a particular structure, provide the connection between the +**SecretManagement** module and any local or remote Secret Vault. + +**SecretStore** is a cross-platform extension module that implements a local vault. The +**SecretStore** vault stores secrets, locally in a file, for the current user. It uses .NET Core +cryptographic APIs to encrypt file contents. This extension vault works on all platforms that +support PowerShell 7. + +### Discovering and Installing Vault Extensions + +To find extension vault modules, search the PowerShell Gallery for the +[SecretManagement tag][03]. + +Some community vault extensions that are available: + +- [Azure KeyVault][04] (Microsoft Owned) +- [KeePass][07] +- [LastPass][09] +- [Hashicorp Vault][05] +- [KeyChain][08] +- [CredMan][06] + +## Community feedback and support + +Community feedback has been essential to the iterative development of these modules. To file issues +or get support for the SecretManagement interface or vault development experience please use the +[SecretManagement][01] repository. For issues with the SecretStore module please use the +[SecretStore][02] repository. + + +[01]: https://github.com/PowerShell/SecretManagement/issues +[02]: https://github.com/PowerShell/SecretStore/issues +[03]: https://www.powershellgallery.com/packages?q=Tags%3A%22SecretManagement%22 +[04]: https://www.powershellgallery.com/packages/Az.KeyVault +[05]: https://www.powershellgallery.com/packages/SecretManagement.Hashicorp.Vault.KV +[06]: https://www.powershellgallery.com/packages/SecretManagement.JustinGrote.CredMan +[07]: https://www.powershellgallery.com/packages/SecretManagement.KeePass +[08]: https://www.powershellgallery.com/packages/SecretManagement.KeyChain +[09]: https://www.powershellgallery.com/packages/SecretManagement.LastPass diff --git a/learn-docs/SecretManagement/security-concepts.md b/learn-docs/SecretManagement/security-concepts.md new file mode 100644 index 0000000..b2f4c98 --- /dev/null +++ b/learn-docs/SecretManagement/security-concepts.md @@ -0,0 +1,45 @@ +--- +description: This article explains the security of the features of the SecretManagement and SecretStore modules. +ms.date: 06/28/2023 +title: Understanding the security features of SecretManagement and SecretStore +--- +# Understanding the security features of SecretManagement and SecretStore + +The security of **SecretManagement** is dependent on the extension vaults it hosts. These vaults +perform the actual functions of storing and retrieving the secrets. **SecretManagement** does not +return secrets as plain text by default. By default, any text secrets are returned as +**SecureString** objects unless the user explicitly requests the secret as plain text using the +**AsPlaintext** switch. + +It is critical that you only use extension vault modules published by known and trusted sources, and +that have valid package signatures. + +The **SecretStore** extension vault uses .NET cryptography APIs to encrypt secret data and store it +on the local file system. The store configuration information and secret metadata are also stored in +encrypted form to prevent inadvertent disclosure or casual reading. + +The secret storage file is validated by a cryptographic hash to detect file corruption or tampering. +All of this information is protected by a single cryptographic key and optional password. + +The default configuration of **SecretStore** requires a password. However a password is more +difficult to manage since it must be provided when first configuring the **SecretStore** vault, and +provided again when accessing the store. + +For the best security, use a password that is not stored on the local machine so it cannot be +discovered if the machine is ever breached. + +The **SecretStore** configuration includes a **PasswordTimeout**, which limits the amount of time +that the vault remains unlocked during a session. + +A timeout value of `-1` means that the vault remains unlocked for the entire life of the session. +This is potentially less secure, but is useful when running an unattended script in a single +session. The vault is unlocked, using `Unlock-SecretStore`, and remains unlocked for the entire +session. The session is closed when the script completes. + +The password authentication requirement can also be turned off completely. In this case no password +is required to access secrets from a logged in account, and is much more convenient. The secrets are +still encrypted, but the key to decrypt the secrets is stored on the file system for the current +user account. The key is protected only by the OS file system security. The key could be discovered +by other accounts that have read privileges on files owned by that user account. Therefore, the +no-password configuration is not recommended for any systems needing strong security protections of +the stored secrets.