Modul

Verbindung zu PowerShell Universal herstellen

Das PowerShell Universal-Modul benötigt einige Informationen, um sich mit dem Server zu verbinden. Zunächst muss es die URL oder den Computernamen kennen, und zweitens benötigt es Anmeldeinformationen, um remote auf die Ressourcen zugreifen zu können.

Sie können das Cmdlet Connect-PSUServer verwenden, um eine Verbindung zum Server einzurichten. Der Aufruf dieses Cmdlets setzt die Verbindungsinformationen für den gesamten Prozess. Wenn Sie in einem Mehrbenutzerprozess arbeiten, müssen Sie die Auswirkungen der Verwendung dieses Befehls berücksichtigen.

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

Wenn Sie Skripte in der Integrated-Umgebung oder innerhalb von Apps oder APIs in PowerShell Universal ausführen, sollten Sie die Werte für Computername und Anmeldeinformationen direkt bei den Cmdlets angeben, um zu vermeiden, dass sie prozessweit geteilt werden.

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

Authentifizierung

App-Token

Sie können den Parameter -AppToken verwenden, um sich mit dem angegebenen Token gegenüber der API zu authentifizieren. Behandeln Sie das App-Token wie ein Passwort, da es Zugriff auf Basis der ihm zugewiesenen Rollen gewährt.

Standard-Anmeldeinformationen

Sie können auch Standard-Anmeldeinformationen bzw. Windows-Anmeldeinformationen verwenden. Dieser Mechanismus wird nur unterstützt, wenn auf dem Zielserver die Windows-Authentifizierung aktiviert ist. Rollen und Berechtigungen werden beim Verbinden mit dem Server gewährt.

Anmeldeinformationen

Wenn Sie die Formularauthentifizierung aktiviert haben, können Sie die Basic-Authentifizierung verwenden, indem Sie ein PSCredential-Objekt für den Parameter -Credential von Connect-PSUServer angeben.

Scope

Connect-PSUServer unterstützt einen Scope-Parameter, um zu definieren, wie die Verbindungsinformationen gespeichert werden. Standardmäßig ist der Scope „Process“. Der Prozess-Scope speichert die Verbindungsinformationen in einem statischen .NET-Scope. Alle im aktuellen Prozess ausgeführten Cmdlets verwenden diese Verbindungsinformationen.

Wenn Sie Connect-PSUServer in einer Umgebung mit mehreren Runspaces verwenden, wie in der Integrated-Umgebung oder innerhalb von Apps in PowerShell Universal, möchten Sie die Verbindungsinformationen möglicherweise nur für den aktuellen Runspace speichern. Verwenden Sie den Parameterwert -Scope Runspace, um anzupassen, wie die Verbindungsinformationen gespeichert werden.

Verbindung trennen

Sie können die Verbindung zum PowerShell Universal-Server mit dem Cmdlet Disconnect-PSUServer trennen. Wenn Sie den Runspace-Scope verwendet haben, werden die erforderlichen Variablen gelöscht, und wenn Sie den Process-Scope verwendet haben, werden die erforderlichen statischen Eigenschaften gelöscht.

Interne Verbindungen

Wenn Sie das Universal-Modul innerhalb von PowerShell Universal verwenden, ist es bei Standardinstallationen nicht erforderlich, Anmeldeinformationen oder den Computernamen anzugeben. Die Autorisierung entspricht dem aktuellen Benutzer, und die API-URL wird aus dem aktuellen Server abgeleitet.

Autorisierung

Bei Verwendung des Sicherheitsmodells „Strict“ basiert die Autorisierung auf dem Aufrufer. Wenn zum Beispiel ein Benutzer einen API-Endpunkt aufruft und dieser Endpunkt Invoke-PSUScript aufruft, erfolgt der Aufruf im Namen des Endpunkt-Aufrufers. Die Berechtigungen des Aufrufers werden bei der Skriptausführung durchgesetzt.

Bei Verwendung anderer Sicherheitsmodelle werden die Cmdlets im Namen des System-Benutzers aufgerufen, und die Autorisierung wird nicht basierend auf dem Aufrufer der Ressource durchgesetzt.

Autorisierungs-Sicherheitsmodell

Sie können das Autorisierungsmodell so ändern, dass alle Aufrufe innerhalb von PowerShell Universal ohne App-Token funktionieren. Auch wenn dies von manchen als weniger sicher betrachtet wird, hängt es davon ab, wie Ihre Organisation die Plattform nutzt. Dieser Wert kann in appsettings.json oder in der Umgebungsvariablen API__SecurityModel gesetzt werden.

Für die Authentifizierung ist ein Benutzerkontext erforderlich. Das bedeutet, dass Sie bei der Verwendung des Moduls in Kontexten ohne Benutzer, wie bei Schedules, ein App-Token angeben müssen.

In Scopes mit Benutzerkontext, wie einer App, erfolgen Aufrufe von Cmdlets mit den Berechtigungen dieses Benutzers. Wenn zum Beispiel ein Benutzer, der auf eine App zugreift, keine Berechtigung zum Aufruf von Get-PSUScript hat, ist das Cmdlet ohne ein App-Token mit diesen Berechtigungen nicht verwendbar.

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

