Variables

Les variables peuvent être utilisées dans les API, les scripts et les tableaux de bord. Lorsque vous utilisez les environnements par défaut, toutes les variables sont importées automatiquement. Cela est réalisé en spécifiant le paramètre -Variable de New-PSUEnvironment avec un caractère générique (*). Si vous utilisez vos propres environnements, vous devrez configurer quelles variables vous souhaitez inclure. Vous pouvez référencer une variable comme n'importe quelle autre variable PowerShell. La variable contiendra la valeur que vous avez définie. Si vous utilisez un secret, elle contiendra la valeur du secret.

Les variables sont stockées dans le fichier de configuration variables.ps1.

Créer une variable

Pour créer une variable, naviguez vers la page Manage > Variables & Secrets > Variables. Cliquez sur Create Variable pour définir une nouvelle variable.

Les variables seront ajoutées à vos scripts avant leur exécution.

Créer une variable secrète

Les variables secrètes sont stockées dans le coffre sélectionné. La valeur de ces variables n'est jamais stockée dans Universal. Pour définir une nouvelle variable secrète, cliquez sur Create Secret Variable dans la page des variables et sélectionnez l'onglet Secret.

À partir de ce dialogue, vous pourrez définir des chaînes et des PSCredentials dans le coffre spécifié.

Format des identifiants

Dans certains environnements, il peut être nécessaire de spécifier le nom de domaine dans le champ du nom d'utilisateur. Vous pouvez le spécifier au format domain\user ou user@domain. Si vous ne le faites pas, vous recevrez des erreurs en tentant de démarrer des processus, comme des scripts ou des tableaux de bord, avec ce compte d'utilisateur.

Comptes de service géré de groupe

Lorsque vous utilisez des comptes de service géré de groupe (GMSA), vous devrez vous assurer que la machine et le compte ont accès au compte GSMA. Vous pouvez suivre le guide de Microsoft ici. Une fois la configuration terminée, créez un nouvel identifiant dans la gestion des secrets de PowerShell Universal et sélectionnez l'option Password Not Required. Saisissez le compte GSMA (p. ex. domain\user$). Tant que le compte hébergeant possède les privilèges appropriés, vous pourrez exécuter des tâches avec le compte GMSA.

Validation des identifiants

Sur Windows, vous pouvez valider les identifiants avant d'enregistrer leur valeur. Cliquez sur le bouton Validate dans le champ du mot de passe pour tenter de connecter l'utilisateur localement. Ce bouton n'apparaîtra pas sur les systèmes non Windows.

Rôles

Appliquer des rôles à un secret empêchera le secret d'être accessible dans les tâches planifiées, car aucun rôle n'est appliqué dans le planificateur.

Les variables secrètes peuvent inclure un accès basé sur les rôles. Les rôles limitent qui peut utiliser le secret dans ses scripts et comme identifiants d'exécution.

Lorsqu'un rôle est défini pour un secret, celui-ci ne sera pas accessible dans les ressources qui ne peuvent pas fournir ce rôle. Cela peut inclure ce qui suit :

• Tâches planifiées
• API ou applis non authentifiées
• Terminaux

Coffres

Base de données

Le coffre de base de données stocke les secrets dans la base de données de PowerShell Universal. Ces secrets sont chiffrés avec le chiffrement AES à l'aide d'une clé personnalisable. Vous pouvez personnaliser la clé en spécifiant Secrets \ Database \ EncryptionKey.

appsettings.json

Vous pouvez configurer ce paramètre dans appsettings.json.

"Secrets": {
  "Database": {
    "EncryptionKey": "=b0ywQA@VOSdr&R7an5g&XK6NVO%s4Tf"
  }
}

Variable d'environnement

Vous pouvez configurer ce paramètre avec une variable d'environnement.

$Env:Secrets__Database__EncryptionKey = "=b0ywQA@VOSdr&R7an5g&XK6NVO%s4Tf"

BuiltInLocalVault

Si PowerShell Universal est exécuté en tant que compte de service géré de groupe, il ne peut pas utiliser le BuiltInLocalVault.

Les valeurs des secrets du BuiltInLocalVault sont stockées dans l'instance du Gestionnaire d'identifiants Windows du principal de sécurité qui exécute PSU. Par exemple, le compte de service de l'utilisateur exécutant le service Universal. Si vous changez d'utilisateur (comme en exécutant sous un compte de service), le compte n'aura pas accès aux secrets de l'utilisateur précédent et vous devrez ajouter ces secrets à nouveau.

PSUSecretStore

