Hébergement

Diverses méthodes d'hébergement pour PowerShell Universal.

Vous pouvez héberger PowerShell Universal en tant que service Windows, dans IIS, en tant qu'application web Azure ou simplement en tant qu'application autonome. Si vous utilisez Windows, nous vous recommandons soit un service Windows, soit IIS.

Hébergement en tant que service Windows

Pour héberger en tant que service Windows, vous pouvez télécharger et installer le MSI de PowerShell Universal. Le MSI installera automatiquement le service PowerShell Universal et le démarrera. Les tâches s'exécutent sous le compte système par défaut, mais vous pouvez configurer le service pour qu'il s'exécute sous un autre compte après l'installation.

Une fois la configuration du MSI terminée, votre navigateur web par défaut s'ouvrira à l'adresse http://localhost:5000 pour vous connecter. Les identifiants de connexion par défaut sont Admin et n'importe quel mot de passe.

Configuration manuelle d'un service Windows

Vous n'avez pas besoin d'utiliser le MSI pour configurer Universal en tant que service Windows. Vous pouvez également le faire manuellement avec le script PowerShell suivant.

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

Hébergement dans Azure

Consultez notre guide d'hébergement Azure.

Hébergement manuel

Vous pouvez également héberger le serveur Universal en tant qu'application autonome. Il suffit d'exécuter Universal.Server.exe depuis le répertoire binaire pour utiliser l'implémentation du serveur web Kestrel dans ASP.NET Core et démarrer le serveur web.

Configuration du serveur web

Cette section s'applique à Universal lorsqu'il est hébergé en dehors de IIS.

Définition du port et de l'adresse d'écoute

Vous pouvez définir le port du serveur Universal en modifiant le fichier appsettings.json. Nous vous recommandons de créer un fichier appsettings.json dans le dossier de configuration par défaut.

Windows

%ProgramData%\PowerShellUniversal

Linux

%HOME%/.PowerShellUniversal

Pour définir le port, modifiez la section des points de terminaison Kestrel du fichier appsettings.json. Par défaut, la configuration est définie pour écouter sur le port 5000 et sur toute adresse.

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

Configuration de HTTPS

Pour configurer HTTPS, vous pouvez ajuster le fichier appsettings.json afin d'utiliser un certificat et un port particuliers. La configuration ci-dessous utilise le fichier testCert.pfx avec le mot de passe testPassword et écoute sur le port 5463.

Certificats PFX

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

Magasin de certificats

Pour configurer un certificat dans un emplacement et un magasin particuliers, vous pouvez utiliser une configuration de ce type. Lorsque vous sélectionnez le certificat par nom de sujet, assurez-vous d'utiliser le nom commun sans le préfixe CN=.

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

L'emplacement peut être CurrentUser ou LocalMachine.

Magasin de certificats par empreinte numérique

Vous pouvez utiliser l'empreinte numérique plutôt que le sujet dans la version 3.4 et les versions ultérieures.

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

Certificats PEM et clé

Certains fournisseurs, comme Let's Encrypt et GoDaddy, émettent des certificats sous forme de fichiers texte PEM et clé. Vous pouvez utiliser ces types de certificats directement avec le serveur web Kestrel. Vous devrez spécifier la section HttpsFromPem dans les Endpoints pour Kestrel.

{
  "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"
  },
}

Autorisations

Sur Windows, l'utilisateur exécutant le service PowerShell Universal devra avoir accès au certificat afin de prendre correctement en charge HTTPS. Cela peut poser problème si le service utilise un compte de service géré de groupe. Vous pouvez utiliser le script PowerShell suivant pour accorder les autorisations appropriées.

$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

Protocole

Par défaut, Universal écoute sur HTTP1 et HTTP2. Vous pouvez ajuster les protocoles sur lesquels le serveur écoute en définissant la propriété Protocols. Par exemple, vous pouvez spécifiquement activer la prise en charge de HTTP1 et HTTP2 avec le paramètre suivant.

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

Certaines versions de Windows Server (comme 2012R2) ne prennent pas en charge HTTP2. Pour désactiver la prise en charge de HTTP2, configurez l'écouteur pour qu'il écoute uniquement sur HTTP1.

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

Pour un ensemble complet d'options d'écoute, vous pouvez consulter la documentation ASP.NET Core.

En-têtes de sécurité

Les organisations peuvent exiger que PowerShell Universal fournisse certains en-têtes de sécurité dans les réponses HTTP provenant du serveur, notamment :

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

Vous pouvez utiliser la section Kestrel \ Headers pour définir ces valeurs.

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

Soyez prudent lors de la configuration de ces en-têtes, car ils modifient le comportement de chaque requête web retournée par PowerShell Universal.

Exemple : certificat auto-signé

Dans cet exemple, nous allons montrer comment créer un certificat auto-signé et l'utiliser avec PowerShell Universal.

Tout d'abord, créez un certificat auto-signé et stockez-le dans votre magasin de l'ordinateur local. Vous devrez exécuter PowerShell en tant qu'administrateur. Le magasin de l'ordinateur local est requis car PowerShell Universal peut s'exécuter en tant que service et non sous votre compte.

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

Ensuite, vous devrez configurer PowerShell Universal pour utiliser le certificat. Pour ce faire, modifiez ou créez le fichier appsettings.json dans %ProgramData%\PowerShellUniversal. Ce fichier devrait déjà exister si vous avez effectué l'installation avec le programme d'installation MSI. Le contenu du fichier doit inclure le nom DNS de votre certificat et l'emplacement.

Pour les certificats auto-signés, vous devrez inclure l'option AllowInvalid.

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

Une fois le fichier appsettings.json mis à jour, redémarrez le service PowerShell Universal. Vous devriez maintenant pouvoir accéder à votre site web PowerShell Universal à l'adresse https://localhost.