Hosting

Sie können PowerShell Universal als Windows-Dienst, in IIS, als Azure Web App oder einfach als eigenständige Anwendung hosten. Wenn Sie unter Windows arbeiten, empfehlen wir entweder einen Windows-Dienst oder IIS.

Hosting als Windows-Dienst

Um als Windows-Dienst zu hosten, können Sie das PowerShell Universal MSI herunterladen und installieren. Das MSI installiert den PowerShell Universal-Dienst automatisch und startet ihn. Jobs werden standardmäßig unter dem Systemkonto ausgeführt, aber Sie können den Dienst nach der Installation so konfigurieren, dass er unter einem anderen Konto ausgeführt wird.

Nachdem das MSI die Einrichtung abgeschlossen hat, öffnet sich Ihr Standard-Webbrowser unter http://localhost:5000 zur Anmeldung. Die Standard-Anmeldeinformationen sind auf Admin und ein beliebiges Passwort festgelegt.

Einen Windows-Dienst manuell konfigurieren

Sie müssen das MSI nicht verwenden, um Universal als Windows-Dienst zu konfigurieren. Sie können dies auch manuell mit dem folgenden PowerShell-Skript tun.

New-Service -Name "PowerShellUniversal" -BinaryPathName "Universal.Server.exe --service" -Description "PowerShell Universal server service." -DisplayName "PowerShell Universal" -StartupType Automatic
Start-Service PowerShellUniversal

Hosting in Azure

Lesen Sie unseren Azure-Hosting-Leitfaden.

Manuelles Hosting

Sie können den Universal-Server auch als eigenständige Anwendung hosten. Führen Sie einfach die Universal.Server.exe aus dem Binärverzeichnis aus, um die Kestrel-Webserver-Implementierung in ASP.NET Core zum Starten des Webservers zu nutzen.

Webserver-Konfiguration

Dieser Abschnitt gilt für Universal, wenn es außerhalb von IIS gehostet wird.

Port und Listening-Adresse festlegen

Sie können den Port des Universal-Servers festlegen, indem Sie die Datei appsettings.json ändern. Wir empfehlen, eine appsettings.json-Datei im Standard-Konfigurationsordner zu erstellen.

Windows

%ProgramData%\PowerShellUniversal

Linux

%HOME%/.PowerShellUniversal

Um den Port festzulegen, ändern Sie den Abschnitt der Kestrel-Endpunkte in der appsettings.json. Standardmäßig ist die Konfiguration so definiert, dass auf Port 5000 und auf jeder Adresse gelauscht wird.

    "Kestrel": {
    "Endpoints": {
      "HTTP": {
        "Url": "http://*:5000"
      }
    }
  },

HTTPS konfigurieren

Um HTTPS zu konfigurieren, können Sie die Datei appsettings.json so anpassen, dass ein bestimmtes Zertifikat und ein bestimmter Port verwendet werden. Die folgende Konfiguration verwendet die Datei testCert.pfx und testPassword und lauscht auf Port 5463.

PFX-Zertifikate