Der Permissive-Modus verwendet weiterhin die externen PowerShell Universal-APIs und übermittelt beim Aufruf der PowerShell Universal-APIs den Benutzerkontext, sofern verfügbar. Der Permissive-Modus erlaubt die Verwendung des Schalters -Integrated, um die Autorisierung zu umgehen und die Backchannel-TCP-Verbindung anstelle der externen PowerShell Universal-API zu nutzen.

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

Sie können auch das Sicherheitsmodell Integrated verwenden, um die Konfiguration von App-Tokens, URLs oder Zertifikaten vollständig zu vermeiden. Das Sicherheitsmodell „Integrated“ übermittelt den Benutzerkontext nicht, selbst wenn der Benutzer authentifiziert ist. Es verwendet außerdem die Backchannel-TCP-Verbindung anstelle der externen PowerShell Universal-API.

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

HTTPS-Zertifikat vertrauen

In einigen Umgebungen kann es erforderlich sein, PowerShell Universal zu erlauben, dem Zertifikat des Webservers zu vertrauen, damit die Kommunikation erfolgreich funktioniert. Bei jedem Aufruf können Sie den Parameter -TrustCertificate verwenden, um dieses Verhalten zuzulassen. Zusätzlich können Sie den Wert auf Serverebene setzen, um interne Kommunikation zu ermöglichen.

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

Integrated-Modus

Der Integrated-Modus verwendet die interne Backchannel-Verbindung von PowerShell Universal, um über das Universal-Modul mit den Diensten zu kommunizieren. Bei Verwendung des Integrated-Modus wird die Autorisierung nur durchgeführt, wenn sich die API im Sicherheitsmodus „Strict“ befindet.

Sie können Cmdlets im Integrated-Modus aufrufen, indem Sie den Schalterparameter -Integrated verwenden.

Das Sicherheitsmodell des Servers kann ebenfalls auf Integrated gesetzt werden. Dadurch werden alle Cmdlet-Aufrufe gezwungen, den Integrated-Modus zu verwenden, und der Parameter -Integrated ist nicht mehr erforderlich.

Schedules

Schedules haben keinen aktuellen Benutzer. Sie müssen ein App-Token oder Standard-Anmeldeinformationen angeben, wenn Sie Cmdlets innerhalb geplanter Skripte verwenden. Auch wenn dies ein zusätzlicher Schritt ist, stellt es sicher, dass nur die erforderlichen Berechtigungen auf das geplante Skript angewendet werden.

Schedules haben keinen Benutzerkontext, daher müssen Sie einen angeben, damit sie bei Verwendung dieser Cmdlets ordnungsgemäß ausgeführt werden.

Reverse-Proxys (IIS)

PowerShell Universal verwendet alle verfügbaren Daten, um die richtige URL für den Aufruf der API zu bestimmen. Dies kann bei der Verwendung eines Reverse-Proxys wie IIS problematisch sein. Die URL, die PowerShell Universal sieht, unterscheidet sich von der tatsächlichen, erreichbaren URL. Dies kann zu Problemen führen, wenn die Cmdlets versuchen, auf die API zuzugreifen.

Um dieses Problem zu umgehen, können Sie entweder für jeden Cmdlet-Aufruf die richtige URL angeben oder die API-URL in den Anwendungseinstellungen anpassen.

Die URL angeben

Um die URL anzugeben, übergeben Sie sie einfach an den Parameter -ComputerName.

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

Anwendungseinstellungen

Sie können auch den API-URL-Wert in den Anwendungseinstellungen setzen, um denselben Wert plattformweit bereitzustellen. Setzen Sie den Wert entweder in einer Umgebungsvariablen oder in der Datei appsettings.json.

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

Technische Überlegungen

Das Universal-Modul verwendet gRPC für die gesamte Kommunikation mit dem PowerShell Universal-Server. Je nach Serverkonfiguration unterscheidet sich die gRPC-Kommunikation leicht.

HTTPS

Bei der Verwendung von HTTPS wird der standardmäßige gRPC-Kommunikationskanal genutzt. Dies ist die schnellste Konfiguration, da sie keine spezielle Serialisierung oder Anpassungen für ältere Protokolle erfordert. Für gRPC ist HTTP/2 erforderlich.

Wenn HTTPS verwendet wird, muss das Zertifikat vom System als vertrauenswürdig eingestuft werden. Wenn das Zertifikat selbstsigniert ist, können Sie den Parameter -TrustCertificate bei den Cmdlets verwenden, um die Zertifikatsprüfung zu vermeiden.

HTTP und Windows-Authentifizierung

Bei der Verwendung von HTTP oder Windows-Authentifizierung wird HTTP/2 nicht unterstützt und gRPC kann nicht nativ ausgeführt werden, da nachgestellte Header nicht unterstützt werden. Um dies zu berücksichtigen, verwendet das Universal-Modul eine Technologie namens gRPC-Web, um gRPC-Aufrufe in HTTP und JSON zu übersetzen und so HTTP-REST-Methoden anstelle der standardmäßigen gRPC-Methoden aufzurufen.

Diese Konfiguration ist etwas langsamer, sollte aber in den meisten Umgebungen nicht spürbar sein.

Integrated-Modus

Der Integrated-Modus verwendet nicht die externe API und kommuniziert über den gRPC-Backchannel von PowerShell Universal. Es ist nicht erforderlich, API-URLs, Zertifikate oder Anmeldeinformationen zu konfigurieren.