> For the complete documentation index, see [llms.txt](https://docs.devolutions.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.devolutions.net/pam/it/knowledge-base/knowledge-base-articles/custom-pam-provider-action-scripts-in-devolutions-server.md). # Script di azione personalizzati dei provider PAM in Devolutions Server Scriva script di azione PowerShell per provider PAM personalizzati in Devolutions Server, che coprono il rilevamento degli account, l'heartbeat e la rotazione delle password. 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 rispettare le stesse best practice applicabili a qualsiasi script PowerShell. Tuttavia, esistono sfumature specifiche da considerare quando si scrivono gli script di azione. {% hint style="success" %} La padronanza dello scripting PowerShell è essenziale per creare provider PAM personalizzati. Si raccomanda di possedere almeno un livello intermedio di competenza nello scripting prima di tentare di creare script di azione. {% endhint %} ### Parametri dello script per l'endpoint del provider di identità Ogni script di azione deve includere un insieme di parametri attraverso i quali il provider PAM personalizzato trasmette i valori. Sebbene i dettagli 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: ```powershell [Parameter(Mandatory)] [string]$IdentityProviderEndpoint, [Parameter(Mandatory)] [string]$IdentityProviderEndpointUserName, [Parameter(Mandatory)] [securestring]$IdentityProviderEndpointPassword ``` {% hint style="success" %} Anche se esiste flessibilità nella denominazione dei parametri all'interno degli script di azione (purché 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. {% endhint %} In questo esempio, ogni parametro è contrassegnato come obbligatorio, costringendo il provider a utilizzarlo. 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. Quando si costruisce il 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 predefinite Quando è necessario offrire la possibilità di passare un valore a un parametro dello script senza però 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 menzionato sopra 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. ```powershell .\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 evitare ciò, non si dovrebbero impostare valori predefiniti all'interno dei parametri dello script. Al contrario, le condizioni all'interno dello script dovrebbero determinare i valori predefiniti. ```powershell [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 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 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 raccomanda che restituiscano l'output solo in quattro modi: * Utilizzi la parola chiave `throw` per generare un errore con interruzione tramite il flusso di errore. * Utilizzi il cmdlet `Write-Error` per generare un errore senza interruzione tramite il flusso di errore. * Utilizzi il cmdlet `Write-Output` per restituire informazioni al flusso di output. * Restituisca 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. ```powershell 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' ``` ```powershell 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' ``` {% hint style="success" %} 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`. {% endhint %} ### Rilevamento degli account {% embed url="" %} La prima azione 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 successiva gestione. * **Parametri di input richiesti** Lo script di azione per il rilevamento degli account è relativamente semplice, poiché richiede principalmente i parametri comuni dello script dell'endpoint. Non sono necessari parametri aggiuntivi, a meno che non siano imposti dallo specifico provider di identità. * **Output richiesto** Ogni script di azione per il 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 in genere 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 cifrata 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. ```powershell ## 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 si esegue il test (le istruzioni sono fornite di seguito) con una [configurazione di rilevamento degli account](/pam/it/pam-with-devolutions-server/account-discovery-configurations.md), i campi ***Username*** e ***Unique Identifier*** vengono popolati con i valori delle proprietà `username` e `id` dello script di azione. ### Heartbeat {% embed url="" %} Dopo il recupero di tutti gli account dal provider di identità da parte dell'azione di rilevamento degli account, viene avviata un'azione di heartbeat. Questa legge il valore attuale 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 di azione di heartbeat deve includere almeno due parametri: `username` e `secret`, che sono rispettivamente di tipo `string` e `securestring`. * **Output richiesto** Uno script di azione di heartbeat restituisce un singolo oggetto booleano (`$true` o `$false`) per indicare se il valore attuale della password di un account corrisponde al valore noto ai moduli PAM. Di seguito è riportato un esempio di script di azione di heartbeat. ```powershell [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 {% embed url="" %} Quando i provider PAM personalizzati eseguono l'azione di heartbeat e lo script di azione restituisce un valore `$false`, indicando che la nuova password differisce dalla password presente 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 di azione per la rotazione delle 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 delle password deve restituire un valore booleano `$true` solo se la modifica della password va a buon fine. Di seguito è riportato un esempio di base di script di azione per la rotazione delle password. ```powershell [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." } ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.devolutions.net/pam/it/knowledge-base/knowledge-base-articles/custom-pam-provider-action-scripts-in-devolutions-server.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.