> For the complete documentation index, see [llms.txt](https://docs.devolutions.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.devolutions.net/powershell-universal/de/config/module.md). # 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. ```powershell 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. ```powershell 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. ```json { "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. ```json { "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. ```json { "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. ```json { "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`. ```powershell 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`. ```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. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.devolutions.net/powershell-universal/de/config/module.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.