Scripts de acción personalizados de proveedores PAM en Devolutions Server

El uso de proveedores PAM personalizados requiere la creación de scripts de acción, que se colocan en la sección Script de cada acción durante el proceso de creación de la plantilla.

Los scripts de acción son scripts de PowerShell ejecutados por Devolutions PAM, y deben seguirse las mismas buenas prácticas aplicables a cualquier script de PowerShell. Sin embargo, hay matices específicos que se deben tener en cuenta al escribir scripts de acción.

El dominio de la creación de scripts de PowerShell es esencial para crear proveedores PAM personalizados. Se recomienda que las personas posean al menos un nivel intermedio de habilidad en scripting antes de intentar crear scripts de acción.

Parámetros de script del endpoint del proveedor de identidad

Cada script de acción debe incluir un conjunto de parámetros a través de los cuales el proveedor PAM personalizado pasa valores. Aunque los detalles pueden variar, los scripts de acción deben compartir un conjunto común de parámetros para conectarse al endpoint del proveedor de identidad. A continuación se muestra un ejemplo de cómo definirlos:

[Parameter(Mandatory)]
[string]$IdentityProviderEndpoint,
[Parameter(Mandatory)]
[string]$IdentityProviderEndpointUserName,
[Parameter(Mandatory)]
[securestring]$IdentityProviderEndpointPassword

Aunque existe flexibilidad para nombrar los parámetros dentro de los scripts de acción (siempre que coincidan con lo especificado durante el proceso de creación de la plantilla en los proveedores PAM personalizados), es aconsejable utilizar un conjunto estándar de parámetros para mantener la coherencia y la claridad en las convenciones de nomenclatura.

En este ejemplo, cada parámetro está marcado como obligatorio, lo que fuerza al proveedor a utilizarlos. Asegúrese de utilizar el tipo securestring para el parámetro IdentityEndpointPassword, ya que los proveedores PAM personalizados lo exigen para evitar la transmisión y el procesamiento de contraseñas en texto plano.

Al construir la plantilla del proveedor PAM personalizado, estos parámetros del endpoint del proveedor de identidad se corresponden con los definidos durante el proceso de creación de la plantilla.

Gestión de permisos opcionales y predeterminados

Cuando necesita ofrecer la posibilidad de pasar un valor a un parámetro de script sin exigirlo, ese parámetro se considera opcional y solo se utiliza cuando se le pasa un valor.

Durante la creación de una plantilla de proveedor PAM personalizado, es posible definir propiedades del proveedor y de la cuenta, y especificar si son obligatorias u opcionales.

Los parámetros dentro del script de acción para el proveedor mencionado anteriormente pueden estructurarse de la siguiente manera, coincidiendo cada uno con las propiedades de la plantilla del proveedor PAM personalizado y con los valores predeterminados asignados a los parámetros opcionales.

