en-US/about_Get-DomainAdminCredential.help.txt
|
.EXTERNALHELP Get-DomainAdminCredential-help.xml
.NOTES NAME: about_Get-DomainAdminCredential .DESCRIPTION The Get-DomainAdminCredential function provides a centralized credential workflow for the module's domain admin account. It supports four primary behaviors: 1. RETURN CACHED CREDENTIAL If an in-memory PSCredential already exists in $script:domainAdminCred, it is reused by default to avoid repeated prompts during the same session. 2. REBUILD FROM STORED SETTINGS If no in-memory credential is available, the function attempts to reconstruct one from: - settings.passwords.domainAdminCredential.username in config.json - passwords.domainAdminCredential.password in config.secrets.json The password is stored only as DPAPI-protected SecureString text and can only be decrypted under the same Windows user / machine / security context that created it. 3. PROMPT FOR NEW CREDENTIAL If no usable cached/stored credential exists, or if -ForcePrompt is supplied, the function prompts interactively via Get-Credential and stores the result in memory for the current session. 4. PERSIST OR CLEAR STORED VALUES -Persist writes the username to config.json and the DPAPI-protected password blob to config.secrets.json. -Clear removes both stored values and clears the in-memory cache. STORAGE MODEL The username is treated as non-secret configuration and stored in config.json. The password is never written to config.json; it is stored only in config.secrets.json using ConvertFrom-SecureString, which relies on Windows DPAPI by default. .PARAMETER Clear Clears the stored domain admin credential values from both config files (config.json and config.secrets.json) and removes the in-memory cached credential. Use this to reset credentials for a new user or machine context. .PARAMETER ForcePrompt Forces an interactive prompt via Get-Credential even if a valid cached or stored credential already exists. This is useful when you need to switch users without clearing all stored settings first. .PARAMETER Persist Writes the current domain admin username to config.json and the DPAPI-protected password blob to config.secrets.json. This enables future sessions to automatically reconstruct the credential without prompting, provided the same user/machine context is used. .PARAMETER PassThru Returns the resulting PSCredential object to the pipeline. Without this switch, the function may not output anything if it only updates internal state or config files. .INPUTS None. You cannot pipe objects to Get-DomainAdminCredential. .OUTPUTS [PSCredential] The domain admin credential object, if -PassThru is specified or if a cached/stored credential is successfully retrieved and returned. .EXAMPLE Get-DomainAdminCredential Description: Retrieves the domain admin credential from memory cache, config files, or prompts for it interactively. The result is stored in $script:domainAdminCred for reuse within the session. .EXAMPLE Get-DomainAdminCredential -Persist Description: Prompts for credentials if not already available and persists them to config.json and config.secrets.json for future use. The credential is also stored in memory. .EXAMPLE Get-DomainAdminCredential -Clear Description: Removes all stored domain admin credentials from configuration files and clears the in-memory cache, forcing a prompt on the next invocation. .EXAMPLE Get-DomainAdminCredential -ForcePrompt -PassThru Description: Forces an interactive credential prompt regardless of existing cached values and returns the resulting PSCredential object to the pipeline for immediate use. .LINK [TechToolbox](https://github.com/dan-damit/TechToolbox) |