Script di azione personalizzati dei provider PAM in Devolutions Server

L'uso di provider PAM personalizzati richiede la creazione di script di azione, che vengono inseriti nella sezione Script di ogni azione durante il processo di creazione del modello.

Gli script di azione sono script PowerShell eseguiti da Devolutions PAM, e devono essere rispettate le stesse best practice applicabili a qualsiasi script PowerShell. Tuttavia, vi sono sfumature specifiche da considerare quando si scrivono script di azione.

La padronanza dello scripting PowerShell è essenziale per creare provider PAM personalizzati. Si consiglia di possedere almeno un livello intermedio di competenza nello scripting prima di tentare di creare script di azione.

Parametri degli script dell'endpoint del provider di identità

Ogni script di azione deve includere un insieme di parametri attraverso i quali il provider PAM personalizzato passa i valori. Sebbene le specifiche possano variare, gli script di azione devono condividere un insieme comune di parametri per connettersi all'endpoint del provider di identità. Di seguito è riportato un esempio di come definirli:

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

Sebbene vi sia flessibilità nella denominazione dei parametri all'interno degli script di azione (a condizione che corrispondano a quanto specificato durante il processo di creazione del modello nei provider PAM personalizzati), è consigliabile utilizzare un insieme standard di parametri per mantenere coerenza e chiarezza nelle convenzioni di denominazione.

In questo esempio, ogni parametro è contrassegnato come obbligatorio, costringendo il provider a utilizzarli. Si assicuri di utilizzare il tipo securestring per il parametro IdentityEndpointPassword, poiché i provider PAM personalizzati lo richiedono per impedire la trasmissione e l'elaborazione di password in chiaro.

Durante la creazione del modello del provider PAM personalizzato, questi parametri dell'endpoint del provider di identità corrispondono a quelli definiti durante il processo di creazione del modello.

Gestione delle autorizzazioni opzionali e predefinite

Quando è necessario offrire la possibilità di passare un valore a un parametro di script senza renderlo obbligatorio, tale parametro è considerato opzionale e viene utilizzato solo quando gli viene passato un valore.

Durante la creazione di un modello di provider PAM personalizzato, è possibile definire le proprietà del provider e dell'account e specificare se sono obbligatorie o opzionali.

I parametri all'interno dello script di azione per il provider sopra menzionato possono essere strutturati come segue, con ciascuno corrispondente alle proprietà del modello del provider PAM personalizzato e con valori predefiniti assegnati ai parametri opzionali.

