> 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 PAM-Anbieter-Aktionsskripte in Devolutions Server Schreiben Sie PowerShell-Aktionsskripte für benutzerdefinierte PAM-Anbieter in Devolutions Server – für Kontenerkennung, Heartbeat und Passwortrotation. Die Verwendung benutzerdefinierter PAM-Anbieter erfordert die Erstellung von Aktionsskripten, die während der Vorlagenerstellung im Abschnitt ***Skript*** jeder Aktion platziert werden. Aktionsskripte sind PowerShell-Skripte, die von Devolutions PAM ausgeführt werden, und es sollten dieselben Best Practices eingehalten werden, die für jedes PowerShell-Skript gelten. Beim Schreiben von Aktionsskripten sind jedoch bestimmte Besonderheiten zu beachten. {% hint style="success" %} Kenntnisse im PowerShell-Scripting sind für die Erstellung benutzerdefinierter PAM-Anbieter unerlässlich. Es wird empfohlen, dass Personen mindestens über ein mittleres Scripting-Niveau verfügen, bevor sie versuchen, Aktionsskripte zu erstellen. {% endhint %} ### Skriptparameter für den Identitätsanbieter-Endpunkt Jedes Aktionsskript muss einen Satz von Parametern enthalten, über die der benutzerdefinierte PAM-Anbieter Werte übergibt. Auch wenn die Einzelheiten variieren können, müssen Aktionsskripte einen gemeinsamen Satz von Parametern zur Verbindung mit dem Identitätsanbieter-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 den Angaben übereinstimmen, die während der Vorlagenerstellung in benutzerdefinierten PAM-Anbietern festgelegt wurden), ist es ratsam, einen Standardsatz von Parametern zu verwenden, um Konsistenz und Klarheit in den Namenskonventionen zu gewährleisten. {% endhint %} In diesem Beispiel ist jeder Parameter als obligatorisch gekennzeichnet, wodurch der Anbieter gezwungen wird, sie zu verwenden. Verwenden Sie für den Parameter `IdentityEndpointPassword` unbedingt den Typ `securestring`, da benutzerdefinierte PAM-Anbieter dies vorschreiben, um die Übertragung und Verarbeitung von Klartextpasswörtern zu verhindern. Beim Erstellen der Vorlage für den benutzerdefinierten PAM-Anbieter entsprechen diese Parameter des Identitätsanbieter-Endpunkts denjenigen, 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, ohne dies zu verlangen, gilt dieser Parameter als optional und wird nur verwendet, wenn ihm ein Wert übergeben wird. Bei der Erstellung einer Vorlage für einen benutzerdefinierten PAM-Anbieter ist es möglich, Anbieter- und Kontoeigenschaften zu definieren und festzulegen, ob sie obligatorisch oder optional sind. Die Parameter innerhalb des Aktionsskripts für den oben genannten Anbieter können wie folgt strukturiert sein, wobei jeder den Eigenschaften der Vorlage des benutzerdefinierten PAM-Anbieters entspricht und den optionalen Parametern Standardwerte zugewiesen werden. ```` ```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-Anbieters 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) ``` Wenn jedoch die Vorlage für den benutzerdefinierten PAM-Anbieter erstellt und nur die obligatorischen Parameter bereitgestellt werden, wobei man sich auf die internen Standardwerte des Skripts verlässt, überschreiben benutzerdefinierte PAM-Anbieter diese Standardwerte. Wenn benutzerdefinierte PAM-Anbieter ein Aktionsskript ausführen, übergeben sie ausnahmslos Werte an alle Parameter. In Fällen, in denen kein Wert definiert ist, übergeben benutzerdefinierte PAM-Anbieter 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 dies von den PowerShell-Best-Practices generell nicht empfohlen wird, ist die Bereitstellung von Standardparameterwerten auf diese Weise eine Anforderung für benutzerdefinierte PAM-Anbieter. ### Umgang mit der Ausgabe Aktionsskripte werden letztlich innerhalb der Umgebung der benutzerdefinierten PAM-Anbieter 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 eine Ausgabe nur auf vier Wege zurückgeben: * Verwenden Sie das Schlüsselwort `throw`, um über den Fehlerstream einen abbrechenden Fehler zu erzeugen. * Verwenden Sie das Cmdlet `Write-Error`, um über den Fehlerstream einen nicht abbrechenden 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 ***Skript testen*** im Bereich ***Ergebnisse*** der benutzerdefinierten PAM-Anbieter. ```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" %} Um sicherzustellen, dass ein Aktionsskript Informationen an den benutzerdefinierten PAM-Anbieter zurückgibt, wird empfohlen, `Write-Verbose`, `Write-Information` oder `Write-Host` **nicht** zu verwenden. {% endhint %} ### Kontenerkennung {% embed url="" %} Die erste von einem benutzerdefinierten PAM-Anbieter ausgeführte Aktion ist die Kontenerkennungsaktion, die die Konten auf einem Identitätsanbieter 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 benötigt. Zusätzliche Parameter sind nicht erforderlich, es sei denn, der spezifische Identitätsanbieter schreibt dies vor. * **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 eindeutiger Identifikator für jedes Konto dienen. Während dieser Identifikator typischerweise ein Benutzername ist, kann er jeder eindeutige Identifikator 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 jeder Identifikator sein, der das Konto darstellt. * Die Eigenschaft `secret` ist der Passwort-Identifikator. Dieser kann die Form einer verschlüsselten Zeichenfolge oder eines Klartextpassworts annehmen, das dann über die Heartbeat-Aktion mit anderen Secrets verglichen wird. Wenn der Code des Identitätsanbieters dieses Objekt mit den angegebenen Eigenschaften nicht von sich aus zurückgibt, ist es notwendig, es durch die Erstellung eines `PSCustomObject` zu konvertieren. Nachfolgend ein Beispiel, wie dies erreicht wird. ```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-Anbieter und deren Testen (Anleitung siehe unten) mit einer [Kontenerkennungskonfiguration](/pam/de/pam-with-devolutions-server/account-discovery-configurations.md) werden die Felder ***Benutzername*** und ***Eindeutiger Identifikator*** mit den Eigenschaftswerten für die Eigenschaften `username` und `id` aus dem Aktionsskript gefüllt. ### Heartbeat {% embed url="" %} Nachdem die Kontenerkennungsaktion alle Konten vom Identitätsanbieter abgerufen hat, wird eine Heartbeat-Aktion eingeleitet. Diese liest den aktuellen Passwortwert eines Kontos und vergleicht ihn mit dem von PAM gespeicherten Wert. Wenn die beiden Werte voneinander abweichen, 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 ein `string` und ein `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-Anbieter die Heartbeat-Aktion ausführen und das Aktionsskript einen `$false`-Wert zurückgibt, was bedeutet, dass sich das neue Passwort vom Passwort beim Identitätsanbieter unterscheidet, wird die Passwortrotationsaktion ausgelöst. Diese Aktion ist für die Synchronisierung der vom PAM-Modul generierten Passwörter mit dem Identitätsanbieter verantwortlich. * **Erforderliche Eingabeparameter** Zusätzlich zu den gängigen Endpunktparametern muss ein Passwortrotations-Aktionsskript einen Parameter enthalten: `NewPassword`. Dies ist ein `securestring`-Parameter, der benutzerdefinierten PAM-Anbietern 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 Passwortrotations-Aktionsskript. ```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.