Si PowerShell Universal est exécuté en tant que compte de service géré de groupe, il ne peut pas utiliser le PSUSecretStore.

Le coffre PSUSecretStore est intégré au module Microsoft SecretStore pour stocker les secrets dans un fichier multiplateforme. Ce fichier est lié au compte d'utilisateur actuel exécutant PowerShell Universal. Le mot de passe du coffre est stocké dans appsettings.json.

Az.KeyVault

Utilisez l'enregistrement de coffre Azure Key Vault pour configurer Azure Key Vault pour PowerShell Universal.

Par défaut, nous n'incluons pas l'extension Azure Key Vault directement dans PowerShell Universal. Un conteneur incluant les modules Az.Accounts et Az.KeyVault requis est disponible pour vous permettre d'utiliser KeyVault dès le départ. Il se trouve sur Docker Hub.

Vous trouverez ci-dessous comment le configurer. Cet exemple utilise une version de PowerShell Universal en application web hébergée sur Azure.

Dans Azure, nous devrons configurer une identité gérée pour notre application web. Cette étape n'est pas nécessairement requise si vous exécutez à l'extérieur d'Azure. Vous pouvez activer l'identité gérée dans la page Identity de votre application web.

Enfin, nous devrons enregistrer le key vault et nous connecter à Azure au démarrage de l'application web. Cela peut être réalisé en utilisant les modules Az.Account et Az.KeyVault.

Après avoir déployé votre application web, vous devrez d'abord installer les modules Az.Account et Az.KeyVault. Vous pouvez le faire dans la page des modules. Ils seront installés dans le dépôt local de l'application web.

Ensuite, créez un script dans PowerShell Universal pour vous connecter à Azure et enregistrer le coffre. Exécutez le script pour vérifier qu'il fonctionne correctement.

$sub = 'affdf0d4-eed5-48a6-889c-599d482xxxxx'
Connect-AzAccount -Id -Scope CurrentUser -SubscriptionId $sub

Register-SecretVault -ModuleName Az.KeyVault -Name AzureKeyVault -VaultParameters @{ 
    AZKVaultName = 'psu-demo'
    SubscriptionId = $sub
} -AllowClobber

Maintenant, lorsque vous créerez des secrets, vous verrez AzureKeyVault disponible.

Pour vous assurer que l'application est connectée à Azure et que le key vault est enregistré, exécutez le script dans vaults.ps1. Nous recommandons d'exécuter le script dans un processus PowerShell externe afin d'éviter les conflits d'assemblages avec les DLL de PowerShell Universal.

$pwsh = (Get-Command pwsh).Path
& $pwsh -File "$PSScriptRoot\registerVault.ps1"

Ce script s'exécute avant que les variables soient enregistrées et que les coffres soient localisés. Vous pouvez créer ce fichier directement dans le répertoire Repository.universal. Il sera exécuté au démarrage du système avant que les autres scripts de configuration soient exécutés.

vaults.ps1

Le fichier vaults.ps1 contient les commandes d'enregistrement de coffres. Bien que l'exemple ci-dessus définisse un enregistrement de coffre de secrets Azure KeyVault, vous pouvez en fait inclure tout enregistrement de coffre dont vous avez besoin dans ce fichier.

Vous pouvez modifier les coffres en cliquant sur Manage > Variables & Secrets > Vaults, puis en naviguant vers l'onglet vaults.ps1.

Importer des variables secrètes

Vous pouvez également importer des secrets préexistants comme variables dans Universal. Les valeurs des variables ne sont pas importées, mais elles seront recherchées lors de l'exécution. Cliquez sur le bouton Import Secret pour importer des secrets.

Utiliser des variables

Les variables peuvent être utilisées dans les API, les scripts et les tableaux de bord. Lorsque vous utilisez les environnements par défaut, toutes les variables sont importées automatiquement. Cela est réalisé en spécifiant le paramètre -Variable de New-PSUEnvironment avec un caractère générique (*). Si vous utilisez vos propres environnements, vous devrez configurer quelles variables vous souhaitez inclure. Vous pouvez référencer une variable comme n'importe quelle autre variable PowerShell. La variable contiendra la valeur que vous avez définie. Si vous utilisez un secret, elle contiendra la valeur du secret.

$MyVariable

Vous pouvez personnaliser quelles variables sont autorisées dans un environnement en personnalisant le paramètre -Variable de l'environnement.

Consultez Environnements pour plus d'information.

Portée des secrets

