> 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/de/knowledge-base/knowledge-base-articles/custom-pam-provider-action-scripts-in-devolutions-server.md). # Benutzerdefinierte Aktionsskripte für PAM-Anbieter in Devolutions Server Die Verwendung benutzerdefinierter PAM-Provider erfordert die Erstellung von Aktionsskripten, die während des Vorlagenerstellungsprozesses im Abschnitt ***Script*** jeder Aktion platziert werden. Aktionsskripte sind PowerShell-Skripte, die von Devolutions PAM ausgeführt werden, und es sollten dieselben Best Practices befolgt werden, die für jedes PowerShell-Skript gelten. Beim Schreiben von Aktionsskripten sind jedoch bestimmte Feinheiten zu beachten. {% hint style="success" %} Für die Erstellung benutzerdefinierter PAM-Provider sind fundierte Kenntnisse im PowerShell-Scripting unerlässlich. Es wird empfohlen, dass Personen mindestens über mittlere Scripting-Kenntnisse verfügen, bevor sie versuchen, Aktionsskripte zu erstellen. {% endhint %} ### Skriptparameter für den Identitätsprovider-Endpunkt Jedes Aktionsskript muss eine Reihe von Parametern enthalten, über die der benutzerdefinierte PAM-Provider Werte übergibt. Während die Einzelheiten variieren können, müssen Aktionsskripte einen gemeinsamen Satz von Parametern zur Verbindung mit dem Identitätsprovider-Endpunkt aufweisen. Nachfolgend ein Beispiel, wie diese definiert werden: ```powershell [Parameter(Mandatory)] [string]$IdentityProviderEndpoint, [Parameter(Mandatory)] [string]$IdentityProviderEndpointUserName, [Parameter(Mandatory)] [securestring]$IdentityProviderEndpointPassword ``` {% hint style="success" %} Obwohl bei der Benennung der Parameter innerhalb von Aktionsskripten Flexibilität besteht (sofern sie mit dem übereinstimmen, was während des Vorlagenerstellungsprozesses in benutzerdefinierten PAM-Providern angegeben wurde), ist es ratsam, einen Standardsatz von Parametern zu verwenden, um Konsistenz und Klarheit in den Namenskonventionen zu bewahren. {% endhint %} In diesem Beispiel ist jeder Parameter als erforderlich markiert, wodurch der Provider gezwungen wird, sie zu verwenden. Stellen Sie sicher, dass Sie den Typ `securestring` für den Parameter `IdentityEndpointPassword` verwenden, da benutzerdefinierte PAM-Provider dies vorschreiben, um die Übertragung und Verarbeitung von Klartextpasswörtern zu verhindern. Beim Erstellen der Vorlage für den benutzerdefinierten PAM-Provider entsprechen diese Parameter des Identitätsprovider-Endpunkts denen, die während des Vorlagenerstellungsprozesses definiert wurden. ### Umgang mit optionalen Standardberechtigungen Wenn Sie die Möglichkeit bieten möchten, einen Wert an einen Skriptparameter zu übergeben, ihn aber nicht erfordern, gilt dieser Parameter als optional und wird nur verwendet, wenn ihm ein Wert übergeben wird. Während der Erstellung einer Vorlage für einen benutzerdefinierten PAM-Provider ist es möglich, Provider- und Kontoeigenschaften zu definieren und anzugeben, ob sie erforderlich oder optional sind. Die Parameter innerhalb des Aktionsskripts für den oben genannten Provider können wie folgt strukturiert sein, wobei jeder den Eigenschaften der Vorlage des benutzerdefinierten PAM-Providers entspricht und den optionalen Parametern Standardwerte zugewiesen sind. ```` ```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." ```` Sollte dieses PowerShell-Skript außerhalb des benutzerdefinierten PAM-Providers ohne Angabe der optionalen Parameter ausgeführt werden, würde es wie erwartet funktionieren und die Standardwerte verwenden. ```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) Wenn jedoch die Vorlage des benutzerdefinierten PAM-Providers erstellt und nur die erforderlichen Parameter angegeben werden, wobei man sich auf die internen Standardwerte des Skripts verlässt, überschreiben benutzerdefinierte PAM-Provider diese Standardwerte. ![](https://cdnweb.devolutions.net/docs/DVLS4217_2025_2.png) Wenn benutzerdefinierte PAM-Provider ein Aktionsskript ausführen, übergeben sie ausnahmslos Werte an alle Parameter. In Fällen, in denen kein Wert definiert ist, übergeben benutzerdefinierte PAM-Provider einen `null`-Wert oder, wenn der Parameter vom Typ Integer ist, einen `0`-Wert. Um dies zu umgehen, sollten innerhalb der Skriptparameter keine Standardwerte festgelegt werden. Stattdessen sollten Bedingungen innerhalb des Skripts die Standardwerte bestimmen. ```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." ``` Obwohl es von den PowerShell-Best-Practices im Allgemeinen nicht empfohlen wird, ist die Bereitstellung von Standardparameterwerten auf diese Weise eine Voraussetzung für benutzerdefinierte PAM-Provider. ![](https://cdnweb.devolutions.net/docs/DVLS4218_2025_2.png) ### Umgang mit Ausgaben Aktionsskripte werden letztlich innerhalb der Umgebung der benutzerdefinierten PAM-Provider ausgeführt. Jede von ihnen erzeugte Ausgabe wird interpretiert, gespeichert und/oder in der Weboberfläche von Devolutions Server angezeigt. Um sicherzustellen, dass Aktionsskripte die erwartete Ausgabe erzeugen, wird empfohlen, dass sie Ausgaben nur auf vier Arten zurückgeben: * Verwenden Sie das Schlüsselwort `throw`, um über den Fehlerstream einen terminierenden Fehler zu erzeugen. * Verwenden Sie das Cmdlet `Write-Error`, um über den Fehlerstream einen nicht terminierenden Fehler zu erzeugen. * Verwenden Sie das Cmdlet `Write-Output`, um Informationen an den Ausgabestream zurückzugeben. * Geben Sie Informationen direkt an den Ausgabestream aus. Nachfolgend finden Sie Beispiele für Aktionsskripte und die entsprechenden Ergebnisse innerhalb der Funktion ***Test script*** im Bereich ***Results*** der benutzerdefinierten PAM-Provider. ```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" %} Um sicherzustellen, dass ein Aktionsskript Informationen an den benutzerdefinierten PAM-Provider zurückgibt, wird empfohlen, `Write-Verbose`, `Write-Information` oder `Write-Host` **nicht** zu verwenden. {% endhint %} ### Kontenerkennung {% embed url="" %} Die erste von einem benutzerdefinierten PAM-Provider ausgeführte Aktion ist die Kontenerkennungsaktion, die die Konten auf einem Identitätsprovider aufzählt und die Devolutions Server-Datenbank für die anschließende Verwaltung füllt. * **Erforderliche Eingabeparameter** Das Aktionsskript für die Kontenerkennung ist relativ einfach, da es hauptsächlich gängige Endpunkt-Skriptparameter erfordert. Es sind keine zusätzlichen Parameter notwendig, sofern der spezifische Identitätsprovider dies nicht vorschreibt. * **Erforderliche Ausgabe** Jedes Aktionsskript für die Kontenerkennung muss ein oder mehrere Objekte des Typs `PSCustomObject` zurückgeben, wobei jedes Objekt ein einzelnes Konto darstellt und drei Eigenschaften enthält: `id`, `username` und `secret`. * Die Eigenschaft `id` muss als eindeutige Kennung für jedes Konto dienen. Während diese Kennung typischerweise ein Benutzername ist, kann sie jede eindeutige Kennung für das Konto sein. * Die Eigenschaft `username` sollte als Bezeichnung für jedes Konto dienen. Diese Bezeichnung ist in der Regel ein Benutzername, kann aber jede Kennung sein, die das Konto repräsentiert. * Die Eigenschaft `secret` ist die Passwortkennung. Diese kann die Form einer verschlüsselten Zeichenfolge oder eines Klartextpassworts haben, das dann über die Heartbeat-Aktion mit anderen Secrets verglichen wird. Wenn der Code des Identitätsproviders dieses Objekt mit den angegebenen Eigenschaften nicht von sich aus zurückgibt, ist es notwendig, es durch Erstellen eines `PSCustomObject` zu konvertieren. Nachfolgend ein Beispiel, wie dies zu bewerkstelligen ist. ```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 ``` Beim Erstellen einer Vorlage für einen benutzerdefinierten PAM-Provider und deren Test (Anweisungen weiter unten) mit einer [Kontenerkennungskonfiguration](/pam/de/pam-with-devolutions-server/account-discovery-configurations.md) werden die Felder ***Username*** und ***Unique Identifier*** mit den Eigenschaftswerten für die Eigenschaften `username` und `id` aus dem Aktionsskript gefüllt. ![](https://cdnweb.devolutions.net/docs/ab_how-to-articles-create-anyidentity-action-scripts_8-8.png) ### Heartbeat {% embed url="" %} Nach dem Abrufen aller Konten vom Identitätsprovider durch die Kontenerkennungsaktion wird eine Heartbeat-Aktion initiiert. Diese liest den aktuellen Passwortwert eines Kontos und vergleicht ihn mit dem von PAM gespeicherten Wert. Wenn sich die beiden Werte unterscheiden, wird eine Änderung erkannt. * **Erforderliche Eingabeparameter** Zusätzlich zu den gängigen Endpunktparametern muss ein Heartbeat-Aktionsskript mindestens zwei Parameter enthalten: `username` und `secret`, die jeweils vom Typ `string` bzw. `securestring` sind. * **Erforderliche Ausgabe** Ein Heartbeat-Aktionsskript gibt ein einzelnes booleanes Objekt (`$true` oder `$false`) zurück, um anzugeben, ob der aktuelle Passwortwert eines Kontos mit dem den PAM-Modulen bekannten Wert übereinstimmt. Nachfolgend ein Beispiel für ein Heartbeat-Aktionsskript. ```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 ``` ### Passwortrotation {% embed url="" %} Wenn benutzerdefinierte PAM-Provider die Heartbeat-Aktion ausführen und das Aktionsskript einen `$false`-Wert zurückgibt, was darauf hinweist, dass sich das neue Passwort vom Passwort auf dem Identitätsprovider unterscheidet, wird die Passwortrotationsaktion ausgelöst. Diese Aktion ist für die Synchronisierung der vom PAM-Modul generierten Passwörter mit dem Identitätsprovider verantwortlich. * **Erforderliche Eingabeparameter** Zusätzlich zu den gängigen Endpunktparametern muss ein Aktionsskript für die Passwortrotation einen Parameter enthalten: `NewPassword`. Dies ist ein `securestring`-Parameter, der es benutzerdefinierten PAM-Providern ermöglicht, den neuen Passwortwert an das Aktionsskript zu übergeben. * **Erforderliche Ausgabe** Das Passwortrotationsskript sollte nur dann einen booleanen `$true`-Wert zurückgeben, wenn die Passwortänderung erfolgreich ist. Nachfolgend ein einfaches Beispiel für ein Aktionsskript zur Passwortrotation. ```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/de/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.