```powershell
[CmdletBinding()]
param(
    [Parameter(Mandatory)]
    [string]$IdentityProviderEndpoint,

    [Parameter(Mandatory)]
    [string]$IdentityProviderEndpointUserName,

    [Parameter(Mandatory)]
    [securestring]$IdentityProviderEndpointPassword,

    [Parameter()]
    [string]$Instance = '.',

    [Parameter()]
    [int]$Port = 1433
)
Write-Host "Using the instance of [$Instance] and the port of [$Port] here in the code somewhere."

Si este script de PowerShell se ejecutase fuera del proveedor PAM personalizado sin especificar los parámetros opcionales, funcionaría como cabría esperar, utilizando los valores predeterminados.

.\actionscript.ps1 -IdentityProviderEndpoint 'hostname' -IdentityProviderEndpointUserName 'admin' -IdentityProviderEndpointPassword (ConvertTo-SecureString -String 'P@$$word' -AsPlainText -Force)

Sin embargo, al construir la plantilla del proveedor PAM personalizado y proporcionar únicamente los parámetros obligatorios, confiando en los valores predeterminados internos del script, los proveedores PAM personalizados anulan estos valores predeterminados.

Cuando los proveedores PAM personalizados ejecutan un script de acción, siempre pasan valores a todos los parámetros. En los casos en los que no se define ningún valor, los proveedores PAM personalizados pasan un valor null o, si el parámetro es de tipo entero, un valor 0.

Para evitar esto, no se deben establecer valores predeterminados en los parámetros del script. En su lugar, las condiciones dentro del script deben determinar los valores predeterminados.

[CmdletBinding()]
param(
    [Parameter(Mandatory)]
    [string]$IdentityProviderEndpoint,

    [Parameter(Mandatory)]
    [string]$IdentityProviderEndpointUserName,

    [Parameter(Mandatory)]
    [securestring]$IdentityProviderEndpointPassword,

    [Parameter()]
    [string]$Instance,

    [Parameter()]
    [int]$Port
)
if (!$Instance) { $Instance = '.' }
if (!$Port) { $Port = 1433 }
Write-Output "Using the instance of [$Instance] and the port of [$Port] here in the code somewhere."

Aunque las buenas prácticas de PowerShell no lo recomiendan en general, proporcionar valores de parámetros predeterminados de esta manera es un requisito para los proveedores PAM personalizados.

Gestión de la salida

Los scripts de acción se ejecutan en última instancia dentro del entorno de los proveedores PAM personalizados. Cualquier salida que generen se interpreta, se almacena y/o se muestra en la interfaz web de Devolutions Server.

Para garantizar que los scripts de acción produzcan la salida esperada, se recomienda que devuelvan la salida únicamente de cuatro formas:

• Utilice la palabra clave throw para generar un error de terminación mediante el flujo de errores.
• Utilice el cmdlet Write-Error para generar un error que no sea de terminación mediante el flujo de errores.
• Utilice el cmdlet Write-Output para devolver información al flujo de salida.
• Envíe la información directamente al flujo de salida.

A continuación se muestran ejemplos de scripts de acción y los resultados correspondientes dentro de la funcionalidad Probar script en el área de Resultados de los proveedores PAM personalizados.

Write-Verbose -Message 'This is a verbose message.'
Write-Information -MessageData 'information action'
Write-Output 'output stream here'
Write-Host 'write-host output here'
Write-Error 'error'

Write-Verbose -Message 'This is a verbose message.'
Write-Information -MessageData 'information action'
Write-Output 'output stream here'
'output stream here directly'
Write-Host 'write-host output here'

Para garantizar que un script de acción devuelva información al proveedor PAM personalizado, se recomienda no utilizar Write-Verbose, Write-Information ni Write-Host.

Descubrimiento de cuentas

La acción inicial ejecutada por un proveedor PAM personalizado es la acción de descubrimiento de cuentas, que enumera las cuentas de un proveedor de identidad y rellena la base de datos de Devolutions Server para su posterior gestión.

• Parámetros de entrada obligatorios

  El script de acción de descubrimiento de cuentas es relativamente sencillo, ya que principalmente requiere los parámetros de script comunes del endpoint. No son necesarios parámetros adicionales, salvo que lo exija el proveedor de identidad concreto.
• Salida obligatoria

  Cada script de acción de descubrimiento de cuentas debe devolver uno o más objetos de tipo PSCustomObject, representando cada objeto una cuenta individual y conteniendo tres propiedades: id, username y secret.

  • La propiedad id debe servir como identificador único de cada cuenta. Aunque este identificador suele ser un nombre de usuario, puede ser cualquier identificador único de la cuenta.
  • La propiedad username debe servir como etiqueta para cada cuenta. Esta etiqueta suele ser un nombre de usuario, pero puede ser cualquier identificador que represente la cuenta.
  • La propiedad secret es el identificador de la contraseña. Puede adoptar la forma de una cadena cifrada o de una contraseña en texto plano, que después se utiliza para comparar con otros secretos mediante la acción de latido (heartbeat).

  Si el código del proveedor de identidad no devuelve de forma nativa este objeto con las propiedades especificadas, es necesario convertirlo creando un PSCustomObject. A continuación se muestra un ejemplo de cómo lograrlo.

  ## Some code that returns an object for each account.
  $accounts = Get-AccountFromIdentityProvider
  
  ## Create custom fields for Select-Object to return the id and username properties instead of name, and name
  $selectProps = @(
      @{'n'='id';e={$_.name}} ## "convert" the name property from the account to id
      @{'n'='username';e={$_.name}} ## "convert" the name property from the account to username
      @{'n'='secret';e={$_.password_hash}} ## "convert" the password_hash property from the account to secret
  )
  
  ## Pass each account to Select-Object to return the property names.
  $accounts | Select-Object -Property $selectProps

  Al crear una plantilla de proveedor PAM personalizado y probarla (las instrucciones se indican más abajo) con una configuración de descubrimiento de cuentas, los campos Nombre de usuario e Identificador único se rellenan con los valores de las propiedades username e id del script de acción.

Latido (heartbeat)

Tras la recuperación de todas las cuentas del proveedor de identidad mediante la acción de descubrimiento de cuentas, se inicia una acción de latido (heartbeat). Esta lee el valor actual de la contraseña de una cuenta y lo compara con el valor almacenado por PAM. Si los dos valores difieren, se detecta un cambio.

• Parámetros de entrada obligatorios

  Además de los parámetros comunes del endpoint, un script de acción de latido debe incluir al menos dos parámetros: username y secret, que son respectivamente de tipo string y securestring.
• Salida obligatoria

  Un script de acción de latido devuelve un único objeto booleano ($true o $false) para indicar si el valor actual de la contraseña de una cuenta coincide con el valor conocido por los módulos PAM.

A continuación se muestra un ejemplo de un script de acción de latido.

[CmdletBinding()]
param(
    [Parameter(Mandatory)]
    [string]$IdentityProviderEndpoint,

    [Parameter(Mandatory)]
    [string]$IdentityProviderEndpointUserName,

    [Parameter(Mandatory)]
    [securestring]$IdentityProviderEndpointPassword,

    [Parameter(Mandatory)]
    [string]$UserName,

    [Parameter(Mandatory)]
    [securestring]$Secret
)

## Code to query for a single user account here. Let's say it is $account.

## Convert the password to a secure string.
$secPw = $account.password | ConvertTo-SecureString -AsPlainText -Force

## Compare the results.
$secPw -eq $Secret

Rotación de contraseñas

Cuando los proveedores PAM personalizados ejecutan la acción de latido y el script de acción devuelve un valor $false, lo que indica que la nueva contraseña difiere de la contraseña del proveedor de identidad, se desencadena la acción de rotación de contraseñas.

Esta acción se encarga de sincronizar las contraseñas generadas por el módulo PAM con el proveedor de identidad.

• Parámetros de entrada obligatorios

  Además de los parámetros comunes del endpoint, un script de acción de rotación de contraseñas debe incluir un parámetro: NewPassword. Se trata de un parámetro securestring que permite a los proveedores PAM personalizados pasar el nuevo valor de la contraseña al script de acción.
• Salida obligatoria

  El script de rotación de contraseñas solo debe devolver un valor booleano $true si el cambio de contraseña se realiza correctamente.

A continuación se muestra un ejemplo básico de un script de acción de rotación de contraseñas.

[CmdletBinding()]
param(
    [Parameter(Mandatory)]
    [string]$IdentityProviderEndpoint,

    [Parameter(Mandatory)]
    [string]$IdentityProviderEndpointUserName,

    [Parameter(Mandatory)]
    [securestring]$IdentityProviderEndpointPassword,

    [Parameter(Mandatory)]
    [securestring]$NewPassword
)

## $result = Dowhatevertochangethepasword
if ($Result) {
    $True
} else {
    Write-Error "Failed to update secret."
}