> 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 per 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. {% hint style="success" %} 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. {% endhint %} ### 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: ```powershell [Parameter(Mandatory)] [string]$IdentityProviderEndpoint, [Parameter(Mandatory)] [string]$IdentityProviderEndpointUserName, [Parameter(Mandatory)] [securestring]$IdentityProviderEndpointPassword ``` {% hint style="success" %} 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. {% endhint %} 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. ```powershell .\actionscript.ps1 -IdentityProviderEndpoint 'hostname' -IdentityProviderEndpointUserName 'admin' -IdentityProviderEndpointPassword (ConvertTo-SecureString -String 'P@$$word' -AsPlainText -Force) ``` ![](https://cdnweb.devolutions.net/docs/ab_how-to-articles-create-anyidentity-action-scripts_3-8.png) 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. ![](https://cdnweb.devolutions.net/docs/DVLS4217_2025_2.png) 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. ```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 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. ![](https://cdnweb.devolutions.net/docs/DVLS4218_2025_2.png) ### 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. ```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' ``` ![](https://cdnweb.devolutions.net/docs/DVLS4219_2025_2.png) ```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' ``` ![](https://cdnweb.devolutions.net/docs/DVLS4220_2025_2.png) {% 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="" %} 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. ```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 lo si testa (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. ![](https://cdnweb.devolutions.net/docs/ab_how-to-articles-create-anyidentity-action-scripts_8-8.png) ### Heartbeat {% embed url="" %} 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. ```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`, 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. ```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.