```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."

Se questo script PowerShell venisse eseguito al di fuori del provider PAM personalizzato senza specificare i parametri opzionali, funzionerebbe come previsto, utilizzando i valori predefiniti.

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

Tuttavia, quando si costruisce il modello del provider PAM personalizzato fornendo solo i parametri obbligatori e affidandosi ai valori predefiniti interni dello script, i provider PAM personalizzati sovrascrivono tali valori predefiniti.

Quando i provider PAM personalizzati eseguono uno script di azione, passano invariabilmente valori a tutti i parametri. Nei casi in cui non sia definito alcun valore, i provider PAM personalizzati passano un valore null oppure, se il parametro è di tipo intero, un valore 0.

Per ovviare a questo, non si dovrebbero impostare valori predefiniti nei parametri dello script. Al contrario, dovrebbero essere le condizioni all'interno dello script a determinare i valori predefiniti.

[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."

Sebbene ciò non sia generalmente raccomandato dalle best practice di PowerShell, fornire i valori predefiniti dei parametri in questo modo è un requisito per i provider PAM personalizzati.

Gestione dell'output

Gli script di azione vengono in definitiva eseguiti all'interno dell'ambiente dei provider PAM personalizzati. Qualsiasi output da essi generato viene interpretato, memorizzato e/o visualizzato nell'interfaccia web di Devolutions Server.

Per garantire che gli script di azione producano l'output previsto, si consiglia di restituire l'output solo in quattro modi:

• Usare la parola chiave throw per generare un errore di terminazione tramite il flusso degli errori.
• Usare il cmdlet Write-Error per generare un errore non di terminazione tramite il flusso degli errori.
• Usare il cmdlet Write-Output per restituire informazioni al flusso di output.
• Restituire le informazioni direttamente al flusso di output.

Di seguito sono riportati esempi di script di azione e i risultati corrispondenti all'interno della funzionalità Test script nell'area Results dei provider PAM personalizzati.

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'

Per garantire che uno script di azione restituisca informazioni al provider PAM personalizzato, si consiglia di non utilizzare Write-Verbose, Write-Information o Write-Host.

Rilevamento degli account

L'azione iniziale eseguita da un provider PAM personalizzato è l'azione di rilevamento degli account, che enumera gli account su un provider di identità e popola il database di Devolutions Server per la gestione successiva.

• Parametri di input richiesti

  Lo script dell'azione di rilevamento degli account è relativamente semplice, poiché richiede principalmente i parametri comuni degli script dell'endpoint. Non sono necessari parametri aggiuntivi, a meno che non siano richiesti dallo specifico provider di identità.
• Output richiesto

  Ogni script dell'azione di rilevamento degli account deve restituire uno o più oggetti di tipo PSCustomObject, dove ogni oggetto rappresenta un singolo account e contiene tre proprietà: id, username e secret.

  • La proprietà id deve fungere da identificatore univoco per ogni account. Sebbene questo identificatore sia generalmente un nome utente, può essere qualsiasi identificatore univoco dell'account.
  • La proprietà username deve fungere da etichetta per ogni account. Questa etichetta è generalmente un nome utente, ma può essere qualsiasi identificatore che rappresenti l'account.
  • La proprietà secret è l'identificatore della password. Può assumere la forma di una stringa crittografata o di una password in chiaro, che viene poi utilizzata per il confronto con altri segreti tramite l'azione di heartbeat.

  Se il codice del provider di identità non restituisce nativamente questo oggetto con le proprietà specificate, è necessario convertirlo creando un PSCustomObject. Di seguito è riportato un esempio di come procedere.

  ## 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

  Quando si crea un modello di provider PAM personalizzato e lo si testa (le istruzioni sono fornite di seguito) con una configurazione di rilevamento degli account, i campi Username e Unique Identifier vengono popolati con i valori delle proprietà username e id dello script di azione.

Heartbeat

Dopo il recupero di tutti gli account dal provider di identità tramite l'azione di rilevamento degli account, viene avviata un'azione di heartbeat. Questa legge il valore corrente della password di un account e lo confronta con il valore memorizzato da PAM. Se i due valori differiscono, viene rilevata una modifica.

• Parametri di input richiesti

  Oltre ai parametri comuni dell'endpoint, uno script dell'azione di heartbeat deve includere almeno due parametri: username e secret, che sono rispettivamente di tipo string e securestring.
• Output richiesto

  Uno script dell'azione di heartbeat restituisce un singolo oggetto booleano ($true o $false) per indicare se il valore corrente della password di un account corrisponde al valore noto ai moduli PAM.

Di seguito è riportato un esempio di script dell'azione di heartbeat.

[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

Rotazione delle password

Quando i provider PAM personalizzati eseguono l'azione di heartbeat e lo script di azione restituisce un valore $false, a indicare che la nuova password differisce dalla password sul provider di identità, viene attivata l'azione di rotazione della password.

Questa azione è responsabile della sincronizzazione delle password generate dal modulo PAM con il provider di identità.

• Parametri di input richiesti

  Oltre ai parametri comuni dell'endpoint, uno script dell'azione di rotazione della password deve includere un parametro: NewPassword. Si tratta di un parametro securestring che consente ai provider PAM personalizzati di passare il valore della nuova password allo script di azione.
• Output richiesto

  Lo script di rotazione della password deve restituire un valore booleano $true solo se la modifica della password ha avuto esito positivo.

Di seguito è riportato un esempio di base di uno script dell'azione di rotazione della password.

[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."
}