Pour accéder aux secrets que vous avez ajoutés à PowerShell Universal, vous pouvez utiliser la portée $Secret. Par exemple, si vous avez défini un secret nommé Credential, vous pourriez accéder à ce secret n'importe où avec la portée des secrets. Vous ne pouvez pas définir de secrets en utilisant la portée des secrets.

Invoke-Command -Credential $Secret:Credential { Write-Host "Hello" }

Accéder aux variables par nom

Vous pouvez accéder aux variables par nom en utilisant le préfixe $Secret:.

# PSCredential
$Secret:MyNewSecret.UserName
$Secret:MyNewSecret.Password

# String
$Secret:DashboardSecret

Accéder aux valeurs dynamiquement

Vous pouvez accéder à la portée des secrets dynamiquement en utilisant Get-Item. La portée des secrets est implémentée comme un fournisseur. Cela est utile si vous n'avez pas de noms de variables statiques.

# PSCredential
(Get-ChildItem "Secret:MyNewSecret").UserName
(Get-ChildItem "Secret:MyNewSecret").Password

# String
(Get-ChildItem "Secret:DashboardSecret")

ForEach-Object -Parallel

Afin d'utiliser des secrets avec ForEach-Object et le paramètre -Parallel, vous devrez tirer parti du mot-clé $using.

1..5 | ForEach-Object -Parallel {
  $using:Secret:MySecret
}

Configurer le mot de passe de PSUSecretStore

Par défaut, le mot de passe du coffre PSUSecretStore est stocké dans appsettings.json sous Secrets \ SecretStore \ Password.

Variables intégrées

Les variables suivantes sont disponibles dans tous les environnements de PowerShell Universal.

Cette référence énumère les variables de PowerShell Universal destinées à être utilisées dans votre code. Get-Variable retourne également les variables automatiques standards de PowerShell et les variables d'implémentation internes, de sorte que sa sortie ne correspondra pas exactement à ces tableaux.

Nom	Type	Description
$PSUEnvironment	string	Le nom de l'environnement dans lequel le script s'exécute (p. ex. Integrated)
$Repository	string	Le chemin absolu vers le dossier du dépôt.

API

Il existe un ensemble de variables prédéfinies disponibles dans les terminaux d'API. Vous pourrez utiliser ces variables dans vos scripts.

Variable	Description	Type
$Url	L'URL que le client a utilisée pour appeler le terminal	String
$Method	La méthode HTTP utilisée pour appeler le terminal	String
$Headers	Les en-têtes fournis par le client pour appeler le terminal	Hashtable
$Body	La chaîne encodée en UTF8 du contenu de la requête	String
$Data	Tableau d'octets binaire du contenu de la requête	Byte[]
$RemoteIpAddress	L'adresse IP distante du client effectuant la requête	String
$LocalIpAddress	L'adresse IP distante du service traitant la requête	String
$RemotePort	Le port distant qui a été appelé pour effectuer la requête	Integer
$LocalPort	Le port local qui a été utilisé pour traiter la requête	Integer
$Identity	Le nom de l'identité du principal accédant à l'API.	String
$UrlDefinition	La définition de l'URL.	String
$ConnectionId	L'ID de connexion du contexte HTTP.	String
$SessionId	L'ID de session du contexte HTTP.	String
$RequestId	L'ID de requête du contexte HTTP	String
$ClaimsPrincipal	Le claims principal de l'utilisateur actuel. Il s'agit du même objet que celui fourni aux stratégies d'accès basées sur les rôles.	ClaimPrincipal

Applis

Voici les variables disponibles dans les applis en plus des variables globales.

Nom	Description	Type
$User	Le nom d'utilisateur de l'utilisateur connecté. $Null si l'authentification est désactivée.	String
$Roles	Les rôles accordés à l'utilisateur. $Null si l'authentification est désactivée.	String[]
$RemoteIpAddress	L'adresse IP distante de l'utilisateur connecté.	String
$RemotePort	Le port distant de l'utilisateur connecté.	Int
$ClaimsPrincipal	Le claims principal de l'utilisateur actuel. Il s'agit du même objet que celui fourni aux stratégies d'accès basées sur les rôles.	ClaimPrincipal
$Headers	Les en-têtes fournis par le navigateur.	hashtable
$Cookies	Les témoins de requête fournis par le navigateur.	hashtable
$PSUAppToken	Le jeton d'appli de l'utilisateur actuel. Disponible uniquement lorsque -GrantAppToken est activé.	string
$PSUURL	L'URL du serveur PSU. Disponible uniquement lorsque -GrantAppToken est activé.	string
$DashboardName	Le nom de l'appli actuelle	string
$Query	Les paramètres de la chaîne de requête provenant de l'URL de l'appli	Hashtable
$RefreshToken	Le jeton d'actualisation lors de l'utilisation d'OpenID Connect	string
$AccessToken	Le jeton d'appli lors de l'utilisation d'OpenID Connect	string
$UDPage	Le nom de la page actuelle	string

