Variables
Informations sur les variables PowerShell Universal.
Les variables permettent de définir globalement des variables disponibles dans les scripts. Vous pouvez également importer des secrets qui sont aussi disponibles dans les scripts ou en tant que références d'exécution.
Les variables sont stockées dans le fichier de configuration variables.ps1.
Création d'une variable
Pour créer une variable, accédez à la page Platform \ Variables. Cliquez sur Create Variable pour définir une nouvelle variable.
Les variables seront ajoutées à vos scripts avant leur exécution.
Création d'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 sur la page des variables et sélectionnez l'onglet Secret.
Dans cette boîte de dialogue, vous pourrez définir des chaînes et des PSCredentials dans le coffre spécifié.
Format des informations d'identification
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 lors de la tentative de démarrage de processus, tels que des scripts ou des tableaux de bord, sous ce compte utilisateur.
Comptes de service gérés de groupe
Lorsque vous utilisez des comptes de service gérés de groupe (GMSA), vous devez vous assurer que la machine et le compte ont accès au compte GMSA. Vous pouvez suivre le guide Microsoft ici. Une fois la configuration terminée, créez de nouvelles informations d'identification dans la gestion des secrets PowerShell Universal et sélectionnez l'option Password Not Required. Saisissez le compte GMSA (p. ex. domain\user$). Tant que le compte d'hébergement dispose des privilèges appropriés, vous pourrez exécuter des tâches sous le compte GMSA.
Validation des informations d'identification
Sous Windows, vous pouvez valider les informations d'identification avant d'enregistrer leur valeur. Cliquez sur le bouton Validate dans le champ du mot de passe pour tenter une connexion locale de l'utilisateur. Ce bouton n'apparaîtra pas sur les systèmes autres que Windows.
Rôles
L'application de rôles à un secret empêchera celui-ci 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 contrôle d'accès basé sur les rôles. Les rôles limitent les personnes pouvant utiliser le secret dans leurs scripts et en tant que références d'exécution.
Lorsqu'un secret a un rôle défini, il ne sera pas accessible dans les ressources qui ne peuvent pas fournir ce rôle. Cela peut inclure les éléments suivants :
Tâches planifiées
API ou applications 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 PowerShell Universal. Ces secrets sont chiffrés à l'aide du chiffrement AES avec 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.
Variable d'environnement
Vous pouvez configurer ce paramètre à l'aide d'une variable d'environnement.
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 avec le BuiltInLocalVault sont stockées dans l'instance du gestionnaire d'informations d'identification 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 (par exemple en exécutant le service sous un compte de service), le nouveau compte n'aura pas accès aux secrets de l'utilisateur précédent et vous devrez ajouter de nouveau ces secrets.
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 utilisateur actuel exécutant PowerShell Universal. Le mot de passe du coffre est stocké dans appsettings.json.
Az.KeyVault
Par défaut, nous n'incluons pas l'extension Azure Key Vault directement dans PowerShell Universal. À partir de PowerShell Universal v4.0.11, un conteneur incluant les modules Az.Accounts et Az.KeyVault requis est disponible pour vous permettre d'utiliser KeyVault immédiatement. Celui-ci est disponible sur Docker Hub.
Vous trouverez ci-dessous comment le configurer. Cet exemple utilise une version d'application web hébergée sur Azure de PowerShell Universal.
Dans Azure, vous devrez configurer une identité gérée pour votre application web. Cette étape n'est pas nécessairement requise si vous exécutez en dehors d'Azure. Vous pouvez activer l'identité gérée sous la page Identity de votre application web.
Ensuite, vous devrez autoriser votre identité gérée à accéder à votre coffre de clés et à lire votre abonnement. Vous pouvez ajouter l'identité gérée au groupe Reader intégré pour autoriser l'accès à l'abonnement.
Puis, tous les privilèges de gestion des secrets et des clés ont été accordés à l'identité gérée dans la ressource Key Vault.
Enfin, vous devrez enregistrer le coffre de clés et vous connecter à Azure au démarrage de l'application web. Cela peut être accompli à l'aide des 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 sur la page des modules. Ils seront installés dans le référentiel 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.
Désormais, lors de la création de secrets, vous verrez AzureKeyVault disponible.
Pour s'assurer que l'application est connectée à Azure et que le coffre de clés est enregistré, exécutez le script dans vaults.ps1. Nous recommandons d'exécuter le script dans un processus PowerShell externe pour éviter les conflits d'assembly avec les DLL de PowerShell Universal.
Ce script s'exécute avant l'enregistrement des variables et la localisation des coffres. Vous pouvez créer ce fichier directement dans le répertoire Repository\.universal. Il sera exécuté au démarrage du système avant les autres scripts de configuration.
vaults.ps1
Le fichier vaults.ps1 contient les commandes d'enregistrement des coffres. Bien que l'exemple ci-dessus définisse un enregistrement de coffre de secrets Azure KeyVault, vous pouvez en réalité inclure tout enregistrement de coffre dont vous avez besoin dans ce fichier.
Vous pouvez modifier les coffres en cliquant sur Platform \ Variables \ Vaults, puis accéder à l'onglet vaults.ps1.
Importation de variables secrètes
Vous pouvez également importer des secrets préexistants en tant que variables dans Universal. Les valeurs des variables ne sont pas importées, mais seront recherchées lors de l'exécution. Cliquez sur le bouton Import Secret pour importer des secrets.
Utilisation des variables
Les variables peuvent être utilisées dans les API, les scripts et les tableaux de bord. Lors de l'utilisation des environnements par défaut, toutes les variables sont automatiquement importées. Cela est accompli 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 les variables que 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.
Vous pouvez personnaliser les variables autorisées dans un environnement en personnalisant le paramètre -Variable des environnements.
Consultez Environnements pour plus d'informations.
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 pouvez accéder à ce secret partout avec la portée des secrets. Vous ne pouvez pas définir des secrets à l'aide de la portée des secrets.
Accès aux variables par nom
Vous pouvez accéder aux variables par nom en utilisant le préfixe $Secret:.
Accès aux valeurs de manière dynamique
Vous pouvez accéder à la portée des secrets de manière dynamique en utilisant Get-Item. La portée des secrets est implémentée en tant que fournisseur. Cela est utile si vous n'avez pas de noms de variables statiques.
ForEach-Object -Parallel
Pour utiliser des secrets avec ForEach-Object et le paramètre -Parallel, vous devrez tirer parti du mot-clé $using.
Configuration du mot de passe PSUSecretStore
PSUSecretStorePar 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.
$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 référentiel.
API
Il existe un ensemble de variables prédéfinies disponibles dans les points de terminaison API. Vous pourrez utiliser ces variables dans vos scripts.
$Url
URL utilisée par le client pour appeler le point de terminaison
String
$Method
La méthode HTTP utilisée pour appeler le point de terminaison
String
$Headers
En-têtes fournis par le client pour appeler le point de terminaison
Hashtable
$Body
La chaîne encodée en UTF8 du contenu de la requête
String
$Data
Tableau d'octets binaires pour le contenu de la requête
Byte[]
$RemoteIpAddress
L'adresse IP distante utilisée pour effectuer la requête.
String
$LocalIpAddress
L'adresse IP locale utilisée pour traiter la requête.
String
$RemotePort
Le port distant utilisé pour effectuer la requête.
Integer
$LocalPort
Le port local utilisé pour traiter la requête.
Integer
$Identity
Le nom d'identité du principal accédant à l'API.
String
$UrlDefinition
La définition de l'URL.
String
$ClaimsPrincipal
Le principal de revendications 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.
Applications
Vous trouverez ci-dessous les variables disponibles dans les applications, en plus des variables globales.
$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 principal de revendications 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.
$Headers
Les en-têtes fournis par le navigateur.
hashtable
$Cookies
Les cookies de requête fournis par le navigateur.
hashtable
$PSUAppToken
Le jeton d'application de l'utilisateur actuel. Disponible uniquement lorsque -GrantAppToken est activé.
string
$PSUComputerName
L'URL du serveur PSU. Disponible uniquement lorsque -GrantAppToken est activé.
string
$DashboardName
Le nom de l'application actuelle
string
$Query
Les paramètres de chaîne de requête de l'URL de l'application
Hashtable
$RefreshToken
Le jeton d'actualisation lors de l'utilisation de OpenID Connect
string
$AccessToken
Le jeton d'application lors de l'utilisation de OpenID Connect
string
$UDPage
Le nom de la page actuelle.
string
Scripts
Il existe plusieurs variables intégrées définies lors de l'exécution d'une tâche. Vous pouvez utiliser ces variables dans vos scripts pour récupérer des informations sur la tâche en cours.
$UAJob
La tâche en cours d'exécution. Elle inclura des propriétés telles que le script, l'utilisateur ayant démarré la tâche et la date de démarrage.
$UAJobId
L'identifiant de la tâche en cours d'exécution.
$UAScript
Le script en cours d'exécution. Il inclura des propriétés telles que le nom du script et le chemin vers le script.
$UAScriptId
L'identifiant du script en cours d'exécution.
$UASchedule
La planification utilisée pour démarrer le script.
$UAScheduleId
L'identifiant de la planification ayant 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 pour 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.
Récupération de l'utilisateur ayant démarré un script
Vous pouvez récupérer le nom de l'utilisateur ayant démarré le script en utilisant la variable UAJob.
Vérification 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.
Variables de préférence
Les variables de préférence peuvent être configurées sur un script, lors de l'exécution d'une tâche et au niveau global. Celles-ci incluent :
DebugPreference
ErrorActionPreference
InformationPreference
ProgressPreference
VerbosePreference
WarningPreference
Les variables de préférence ont une priorité. La liste suivante est ordonnée par priorité. Par exemple, si un script définit manuellement la variable $DebugPreference, elle remplacera la valeur définie dans la boîte de dialogue des propriétés du script.
Script
Run Dialog ou Invoke-PSUScript
Propriétés du script
Paramètres globaux
API
Mis à jour
Ce contenu vous a-t-il été utile ?