Benutzerdefinierte PAM-Anbieter-Aktionsskripte 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.

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.

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:

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

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.

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.

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

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.

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.

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

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.

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'

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.

Kontenerkennung

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.

  ## 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 werden die Felder Username und Unique Identifier mit den Eigenschaftswerten für die Eigenschaften username und id aus dem Aktionsskript gefüllt.

Heartbeat

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.

[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

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.

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