Module

Tout sur le module Universal PowerShell.

Connexion à PowerShell Universal

Le module PowerShell Universal nécessite quelques informations pour se connecter au serveur. Il doit d'abord connaître l'URL ou le nom de l'ordinateur, puis il a besoin d'informations d'identification pour accéder aux ressources à distance.

Vous pouvez utiliser la cmdlet Connect-PSUServer pour configurer une connexion au serveur. L'appel de cette cmdlet définit les informations de connexion pour l'ensemble du processus. Si vous exécutez dans un processus multi-utilisateur, vous devez tenir compte des implications de l'utilisation de cette commande.

Connect-PSUServer -ComputerName http://localhost:5000 -AppToken xyz123

Lorsque vous exécutez des scripts dans l'environnement intégré ou dans des applications ou des API dans PowerShell Universal, envisagez d'utiliser les valeurs de nom d'ordinateur et d'identifiants directement dans les cmdlets afin d'éviter de les partager dans tout le processus.

Get-PSUJob -ComputerName http://localhost:5000 -AppToken xyz123

Authentification

Jeton d'application

Vous pouvez utiliser le paramètre -AppToken pour vous authentifier auprès de l'API avec le jeton spécifié. Traitez le jeton d'application comme un mot de passe, car il accorde l'accès en fonction des rôles qui lui sont attribués.

Identifiants par défaut

Vous pouvez également utiliser les identifiants par défaut, ou les identifiants Windows. Ce mécanisme n'est pris en charge que si le serveur cible a l'authentification Windows activée. Les rôles et les autorisations seront accordés lors de la connexion au serveur.

Identifiants

Si l'authentification par formulaire est activée, vous pouvez utiliser l'authentification de base en spécifiant un objet PSCredential au paramètre -Credential de Connect-PSUServer.

Portée

Connect-PSUServer prend en charge un paramètre de portée pour définir la façon dont les informations de connexion sont conservées. Par défaut, la portée est Process. La portée de processus stocke les informations de connexion dans une portée .NET statique. Toutes les cmdlets exécutées dans le processus actuel utiliseront ces informations de connexion.

Si vous utilisez Connect-PSUServer dans un environnement multi-runspace, comme l'environnement intégré ou dans des applications dans PowerShell Universal, vous souhaiterez peut-être stocker uniquement les informations de connexion pour le runspace actuel. Utilisez la valeur de paramètre -Scope Runspace pour ajuster la façon dont les informations de connexion sont stockées.

Déconnexion

Vous pouvez vous déconnecter du serveur PowerShell Universal en utilisant la cmdlet Disconnect-PSUServer. Si vous avez utilisé la portée Runspace, elle effacera les variables nécessaires, et si vous avez utilisé la portée Process, elle effacera les propriétés statiques nécessaires.

Connexions internes

Lors de l'utilisation du module Universal dans PowerShell Universal, il n'est pas nécessaire de spécifier des identifiants ni le nom de l'ordinateur dans les installations de base. L'autorisation correspondra à l'utilisateur actuel et l'URL de l'API sera déduite du serveur actuel.

Autorisation

Lors de l'utilisation du modèle de sécurité Strict, l'autorisation est basée sur l'appelant. Par exemple, si un utilisateur appelle un point de terminaison API et que ce point de terminaison appelle Invoke-PSUScript, l'appel est effectué au nom de l'appelant du point de terminaison. Les autorisations de l'appelant sont appliquées à l'exécution du script.

Lors de l'utilisation d'autres modèles de sécurité, les cmdlets sont appelées au nom de l'utilisateur System et l'autorisation n'est pas appliquée en fonction de l'appelant de la ressource.

Modèle de sécurité d'autorisation

Vous pouvez modifier le modèle d'autorisation pour permettre à tous les appels provenant de PowerShell Universal de fonctionner sans jeton d'application. Bien que cela puisse être considéré comme moins sécurisé par certains, cela dépend de l'utilisation de la plateforme par votre organisation. Cette valeur peut être définie dans appsettings.json ou dans la variable d'environnement API__SecurityModel.

Un contexte utilisateur est requis pour l'authentification. Cela signifie que lors de l'utilisation du module dans des contextes sans utilisateur, comme les planifications, vous devrez fournir un jeton d'application.

Dans les portées qui ont un contexte utilisateur, comme une application, les appels aux cmdlets sont effectués sous les privilèges de cet utilisateur. Par exemple, si un utilisateur accédant à une application n'a pas accès pour appeler Get-PSUScript, la cmdlet ne sera pas utilisable sans un jeton d'application disposant de ces privilèges.

{
    "Api": {
       "SecurityModel": "Strict"
    }
}

Le mode Permissive utilise toujours les API PowerShell Universal externes et communique le contexte utilisateur, si disponible, lors de l'appel des API PowerShell Universal. Le mode Permissive permet l'utilisation du commutateur -Integrated pour contourner l'autorisation et utiliser la connexion TCP en canal arrière plutôt que l'API externe de PowerShell Universal.

