Scripts d'action de fournisseur PAM personnalisé dans Devolutions Server

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

Les scripts d'action sont des scripts PowerShell exécutés par Devolutions PAM, et les mêmes bonnes pratiques applicables à tout script PowerShell doivent être respectées. Cependant, il existe des nuances spécifiques à prendre en compte lors de la rédaction de scripts d'action.

La maîtrise des scripts PowerShell est essentielle pour créer des fournisseurs PAM personnalisés. Il est recommandé que les personnes possèdent au moins un niveau intermédiaire de compétence en script avant de tenter de créer des scripts d'action.

Paramètres de script du point de terminaison du fournisseur d'identité

Chaque script d'action doit inclure un ensemble de paramètres par lesquels le fournisseur PAM personnalisé transmet des valeurs. Bien que les spécificités puissent varier, les scripts d'action doivent partager un ensemble commun de paramètres pour se connecter au point de terminaison du fournisseur d'identité. Voici un exemple de la façon de les définir :

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

Bien qu'il existe une flexibilité dans la dénomination des paramètres dans les scripts d'action (à condition qu'ils correspondent à ce qui est spécifié lors du processus de création du modèle dans les fournisseurs PAM personnalisés), il est conseillé d'utiliser un ensemble standard de paramètres pour maintenir la cohérence et la clarté des conventions de nommage.

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 de mots de passe en texte clair.

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

Gestion des autorisations facultatives et par défaut

Lorsque vous devez permettre de passer une valeur à un paramètre de script sans l'exiger, ce paramètre est considéré comme facultatif et n'est utilisé que lorsqu'une valeur lui est transmise.

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

Les paramètres 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 les valeurs par défaut étant attribuées aux paramètres facultatifs.

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

Si ce script PowerShell est exécuté en dehors du fournisseur PAM personnalisé sans que les paramètres facultatifs soient spécifiés, il fonctionnerait 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é en ne fournissant que les paramètres obligatoires et en s'appuyant sur les valeurs par défaut internes du script, les fournisseurs PAM personnalisés remplacent ces valeurs par défaut.

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

Pour contourner ce problème, les valeurs par défaut ne doivent pas être définies dans les paramètres du script. À la place, des conditions dans le script doivent déterminer les valeurs par défaut.

[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 que cela ne soit pas généralement recommandé par les bonnes pratiques PowerShell, fournir des valeurs de paramètres par défaut de cette manière est une exigence pour les fournisseurs PAM personnalisés.

Gestion des sorties

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

Pour s'assurer que les scripts d'action produisent la sortie attendue, il est recommandé qu'ils retournent des informations de quatre façons seulement :

• Utiliser le mot-clé throw pour générer une erreur avec fin d'exécution via le flux d'erreur.
• Utiliser la cmdlet Write-Error pour générer une erreur sans fin d'exécution via le flux d'erreur.
• Utiliser la cmdlet Write-Output pour retourner des informations vers le flux de sortie.
• Envoyer des informations directement vers le flux de sortie.

Vous trouverez ci-dessous des exemples de scripts d'action 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'

Pour s'assurer qu'un script d'action retourne des informations au fournisseur PAM personnalisé, il est conseillé de ne pas utiliser Write-Verbose, Write-Information ou Write-Host.

Découverte de comptes

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

• Paramètres d'entrée requis

  Le script d'action de découverte de comptes est relativement simple, car il nécessite principalement les paramètres de script de point de terminaison communs. Aucun paramètre supplémentaire n'est nécessaire, sauf si le fournisseur d'identité spécifique l'exige.
• Sortie requise

  Chaque script d'action de découverte de comptes 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'identifiant unique pour chaque compte. Bien que cet identifiant soit généralement un nom d'utilisateur, il peut s'agir de tout identifiant 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 représentant le compte.
  • La propriété secret est l'identifiant du mot de passe. Celui-ci peut prendre la forme d'une chaîne chiffrée ou d'un mot de passe en texte clair, qui est ensuite utilisé pour être comparé à d'autres secrets via l'action de heartbeat.

  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. Voici un exemple de la façon d'accomplir cela.

  ## 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 découverte de comptes, les champs Nom d'utilisateur et Identifiant unique sont remplis avec les valeurs des propriétés username et id du script d'action.

Heartbeat

Après la récupération de tous les comptes du fournisseur d'identité par l'action de découverte de comptes, une action de heartbeat est lancée. Celle-ci lit la valeur du mot de passe actuel d'un compte et la compare à la valeur stocké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 de point de terminaison communs, un script d'action de heartbeat doit inclure au moins deux paramètres : username et secret, qui sont respectivement une string et une securestring.
• Sortie requise

  Un script d'action de heartbeat retourne un seul objet booléen ($true ou $false) pour indiquer si la valeur du mot de passe actuel d'un compte correspond à la valeur connue des modules PAM.

Voici un exemple de script d'action de heartbeat.

[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

Rotation des mots de passe

Lorsque les fournisseurs PAM personnalisés exécutent l'action de heartbeat et que le script d'action retourne 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 des mots de passe est déclenchée.

Cette action est responsable de la synchronisation des 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 de terminaison communs, un script d'action de rotation des mots de passe doit inclure un paramètre : NewPassword. Il s'agit d'un paramètre securestring qui permet aux fournisseurs PAM personnalisés de transmettre la nouvelle valeur du mot de passe au script d'action.
• Sortie requise

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

Voici un exemple de base d'un script d'action de rotation des mots 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."
}