Functions/New-Credential.ps1
|
# Copyright 2012 Aaron Jensen # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. function New-Credential { <# .SYNOPSIS Creates a new `PSCredential` object from a given username and password. .DESCRIPTION `New-Credential` will create a credential for you from a username and password, converting a password stored as a `String` into a `SecureString`. PowerShell commands use `PSCredential` objects instead of username/password. Although Microsoft recommends using `Get-Credential` to get credentials, when automating installs, there's usually no one around to answer that prompt, so secrets are often pulled from encrypted stores. Beginning with Carbon 2.0, you can pass a `SecureString` as the value for the `Password` parameter. Beginning with Carbon 2.0, you can pipe passwords to `New-Credential`, e.g. Read-EncrptedPassword | Unprotect-String | New-Credential -Username 'fubar' We do *not* recommend passing plaintext passwords around. Beginning ing with Carbon 2.0, you can use `Unprotect-String` to decrypt secrets securely to `SecureStrings` and then use those secure strings with `New-Credential` to create a credential. .LINK Protect-String .LINK Unprotect-String .OUTPUTS System.Management.Automation.PSCredential. .EXAMPLE New-Credential -User ENTERPRISE\picard -Password 'earlgrey' Creates a new credential object for Captain Picard. .EXAMPLE Read-EncryptedPassword | Unprotect-String | New-Credential -UserName 'ENTERPRISE\picard' Demonstrates how to securely decrypt a secret into a new credential object. #> [CmdletBinding()] [OutputType([Management.Automation.PSCredential])] [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSAvoidUsingUserNameAndPassWordParams","")] param( [Alias('User')] [string] # The username. Beginning with Carbon 2.0, this parameter is optional. Previously, this parameter was required. $UserName, [Parameter(Mandatory=$true,ValueFromPipeline=$true)] # The password. Can be a `[string]` or a `[System.Security.SecureString]`. $Password ) begin { Set-StrictMode -Version 'Latest' Use-CallerPreference -Cmdlet $PSCmdlet -Session $ExecutionContext.SessionState } process { if( $Password -is [string] ) { $Password = ConvertTo-SecureString -AsPlainText -Force -String $Password } elseif( $Password -isnot [securestring] ) { Write-Error ('Value for Password parameter must be a [String] or [System.Security.SecureString]. You passed a [{0}].' -f $Password.GetType()) return } return New-Object 'Management.Automation.PsCredential' $UserName,$Password } end { } } |