Nota:
El acceso a esta página requiere autorización. Puede intentar iniciar sesión o cambiar directorios.
El acceso a esta página requiere autorización. Puede intentar cambiar los directorios.
Nota:
La versión original de este artículo apareció en el blog escrito por @joshduffney. Este artículo se ha editado para su inclusión en este sitio. El equipo de PowerShell agradece a Josh por compartir este contenido con nosotros. Consulte su blog en duffney.io.
En este artículo se muestra cómo agregar parámetros de credenciales a las funciones de PowerShell y por qué desea. Un parámetro de credencial es permitir ejecutar la función o el cmdlet como un usuario diferente. El uso más común es ejecutar la función o el cmdlet como una cuenta de usuario con privilegios elevados.
Por ejemplo, el cmdlet New-ADUser tiene un parámetro Credential , que podría proporcionar credenciales de administrador de dominio para crear una cuenta en un dominio. Suponiendo que la cuenta normal que ejecuta la sesión de PowerShell aún no tiene ese acceso.
Creación de un objeto de credencial
El objeto PSCredential representa un conjunto de credenciales de seguridad, como un nombre de usuario y una contraseña. El objeto se puede pasar como parámetro a una función que se ejecuta como la cuenta de usuario de ese objeto de credencial. Hay varias maneras de crear un objeto de credencial. La primera manera de crear un objeto de credencial es usar el cmdlet Get-Credentialde PowerShell . Cuando se ejecuta sin parámetros, se le pide un nombre de usuario y una contraseña. O bien, puede llamar al cmdlet con algunos parámetros opcionales.
Para especificar el nombre de dominio y el nombre de usuario con antelación, puede usar los parámetros Credential o UserName . Al usar el parámetro UserName , también es necesario proporcionar un valor message . El código siguiente muestra el uso del cmdlet . También puede almacenar el objeto de credencial en una variable para poder usar la credencial varias veces. En el ejemplo siguiente, el objeto de credencial se almacena en la variable $Cred.
$Cred = Get-Credential
$Cred = Get-Credential -Credential domain\user
$Cred = Get-Credential -UserName domain\user -Message 'Enter Password'
A veces, no puede usar el método interactivo para crear objetos de credenciales que se muestran en el ejemplo anterior. La mayoría de las herramientas de automatización requieren un método no interactivo. Para crear una credencial sin interacción del usuario, cree una cadena segura que contenga la contraseña. A continuación, pase la cadena segura y el nombre de usuario al System.Management.Automation.PSCredential() método .
Use el siguiente comando para crear una cadena segura que contenga la contraseña:
ConvertTo-SecureString "MyPlainTextPassword" -AsPlainText -Force
Se requieren los parámetros AsPlainText y Force . Sin esos parámetros, recibirá un mensaje de advertencia que indica que no debe pasar texto sin formato a una cadena segura. PowerShell devuelve esta advertencia porque la contraseña de texto sin formato se registra en varios registros. Una vez creada una cadena segura, debe pasarla al PSCredential() método para crear el objeto de credencial. En el ejemplo siguiente, la variable $password contiene la cadena $Cred segura que contiene el objeto de credencial.
$password = ConvertTo-SecureString "MyPlainTextPassword" -AsPlainText -Force
$Cred = New-Object System.Management.Automation.PSCredential ("username", $password)
Ahora que sabe cómo crear objetos de credenciales, puede agregar parámetros de credenciales a las funciones de PowerShell.
Adición de un parámetro de credencial
Al igual que cualquier otro parámetro, empiece por agregarlo en el bloque de la param función.
Se recomienda asignar un nombre al parámetro $Credential porque es lo que usan los cmdlets de PowerShell existentes. El tipo del parámetro debe ser [System.Management.Automation.PSCredential].
En el ejemplo siguiente se muestra el bloque de parámetros de una función denominada Get-Something. Tiene dos parámetros: $Name y $Credential.
function Get-Something {
param(
$Name,
[System.Management.Automation.PSCredential]$Credential
)
El código de este ejemplo es suficiente para tener un parámetro de credencial de trabajo, pero hay algunas cosas que puede agregar para que sea más sólida.
Agregue el
[ValidateNotNull()]atributo de validación para comprobar que el valor que se pasa a Credential. Si el valor del parámetro es NULL, este atributo impide que la función se ejecute con credenciales no válidas.Agregue
[System.Management.Automation.Credential()]. Esto le permite pasar un nombre de usuario como una cadena y tener una solicitud interactiva para la contraseña.Establezca un valor predeterminado para el
$Credentialparámetro en[System.Management.Automation.PSCredential]::Empty. Es posible que la función pase este$Credentialobjeto a los cmdlets de PowerShell existentes. Si se proporciona un valor NULL al cmdlet llamado dentro de la función, se produce un error. Proporcionar un objeto de credencial vacío evita este error.
Sugerencia
Algunos cmdlets que aceptan un parámetro de credencial no admiten [System.Management.Automation.PSCredential]::Empty como deberían. Consulte la sección Tratar con cmdlets heredados para obtener una solución alternativa.
Uso de parámetros de credenciales
En el ejemplo siguiente se muestra cómo usar parámetros de credencial. En este ejemplo se muestra una función denominada Set-RemoteRegistryValue. Esta función define el parámetro de credencial mediante las técnicas que se describen en la sección anterior. La función llama Invoke-Command a mediante la $Credential variable creada por la función . Esto le permite cambiar el usuario que ejecuta Invoke-Command. Dado que el valor predeterminado de $Credential es una credencial vacía, la función se puede ejecutar sin proporcionar credenciales.
function Set-RemoteRegistryValue {
param(
$ComputerName,
$Path,
$Name,
$Value,
[ValidateNotNull()]
[System.Management.Automation.PSCredential]
[System.Management.Automation.Credential()]
$Credential = [System.Management.Automation.PSCredential]::Empty
)
$null = Invoke-Command -ComputerName $ComputerName -ScriptBlock {
Set-ItemProperty -Path $Using:Path -Name $Using:Name -Value $Using:Value
} -Credential $Credential
}
En las secciones siguientes se muestran diferentes métodos para proporcionar credenciales a Set-RemoteRegistryValue.
Solicitud de credenciales
El uso Get-Credential de entre paréntesis () en tiempo de ejecución hace que se Get-Credential ejecute primero. Se le pedirá un nombre de usuario y una contraseña. Puede usar los parámetros Credential o UserName de Get-Credential para rellenar previamente el nombre de usuario y el dominio. En el ejemplo siguiente se usa una técnica denominada expansión para pasar parámetros a la Set-RemoteRegistryValue función . Para obtener más información sobre la expansión, consulte el artículo about_Splatting .
$remoteKeyParams = @{
ComputerName = $Env:COMPUTERNAME
Path = 'HKLM:\SOFTWARE\Microsoft\WebManagement\Server'
Name = 'EnableRemoteManagement'
Value = '1'
}
Set-RemoteRegistryValue @remoteKeyParams -Credential (Get-Credential)
El uso (Get-Credential) parece complicado. Normalmente, cuando se usa el parámetro Credential solo con un nombre de usuario, el cmdlet solicita automáticamente la contraseña. El [System.Management.Automation.Credential()] atributo habilita este comportamiento.
$remoteKeyParams = @{
ComputerName = $Env:COMPUTERNAME
Path = 'HKLM:\SOFTWARE\Microsoft\WebManagement\Server'
Name = 'EnableRemoteManagement'
Value = '1'
}
Set-RemoteRegistryValue @remoteKeyParams -Credential duffney
Nota:
Para establecer el valor del Registro que se muestra, en estos ejemplos se supone que tiene instaladas las características del servidor web de Windows. Ejecute Install-WindowsFeature Web-Server y Install-WindowsFeature web-mgmt-tools , si es necesario.
Proporcionar credenciales en una variable
También puede rellenar una variable de credencial con antelación y pasarla al parámetro Credential de la Set-RemoteRegistryValue función. Use este método con herramientas de integración continua e implementación continua (CI/CD), como Jenkins, TeamCity y Octopus Deploy. Para ver un ejemplo con Jenkins, consulte la entrada de blog de Hodge Automating with Jenkins and PowerShell on Windows - Part 2 (Automatización con Jenkins y PowerShell en Windows: parte 2).
En este ejemplo se usa el método .NET para crear el objeto de credencial y una cadena segura para pasar la contraseña.
$password = ConvertTo-SecureString "P@ssw0rd" -AsPlainText -Force
$Cred = New-Object System.Management.Automation.PSCredential ("duffney", $password)
$remoteKeyParams = @{
ComputerName = $Env:COMPUTERNAME
Path = 'HKLM:\SOFTWARE\Microsoft\WebManagement\Server'
Name = 'EnableRemoteManagement'
Value = '1'
}
Set-RemoteRegistryValue @remoteKeyParams -Credential $Cred
En este ejemplo, la cadena segura se crea mediante una contraseña de texto no cifrado. Todos los CI/CD mencionados anteriormente tienen un método seguro de proporcionar esa contraseña en tiempo de ejecución. Al usar esas herramientas, reemplace la contraseña de texto sin formato por la variable definida en la herramienta CI/CD que use.
Ejecución sin credenciales
Dado $Credential que el valor predeterminado es un objeto de credencial vacío, puede ejecutar el comando sin credenciales, como se muestra en este ejemplo:
$remoteKeyParams = @{
ComputerName = $Env:COMPUTERNAME
Path = 'HKLM:\SOFTWARE\Microsoft\WebManagement\Server'
Name = 'EnableRemoteManagement'
Value = '1'
}
Set-RemoteRegistryValue @remoteKeyParams
Tratar con cmdlets heredados
No todos los cmdlets admiten objetos de credenciales ni permiten credenciales vacías. En su lugar, el cmdlet quiere parámetros de nombre de usuario y contraseña como cadenas. Hay varias maneras de solucionar esta limitación.
Uso de if-else para controlar credenciales vacías
En este escenario, el cmdlet que desea ejecutar no acepta un objeto de credencial vacío. En este ejemplo se agrega el parámetro Credential a Invoke-Command solo si no está vacío. De lo contrario, ejecuta sin Invoke-Command el parámetro Credential .
function Set-RemoteRegistryValue {
param(
$ComputerName,
$Path,
$Name,
$Value,
[ValidateNotNull()]
[System.Management.Automation.PSCredential]
[System.Management.Automation.Credential()]
$Credential = [System.Management.Automation.PSCredential]::Empty
)
if($Credential -ne [System.Management.Automation.PSCredential]::Empty) {
Invoke-Command -ComputerName:$ComputerName -Credential:$Credential {
Set-ItemProperty -Path $Using:Path -Name $Using:Name -Value $Using:Value
}
} else {
Invoke-Command -ComputerName:$ComputerName {
Set-ItemProperty -Path $Using:Path -Name $Using:Name -Value $Using:Value
}
}
}
Uso de la expansión para controlar las credenciales vacías
En este ejemplo se usa la expansión de parámetros para llamar al cmdlet heredado. El $Credential objeto se agrega condicionalmente a la tabla hash para la expansión y evita la necesidad de repetir el bloque de Invoke-Command script. Para obtener más información sobre la expansión dentro de las funciones, consulte la entrada de blog Parámetros de expansión dentro de funciones avanzadas .
function Set-RemoteRegistryValue {
param(
$ComputerName,
$Path,
$Name,
$Value,
[ValidateNotNull()]
[System.Management.Automation.PSCredential]
[System.Management.Automation.Credential()]
$Credential = [System.Management.Automation.PSCredential]::Empty
)
$Splat = @{
ComputerName = $ComputerName
}
if ($Credential -ne [System.Management.Automation.PSCredential]::Empty) {
$Splat['Credential'] = $Credential
}
$null = Invoke-Command -ScriptBlock {
Set-ItemProperty -Path $Using:Path -Name $Using:Name -Value $Using:Value
} @splat
}
Trabajar con contraseñas de cadena
El Invoke-Sqlcmd cmdlet es un ejemplo de un cmdlet que acepta una cadena como contraseña.
Invoke-Sqlcmd permite ejecutar instrucciones sencillas de inserción, actualización y eliminación de SQL.
Invoke-Sqlcmd requiere un nombre de usuario y una contraseña de texto no cifrado en lugar de un objeto de credencial más seguro. En este ejemplo se muestra cómo extraer el nombre de usuario y la contraseña de un objeto de credencial.
La Get-AllSQLDatabases función de este ejemplo llama al Invoke-Sqlcmd cmdlet para consultar un servidor SQL Server para todas sus bases de datos. La función define un parámetro Credential con el mismo atributo usado en los ejemplos anteriores. Puesto que el nombre de usuario y la contraseña existen en la $Credential variable , puede extraer esos valores para usarlos con Invoke-Sqlcmd.
El nombre de usuario está disponible en la propiedad UserName de la $Credential variable. Para obtener la contraseña, debe usar el GetNetworkCredential() método del $Credential objeto . Los valores se extraen en variables que se agregan a una tabla hash usada para la expansión de parámetros en Invoke-Sqlcmd.
function Get-AllSQLDatabases {
param(
$SQLServer,
[ValidateNotNull()]
[System.Management.Automation.PSCredential]
[System.Management.Automation.Credential()]
$Credential = [System.Management.Automation.PSCredential]::Empty
)
$UserName = $Credential.UserName
$Password = $Credential.GetNetworkCredential().Password
$splat = @{
UserName = $UserName
Password = $Password
ServerInstance = 'SQLServer'
Query = "Select * from Sys.Databases"
}
Invoke-Sqlcmd @splat
}
$credSplat = @{
TypeName = 'System.Management.Automation.PSCredential'
ArgumentList = 'duffney',('P@ssw0rd' | ConvertTo-SecureString -AsPlainText -Force)
}
$Credential = New-Object @credSplat
Get-AllSQLDatabases -SQLServer SQL01 -Credential $Credential
Administración continua de credenciales de aprendizaje
La creación y el almacenamiento de objetos de credenciales de forma segura pueden ser difíciles. Los siguientes recursos pueden ayudarle a mantener las credenciales de PowerShell.