{
  "Kestrel": {
    "Endpoints": {
       "HTTP": { "Url": "http://*:5000" },
           "HTTPS": {
              "Url": "https://*:5463",
              "Certificate": {
                  "Path": "testCert.pfx",
                  "Password": "testPassword"
              }
          }
    }
}

Zertifikatspeicher

Um ein Zertifikat an einem bestimmten Speicherort und in einem bestimmten Speicher zu konfigurieren, können Sie eine Konfiguration wie diese verwenden. Wenn Sie das Zertifikat nach dem Antragstellernamen auswählen, stellen Sie sicher, dass Sie den Common Name ohne das Präfix CN= verwenden.

{
  "Kestrel": {
    "Endpoints": {
      "HTTPS": {
         "Url": "https://*:443",
           "Certificate": {
             "Subject": "windows-server.ironman.local",
             "Store": "My",
             "Location": "LocalMachine",
             "AllowInvalid": "true"
           }
      }
   }
}

Der Speicherort kann entweder CurrentUser oder LocalMachine sein.

Zertifikatspeicher nach Fingerabdruck

Ab Version 3.4 können Sie den Fingerabdruck anstelle des Antragstellers verwenden.

{
  "Kestrel": {
    "Endpoints": {
      "HTTPS": {
         "Url": "https://*:443",
           "Certificate": {
             "Thumbprint": "SDFSDFSDFSDFSDFSDFSDFFSD",
             "Store": "My",
             "Location": "LocalMachine",
             "AllowInvalid": "true"
            }
         }
      }
   }
}

PEM- und Key-Zertifikate

Einige Anbieter wie Let's Encrypt und GoDaddy stellen Zertifikate als PEM- und Key-Textdateien aus. Sie können diese Arten von Zertifikaten direkt mit dem Kestrel-Webserver verwenden. Sie müssen den Abschnitt HttpsFromPem innerhalb der Endpoints für Kestrel angeben.

{
  "Kestrel": {
    "Endpoints": {
      "HTTP": {
        "Url": "http://*:5000"
      },
      "HttpsFromPem": {
        "Url": "https://*:5001",
        "Certificate": {
          "Path": "C:\\Users\\adamr\\Desktop\\cert.pem",
          "KeyPath": "C:\\Users\\adamr\\Desktop\\key.pem"
        }
      }
    },
    "RedirectToHttps": "true"
  },
}

Berechtigungen

Unter Windows benötigt der Benutzer, der den PowerShell Universal-Dienst ausführt, Zugriff auf das Zertifikat, um HTTPS ordnungsgemäß zu unterstützen. Dies ist typischerweise ein Problem, wenn der Dienst ein Group Managed Service Account verwendet. Sie können das folgende PowerShell-Skript verwenden, um die richtigen Berechtigungen zu erteilen.

$thumbprint = "<<THUMBPRINT>>"
$certPath = "C:\ProgramData\Microsoft\Crypto\RSA\MachineKeys"
$cert = Get-ChildItem -Path Cert:\LocalMachine\My\$thumbprint
$acl = Get-Acl -Path (Join-Path $certPath $cert.PrivateKey.CspKeyContainerInfo.UniqueKeyContainerName)
$gmSaAccount = "Domain\<<GMSA_Account>>$"
$accessRule = New-Object System.Security.AccessControl.FileSystemAccessRule($gmSaAccount, "Read", "Allow")
$acl.SetAccessRule($accessRule)
Set-Acl -Path (Join-Path $certPath $cert.PrivateKey.CspKeyContainerInfo.UniqueKeyContainerName) -AclObject $acl

Protokoll

Standardmäßig lauscht Universal auf HTTP1 und HTTP2. Sie können die Protokolle, auf die der Server lauscht, anpassen, indem Sie die Eigenschaft Protocols festlegen. Beispielsweise können Sie die Unterstützung für HTTP1 und HTTP2 mit der folgenden Einstellung gezielt festlegen.

"Kestrel": {
  "Endpoints": {
    "HTTP": {
      "Url": "http://*:5000",
      "Protocols": "Http1AndHttp2"
    }
  },
  "RedirectToHttps": "false"
},

Einige Versionen von Windows Server (wie 2012R2) unterstützen HTTP2 nicht. Um die HTTP2-Unterstützung zu deaktivieren, stellen Sie den Listener so ein, dass er nur auf HTTP1 lauscht.

"Kestrel": {
  "Endpoints": {
    "HTTP": {
      "Url": "http://*:5000",
      "Protocols": "Http1"
    }
  },
  "RedirectToHttps": "false"
},

Eine vollständige Liste der Listening-Optionen finden Sie in der ASP.NET Core-Dokumentation.

Sicherheits-Header

Organisationen können verlangen, dass PowerShell Universal bestimmte Sicherheits-Header in HTTP-Antworten des Servers bereitstellt. Dazu können gehören:

• Strict-Transport-Security
• Content-Security-Policy
• X-Frame-Options
• X-Content-Type-Options
• X-XSS-Protection
• Referrer-Policy

Sie können den Abschnitt Kestrel \ Headers verwenden, um diese Werte zu definieren.

{
    "Kestrel" : {
       "Headers": {
          "X-Content-Type-Options": "nosniff",
          "Content-Security-Policy": "default-src 'self';",
          "X-XSS-Protection": "block",
          "X-Frame-Options": "DENY"
       }
    }
}

Seien Sie beim Konfigurieren dieser Header vorsichtig, da sie das Verhalten jeder von PowerShell Universal zurückgegebenen Webanfrage ändern.

Beispiel: Selbstsigniertes Zertifikat

In diesem Beispiel zeigen wir, wie ein selbstsigniertes Zertifikat erstellt und mit PowerShell Universal verwendet wird.

Erstellen Sie zunächst ein selbstsigniertes Zertifikat und speichern Sie es in Ihrem lokalen Computerspeicher. Sie müssen PowerShell als Administrator ausführen. Der lokale Computerspeicher ist erforderlich, da PowerShell Universal möglicherweise als Dienst und nicht unter Ihrem Konto ausgeführt wird.

New-SelfSignedCertificate -DnsName localhost -CertStoreLocation cert:\LocalMachine\My

Als Nächstes müssen Sie PowerShell Universal so konfigurieren, dass es das Zertifikat verwendet. Dies können Sie erreichen, indem Sie die Datei appsettings.json in %ProgramData%\PowerShellUniversal bearbeiten oder erstellen. Diese Datei sollte bereits vorhanden sein, wenn Sie mit dem MSI-Installationsprogramm installiert haben. Der Inhalt der Datei sollte den DNS-Namen Ihres Zertifikats und den Speicherort enthalten.

Für selbstsignierte Zertifikate müssen Sie die Option AllowInvalid einbeziehen.

{
  "Kestrel": {
    "Endpoints": {
      "HTTPS": {
         "Url": "https://*:443",
           "Certificate": {
             "Subject": "localhost",
             "Store": "My",
             "Location": "LocalMachine",
             "AllowInvalid": "true"
           }
      }
   }
}

Nachdem Sie die Datei appsettings.json aktualisiert haben, starten Sie den PowerShell Universal-Dienst neu. Sie sollten nun unter https://localhost auf Ihre PowerShell Universal-Website zugreifen können.

Siehe auch

• Devolutions Academy – Creating a basic endpoint