Créer un script d'action AnyIdentity dans Devolutions Server

Lorsqu'un fournisseur personnalisé AnyIdentity est requis, il est nécessaire de d'abord développer les scripts d'action qui seront exécutés par les actions du fournisseur. Ces scripts d'action seront 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 par conséquent, les mêmes meilleures pratiques applicables à tout script PowerShell doivent être respectées. Cependant, il y a des nuances spécifiques à prendre en compte lors de la création de ces 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 à travers lesquels le fournisseur AnyIdentity transmettra des valeurs. Bien que les paramètres spécifiques pour chaque script d'action puissent varier (comme indiqué dans les exemples ci-dessous), ils partageront tous un ensemble commun de paramètres requis pour se connecter au point d'accès du fournisseur d'identité. Les scripts d'action se connectent à un fournisseur d'identité, et pour faciliter cela, ils doivent recevoir les identifiants nécessaires du fournisseur AnyIdentity.

Ci-dessous se trouve un exemple de comment définir ces paramètres de point de terminaison du fournisseur d'identité.

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

Chaque paramètre est marqué comme obligatoire, garantissant que le fournisseur AnyIdentity est contraint d'utiliser ces paramètres. Il est aussi important de noter l'utilisation du type securestring pour le paramètre IdentityEndpointPassword. AnyIdentity impose l'utilisation de securestring pour empêcher la transmission et le traitement de mots de passe en texte clair dans les scripts d'action.

Lors de la construction du modèle AnyIdentity, ces paramètres de point d'accès du fournisseur d'identité correspondraient aux paramètres définis lors du processus de création du modèle.

Gérer les paramètres facultatifs et par défaut

Quand vous devez offrir la possibilité de transmettre une valeur à un paramètre de script sans l'exiger, ce paramètre est considéré comme optionnel. Il n'est utilisé que lorsqu'une valeur lui est transmise.

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

Les paramètres du script d'action pour le fournisseur mentionné ci-dessus peuvent être structurés comme suit, chaque paramètre de script correspondant aux propriétés du modèle AnyIdentity 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 de AnyIdentity sans que les paramètres facultatifs soient spécifiés, il fonctionnerait comme prévu, utilisant les valeurs par défaut des paramètres.

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

Cependant, lors de la construction du modèle AnyIdentity et en fournissant uniquement les paramètres obligatoires, en s'appuyant sur les valeurs par défaut internes du script, AnyIdentity remplacera ces valeurs par défaut.

Lorsque AnyIdentity exécute un script d'action, il transmet invariablement des valeurs à tous les paramètres. Dans les cas où aucune valeur n'est définie, AnyIdentity transmettra une valeur null, ou si le paramètre est de type entier, une valeur 0.

Pour contourner cela, il ne faut pas définir de valeurs par défaut dans les paramètres du script. Au lieu de cela, les 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 qu'il ne soit généralement pas recommandé par les meilleures pratiques PowerShell, fournir des valeurs par défaut pour les paramètres de cette manière est une exigence pour AnyIdentity.

Gérer la sortie

Les scripts d'action sont finalement exécutés dans l'environnement AnyIdentity. Toute sortie générée par ces scripts 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 renvoient la sortie de seulement quatre manières :

• Utiliser le mot-clé throw pour générer une erreur d'arrêt en utilisant le flux d'erreur.
• Utiliser l'applet de commande Write-Error pour générer une erreur non bloquante en utilisant le flux d'erreurs.
• Utiliser l'applet de commande Write-Output pour retourner des informations au flux de sortie.
• Envoyer directement des informations au flux de sortie.

Ci-dessous se trouvent des exemples de scripts d'action et les résultats correspondants dans la fonctionnalité Tester le script de la zone Résultats d'AnyIdentity.

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'

Détection de compte

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

• Paramètres d'entrée requis

  Le script d'action pour l'action de détection de compte est relativement simple, car il nécessite principalement des paramètres de script communs au point d'accès. Aucun paramètre supplémentaire n'est nécessaire sauf si cela est dicté par le fournisseur d'identité spécifique.

• Sortie requise

  Le script de détection de compte doit retourner un type de sortie spécifique. 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. Bien que cet identificateur soit généralement un nom d'utilisateur, il peut être 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 identificateur qui représente le compte.
  • La propriété secret est l'identifiant du mot de passe. Il peut s'agir d'une chaîne chiffrée ou d'un mot de passe en clair et sera utilisé pour comparer 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 pour 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 AnyIdentity et de son test (instructions fournies ci-dessous) avec une configuration de scan, les champs Nom d'utilisateur et Identifiant unique seront remplis avec les valeurs de propriété pour les propriétés username et id du script d'action.

Moniteur d'activité

Suite à la détection de compte effectuée par l'action d'injection des identifiants auprès du fournisseur d'identité, l'action de moniteur d'activité est initiée. L'action de moniteur d'activité lit la valeur actuelle du mot de passe d'un compte et la compare à la valeur stockée par la gestion de l'accès privilégié. Si les deux valeurs diffèrent, un changement est détecté.

• Paramètres d'entrée requis

  En plus des paramètres communs du point de terminaison, un script d'action de pulsation doit inclure au moins deux paramètres : username et secret.

  • La valeur de la propriété username retournée par le script d'action de détection de compte. Ce paramètre est de type string.
  • La valeur de la propriété secret retournée par le script d'action de détection de compte. Ce paramètre est de type securestring.

• Sortie requise

  Un script d'action de pulsation renvoie 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 des modules PAM.

Ci-dessous un exemple d'un script d'action de balisage.

[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 AnyIdentity exécute l'action de moniteur d'activité et que le script d'action retourne une valeur $false, indiquant que le nouveau mot de passe dans AnyIdentity diffère du mot de passe sur le fournisseur d'identité, l'action de rotation du mot de passe est déclenchée.

L'action de rotation de mot de passe 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 communs du point de terminaison, un script d'action de rotation de mot de passe doit inclure un paramètre : NewPassword. C'est un paramètre securestring qui permet à AnyIdentity de transmettre la nouvelle valeur du mot de passe au script d'action.

• Sortie requise

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

Ci-dessous, 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."
}