Scripts

Il existe plusieurs variables intégrées qui sont définies lorsqu'une tâche est exécutée. Vous pouvez utiliser ces variables dans vos scripts pour récupérer des informations sur la tâche actuelle.

Nom	Description
$UAJob	La tâche en cours d'exécution. Cela comprendra des propriétés telles que le script, l'utilisateur qui a démarré la tâche et le moment où la tâche a été démarrée.
$UAJobId	L'identifiant de la tâche en cours d'exécution.
$UAScript	Le script en cours d'exécution. Cela comprendra des propriétés telles que le nom du script et le chemin d'accès au script.
$UAScriptId	L'identifiant du script en cours d'exécution.
$UASchedule	La planification qui a été utilisée pour démarrer le script.
$UAScheduleId	L'identifiant de la planification qui a démarré le script.
$AccessToken	Lors de l'utilisation de l'authentification OIDC, vous pouvez récupérer le jeton d'accès de l'utilisateur actuel afin d'accéder à des ressources en son nom.
$Roles	Les rôles de l'appelant du script.

Structure de l'objet $UAJob

Notez que les propriétés peuvent être nulles. Les objets DateTime sont retournés dans le fuseau horaire UTC.

class Job {
    public long Id { get; set; }
    public DateTime CreatedTime { get; set; }
    public DateTime StartTime { get; set; }
    public DateTime EndTime { get; set; }
    public JobStatus Status { get; set; }
    public string Output { get; set; }
    public string ScriptFullPath { get; set; }
    public Identity Identity { get; set; }
    public Job ParentJob { get; set; }
    public int ParentLineNumber { get; set; }
    public string ComputerName { get; set; }
    public int ProcessId { get; set; }
    public long MemoryBytes { get; set; }
    public int RunspaceId { get; set; }
    public string Activity { get; set; }
    public string CurrentOperation { get; set; }
    public int PercentComplete { get; set; }
    public int SecondsRemaining { get; set; }
    public string StatusDescription { get; set; }
    public string Environment { get; set; }
    public Computer Computer { get; set; }
    public ActionPreference ErrorAction { get; set; }
    public IEnumerable<Job> Children { get; set; }
    public IEnumerable<JobParameter> Parameters { get; set; }
    public string Credential { get; set; }
    public long ScheduleId { get; set; }
    public bool Triggered { get; set; }
    public string Trigger { get; set; }
    public int RetryCount { get; set; }
    public string Tags { get; set; }
    public string Schedule { get; set; }
    public bool Archived { get; set; }
    public bool Batch { get; set; }
    public Guid? RunId { get; set; }
    public string Roles { get; set; }
}

public enum JobStatus
{
    Queued,
    Running,
    Completed,
    Failed,
    WaitingOnFeedback,
    Canceled,
    Canceling,
    Historical,
    Active,
    TimedOut,
    Warning,
    Error
}

Récupérer l'utilisateur qui a démarré un script

Vous pouvez récupérer le nom de l'utilisateur qui a démarré un script en utilisant la variable UAJob

$UAJob.Identity.Name

Vérifier si une tâche a été exécutée manuellement

Vous pouvez vérifier si une tâche a été exécutée manuellement en utilisant les propriétés Schedule et Trigger.

$Manual = $UAJob.Schedule -eq $null -and $UAJob.Trigger -eq $null

Variables de préférence

Les variables de préférence peuvent être configurées sur un script, pendant l'exécution d'une tâche et au niveau global. Elles comprennent :

• DebugPreference
• ErrorActionPreference
• InformationPreference
• ProgressPreference
• VerbosePreference
• WarningPreference

Les variables de préférence ont une préséance. La liste suivante est classée par ordre de préséance. Par exemple, si un script définit manuellement la variable $DebugPreference, celle-ci remplacera la valeur définie dans la boîte de dialogue des propriétés du script.

• Script
• Boîte de dialogue d'exécution ou Invoke-PSUScript
• Propriétés du script
• Paramètres globaux

API

• New-PSUVariable
• Get-PSUVariable
• Remove-PSUVariable
• Set-PSUVariable

Voir aussi

• Devolutions Academy – Ajout de la fonctionnalité de déverrouillage d'utilisateur