en-US/Posh-SecretRotation-help.xml
|
<?xml version="1.0" encoding="utf-8"?>
<helpItems schema="maml" xmlns="http://msh"> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Update-SecretRotationAccountPassword</command:name> <command:verb>Update</command:verb> <command:noun>SecretRotationAccountPassword</command:noun> <maml:description> <maml:para>Generates a new password, applies it to a configured target's identity backend, and splits it via Shamir Secret Sharing.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Reads the named target from the Posh-SecretRotation config, generates a new random password at that target's configured entropy (Posh-SecretSharing's New-SecretSharingPassword), applies it to the target's backend (Active Directory, Entra ID, or a config-defined Custom handler script), and - only once that backend update actually succeeds - splits the new password into Shamir shares (Posh-SecretSharing's Split-SecretSharingSecret) per the target's configured quorum scheme.</maml:para> <maml:para>A password that was generated but never confirmed applied to the backend is never split or returned: Set-SecretRotationBackendPassword throws on any backend failure, and this cmdlet does not catch that exception before it reaches the caller - it only adds a log entry first. There would be nothing for the returned shares to reconstruct into a live credential otherwise.</maml:para> <maml:para>Supports -WhatIf/-Confirm (ConfirmImpact High) since this changes a real account's password on a real backend - unlike Posh-SecretSharing's pure-computation New-* cmdlets, this one has a real, external side effect.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Update-SecretRotationAccountPassword</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>Target</maml:name> <maml:description> <maml:para>Name of a target block under the config's 'targets' section (e.g. 'corp-ad-svcaccount1'). Validated against the live config at call time; throws with the list of available target names if not found.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none"> <maml:name>BackendParameter</maml:name> <maml:description> <maml:para>Optional hashtable merged over the target's own 'backendConfig', caller's values winning on key collision. Lets a caller override or supply backend properties (e.g. a different 'identity') without editing the config file.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Hashtable</command:parameterValue> <dev:type> <maml:name>Hashtable</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>@{}</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="3" aliases="none"> <maml:name>OutputPath</maml:name> <maml:description> <maml:para>Optional folder. When given, writes one file per returned share to this folder (see Export-SecretRotationShareFile) - never a single combined file, since that would defeat the point of splitting the password.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="wi"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="cf"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>Target</maml:name> <maml:description> <maml:para>Name of a target block under the config's 'targets' section (e.g. 'corp-ad-svcaccount1'). Validated against the live config at call time; throws with the list of available target names if not found.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none"> <maml:name>BackendParameter</maml:name> <maml:description> <maml:para>Optional hashtable merged over the target's own 'backendConfig', caller's values winning on key collision. Lets a caller override or supply backend properties (e.g. a different 'identity') without editing the config file.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Hashtable</command:parameterValue> <dev:type> <maml:name>Hashtable</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>@{}</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="3" aliases="none"> <maml:name>OutputPath</maml:name> <maml:description> <maml:para>Optional folder. When given, writes one file per returned share to this folder (see Export-SecretRotationShareFile) - never a single combined file, since that would defeat the point of splitting the password.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="wi"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="cf"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes /> <command:returnValues> <command:returnValue> <dev:type> <maml:name>PSCustomObject[]. The share objects returned by Split-SecretSharingSecret, unchanged.</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title> <dev:code>Update-SecretRotationAccountPassword -Target 'corp-ad-svcaccount1'</dev:code> <dev:remarks> <maml:para>Rotates the AD account's password and returns its Shamir shares to the pipeline.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 2 --------------------------</maml:title> <dev:code>Update-SecretRotationAccountPassword -Target 'corp-ad-svcaccount1' -OutputPath 'C:\rotation-output'</dev:code> <dev:remarks> <maml:para>Same, and also writes one file per share under C:\rotation-output.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 3 --------------------------</maml:title> <dev:code>Update-SecretRotationAccountPassword -Target 'corp-ad-svcaccount1' -BackendParameter @{ identity = 'svc-account2' } -WhatIf</dev:code> <dev:remarks> <maml:para>Shows what would happen for a different identity than the one in the config, without changing anything.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks /> </command:command> </helpItems> |