{
    "Api": {
       "SecurityModel": "Permissive"
    }
}

Vous pouvez également utiliser le modèle de sécurité Integrated pour éviter complètement la nécessité de configurer des jetons d'application, des URL ou des certificats. Le modèle de sécurité Integrated ne communique pas le contexte utilisateur, même lorsque l'utilisateur est authentifié. Il utilise également la connexion TCP en canal arrière plutôt que l'API externe de PowerShell Universal.

{
    "Api": {
       "SecurityModel": "Integrated"
    }
}

Faire confiance au certificat HTTPS

Dans certains environnements, il peut être nécessaire d'autoriser PowerShell Universal à faire confiance au certificat du serveur web pour qu'il puisse communiquer avec succès. À chaque appel, vous pouvez utiliser le paramètre -TrustCertificate pour autoriser ce comportement. De plus, vous pouvez définir la valeur au niveau du serveur pour permettre les communications internes.

{
    "Api": {
       "TrustCertificate": true
    }
}

Mode intégré

Le mode intégré utilise la connexion en canal arrière interne de PowerShell Universal pour communiquer avec les services via le module Universal. Lors de l'utilisation du mode intégré, l'autorisation n'est effectuée que lorsque l'API est en mode de sécurité Strict.

Vous pouvez appeler des cmdlets en mode intégré en utilisant le paramètre de commutateur -Integrated.

Le modèle de sécurité du serveur peut également être défini sur Integrated. Cela force tous les appels de cmdlets à utiliser le mode intégré et ne nécessite plus l'utilisation du paramètre -Integrated.

Planifications

Les planifications n'ont pas d'utilisateur actuel. Vous devrez spécifier un jeton d'application ou des identifiants par défaut lors de l'utilisation de cmdlets dans des scripts planifiés. Bien que cela représente une étape supplémentaire, cela garantit que seules les autorisations nécessaires sont appliquées au script de planification.

Les planifications n'ont pas de contexte utilisateur, vous devrez donc en spécifier un pour qu'elles s'exécutent correctement lors de l'utilisation de ces cmdlets.

Proxies inverses (IIS)

PowerShell Universal utilise toutes les données disponibles pour déterminer l'URL appropriée à appeler lors de l'utilisation de l'API. Cela peut être problématique lors de l'utilisation d'un proxy inverse, comme IIS. L'URL que PowerShell Universal voit est différente de l'URL réelle et accessible. Cela peut causer des problèmes lorsque les cmdlets tentent d'accéder à l'API.

Pour contourner ce problème, vous pouvez soit spécifier l'URL appropriée pour chaque appel de cmdlet, soit personnaliser l'URL de l'API dans les paramètres de l'application.

Spécifier l'URL

Pour spécifier l'URL, fournissez-la simplement au paramètre -ComputerName.

Get-PSUJob -ComputerName 'https://external.company.com/psu'

Paramètres de l'application

Vous pouvez également définir la valeur de l'URL de l'API dans les paramètres de l'application pour fournir la même valeur sur toute la plateforme. Définissez la valeur dans une variable d'environnement ou dans le fichier appsettings.json.

{
  "API": {
    "URL": "https://external.company.com/psu"
  }
}

Considérations techniques

Le module Universal utilise gRPC pour toutes les communications avec le serveur PowerShell Universal. Selon la configuration du serveur, la communication gRPC sera légèrement différente.

HTTPS

Lors de l'utilisation de HTTPS, le canal de communication gRPC standard sera utilisé. Il s'agit de la configuration la plus rapide car elle ne nécessite pas de sérialisation spéciale ni d'accommodations pour les protocoles de niveau inférieur. HTTP/2 est requis pour gRPC.

Si HTTPS est utilisé, le certificat doit être approuvé par le système. Si le certificat est auto-signé, vous pouvez utiliser le paramètre -TrustCertificate sur les cmdlets pour éviter la vérification du certificat.

HTTP et authentification Windows

Lors de l'utilisation de HTTP ou de l'authentification Windows, HTTP/2 n'est pas pris en charge et gRPC ne peut pas s'exécuter nativement car les en-têtes de fin ne sont pas pris en charge. Pour y remédier, le module Universal utilisera une technologie appelée gRPC-Web pour traduire les appels gRPC en HTTP et JSON afin d'appeler les méthodes REST HTTP plutôt que les méthodes gRPC standard.

Cette configuration est légèrement plus lente, mais ne devrait pas être perceptible dans la plupart des environnements.

Mode intégré

Le mode intégré n'utilise pas l'API externe et communique via le canal arrière gRPC de PowerShell Universal. Il n'est pas nécessaire de configurer des URL d'API, des certificats ou des identifiants.