Créer un script d'action de fournisseur PAM personnalisé dans Devolutions Server

L'utilisation des fournisseurs PAM personnalisés nécessite la création de scripts d'action, qui sont placés dans la section Script de chaque action pendant le processus de création de modèle.

Les scripts d'action sont des scripts PowerShell exécutés par Devolutions PAM, et les mêmes meilleures pratiques applicables à tout script PowerShell doivent être suivies. Cependant, il y a des nuances spécifiques à considérer lors de la rédaction de scripts d'action.

Chaque script d'action doit inclure un ensemble de paramètres à travers lesquels le fournisseur PAM personnalisé passe les valeurs. Alors que les détails peuvent varier, les scripts d'actions doivent partager un ensemble commun de paramètres pour se connecter au point d'accès du fournisseur d'identité. Voici un exemple de comment définir ceux-ci :

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

Dans cet exemple, chaque paramètre est marqué comme obligatoire, forçant le fournisseur à les utiliser. Assurez-vous d'utiliser le type securestring pour le paramètre IdentityEndpointPassword, car les fournisseurs PAM personnalisés l'exigent pour empêcher la transmission et le traitement des mots de passe en clair.

Lors de la construction du modèle de fournisseur PAM personnalisé, ces paramètres de point d'accès du fournisseur d'identité correspondent à ceux définis lors du processus de création de modèle.

Quand il être nécessaire de fournir la capacité de passer une valeur à un paramètre de script sans le requérir, ce paramètre être considéré comme optionnel, et est utilisé uniquement lorsqu'une valeur lui être passée.

Lors de la création d'un modèle de fournisseur PAM personnalisé, il est possible de définir les propriétés du fournisseur et du compte, et de spécifier si elles sont obligatoires ou optionnelles.

Les paramètres au sein du script d'action pour le fournisseur mentionné ci-dessus peuvent être structurés comme suit, chacun correspondant aux propriétés du modèle de fournisseur PAM personnalisé et des valeurs par défaut assignées aux paramètres optionnels.

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

Si ce script PowerShell est exécuté en dehors du fournisseur PAM personnalisé sans que les paramètres optionnels soient spécifiés, il fonctionnera comme prévu, en utilisant les valeurs par défaut.

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

Cependant, lors de la construction du modèle de fournisseur PAM personnalisé et de la fourniture uniquement des paramètres obligatoires, s'appuyant sur les valeurs par défaut internes du script, les fournisseurs PAM personnalisés écrasent ces valeurs par défaut.

Quand les fournisseurs PAM personnalisés exécutent un script d'action, il transmet invariablement des valeurs à tous les paramètres. Dans les cas où aucune valeur n'est définie, les fournisseurs PAM personnalisés passent une valeur null, ou si le paramètre est de type entier, une valeur 0.

Pour contourner cela, ne pas définir de valeurs par défaut dans les paramètres du script. À la place, déterminer les valeurs par défaut avec des conditions dans le script.

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

Bien qu'il ne soit généralement pas recommandé par les meilleures pratiques PowerShell, fournir des valeurs par défaut de paramètres de cette manière est une exigence pour les fournisseurs PAM personnalisés.

Les scripts d'actions sont finalement exécutés dans l'environnement des fournisseurs PAM personnalisés. Tout output qu'ils génèrent est interprété, stocké et/ou affiché dans l'interface Web du Devolutions Server.

Pour garantir que les scripts d'actions produisent la sortie attendue, il est recommandé qu'ils renvoient la sortie de quatre manières seulement :

• Utiliser le mot-clé throw pour générer une erreur fatale en utilisant le flux d'erreur.

• Utiliser l'applet de commande Write-Error pour générer une erreur non fatale en utilisant le flux d'erreur.

• Utiliser l'applet de commande Write-Output pour retourner des informations au flux de sortie.

• Transmettre les informations de sortie directement au flux de sortie.

Ci-dessous sont des exemples de scripts d'actions et les résultats correspondants dans la fonctionnalité Tester le script de la zone Résultats des fournisseurs PAM personnalisés.

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'

La première action exécutée par un fournisseur PAM personnalisé est l'action de détection de compte, qui énumère les comptes sur un fournisseur d'identité et peuple la base de données de Devolutions Server pour de la gestion ultérieure.

• Paramètres d'entrée requis

  Le script d'action de détection de compte être relativement simple, car il requérir principalement des paramètres de script de point de terminaison communs. Aucun paramètre supplémentaire ne être nécessaire à moins qu'il ne soit imposé par le fournisseur d'identité spécifique.

• Paramètres de sortie requis

  Chaque script d'action de détection de compte doit retourner un ou plusieurs objets de type PSCustomObject, chaque objet représentant un compte individuel et contenant trois propriétés : id, username, et secret.

  • La propriété id doit servir d'identificateur unique pour chaque compte. Alors que cet identificateur être généralement un nom d'utilisateur, il peut être tout identificateur unique pour le compte.

  • La propriété username doit servir d'étiquette pour chaque compte. Cette étiquette est généralement un nom d'utilisateur mais peut être tout identifiant qui représente le compte.

  • La propriété secret est l'identifiant du mot de passe. Cela peut prendre la forme d'une chaîne chiffrée ou d'un mot de passe en texte clair, qui est ensuite utilisé pour comparaison avec d'autres secrets via l'action de pulsation.

  Si le code du fournisseur d'identité ne retourne pas nativement cet objet avec les propriétés spécifiées, il est nécessaire de le convertir en créant un PSCustomObject. Vous trouverez ci-dessous un exemple de comment procéder.

  ## 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
  

  Lors de la création d'un modèle de fournisseur PAM personnalisé et de son test (instructions fournies ci-dessous) avec une configuration de scan, les champs Nom d'utilisateur et Identifiant Unique sont renseignés avec les valeurs des propriétés pour les propriétés username et id du script d'action.

Après la récupération de tous les comptes du fournisseur d'identité par l'action de détection de compte, une action de pulsation est initiée. Cela lit la valeur actuelle du mot de passe d'un compte et la compare à la valeur enregistrée par PAM. Si les deux valeurs diffèrent, un changement est détecté.

• Paramètres d'entrée requis

  En plus des paramètres communs de point de terminaison, un script d'action de pulsation doit inclure au moins deux paramètres : username et secret, qui sont respectivement une string et une securestring.

• Paramètres de sortie requis

  Un script d'action de battement de cœur retourner un seul objet booléen ($true ou $false) pour indiquer si la valeur actuelle du mot de passe d'un compte correspond à la valeur connue par les modules PAM.

Voici un exemple de script d'action de pulsation.

[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

Lorsque les fournisseurs PAM personnalisés exécutent l'action de pulsation et que le script d'action renvoie une valeur $false, indiquant que le nouveau mot de passe diffère du mot de passe sur le fournisseur d'identité, l'action de rotation de mot de passe est déclenchée.

Cette action être responsable de synchroniser les mots de passe générés par le module PAM avec le fournisseur d'identité.

• Paramètres d'entrée requis

  En plus des paramètres de point d'accès communs, un script d'action de rotation de mot de passe doit inclure un paramètre : NewPassword. C'est un paramètre de type securestring qui permet aux fournisseurs PAM personnalisés de transmettre la nouvelle valeur du mot de passe au script d'action.

• Paramètres de sortie requis

  Le script de rotation de mot de passe ne doit retourner une valeur booléenne $true que si le changement de mot de passe est réussi.

Voici un exemple de base d'un script d'action de rotation de mot de passe.

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