Hosting

Può ospitare PowerShell Universal come servizio Windows, in IIS, come app Web di Azure o semplicemente come applicazione autonoma. Se lo esegue su Windows, consigliamo un servizio Windows oppure IIS.

Hosting come servizio Windows

Per l'hosting come servizio Windows, può scaricare e installare l'MSI di PowerShell Universal. L'MSI installerà automaticamente il servizio PowerShell Universal e lo avvierà. Per impostazione predefinita i job vengono eseguiti con l'account di sistema, ma può configurare il servizio per l'esecuzione con un altro account dopo l'installazione.

Al termine dell'installazione dell'MSI, il browser web predefinito si aprirà su http://localhost:5000 per il login. Le credenziali di accesso predefinite sono impostate su Admin e una password qualsiasi.

Configurare manualmente un servizio Windows

Non è necessario utilizzare l'MSI per configurare Universal come servizio Windows. Può farlo anche manualmente con il seguente script PowerShell.

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

Consulti la nostra guida all'hosting in Azure.

Hosting manuale

Può anche ospitare il server Universal come applicazione autonoma. È sufficiente eseguire Universal.Server.exe dalla directory dei binari per utilizzare l'implementazione del server web Kestrel in ASP.NET Core per avviare il server web.

Configurazione del server web

Questa sezione si applica a Universal quando è ospitato al di fuori di IIS.

Impostare la porta e l'indirizzo di ascolto

Può impostare la porta del server Universal modificando il file appsettings.json. Consigliamo di creare un file appsettings.json nella cartella di configurazione predefinita.

Windows

%ProgramData%\PowerShellUniversal

Linux

%HOME%/.PowerShellUniversal

Per impostare la porta, modifichi la sezione degli endpoint Kestrel di appsettings.json. Per impostazione predefinita, la configurazione è definita per l'ascolto sulla porta 5000 e su qualsiasi indirizzo.

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

Configurare HTTPS

Per configurare HTTPS, può modificare il file appsettings.json in modo da utilizzare un certificato e una porta specifici. La configurazione seguente utilizza il file testCert.pfx e testPassword e resta in ascolto sulla porta 5463.

Certificati PFX

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

Archivio certificati

Per configurare un certificato in una posizione e in un archivio specifici, può utilizzare una configurazione come questa. Quando seleziona il certificato in base al nome del soggetto, si assicuri di utilizzare il common name senza il prefisso CN=.

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

La posizione può essere CurrentUser o LocalMachine.

Archivio certificati per identificazione personale

Nella versione 3.4 e successive può utilizzare l'identificazione personale anziché il soggetto.

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

Certificati PEM e chiave

Alcuni provider, come Let's Encrypt e GoDaddy, rilasciano i certificati sotto forma di file di testo PEM e key. Può utilizzare questi tipi di certificati direttamente con il server web Kestrel. Dovrà specificare la sezione HttpsFromPem all'interno di Endpoints per 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"
  },
}

Autorizzazioni

Su Windows, l'utente che esegue il servizio PowerShell Universal dovrà avere accesso al certificato per poter fornire correttamente il supporto HTTPS. Si tratta di un problema tipico quando il servizio utilizza un Group Managed Service Account. Può utilizzare il seguente script PowerShell per fornire le autorizzazioni corrette.

$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

Protocollo

Per impostazione predefinita, Universal resta in ascolto su HTTP1 e HTTP2. Può modificare i protocolli su cui il server resta in ascolto impostando la proprietà Protocols. Ad esempio, può impostare in modo specifico il supporto per HTTP1 e HTTP2 con la seguente impostazione.

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

Alcune versioni di Windows Server (come 2012R2) non supportano HTTP2. Per disabilitare il supporto HTTP2, imposti il listener in modo che resti in ascolto solo su HTTP1.

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

Per l'insieme completo delle opzioni di ascolto, può fare riferimento alla documentazione di ASP.NET Core.

Intestazioni di sicurezza

Le organizzazioni possono richiedere che PowerShell Universal fornisca determinate intestazioni di sicurezza nelle risposte HTTP provenienti dal server, tra cui:

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

Può utilizzare la sezione Kestrel \ Headers per definire questi valori.

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

Presti attenzione durante la configurazione di queste intestazioni, poiché modificano il comportamento di ogni richiesta web restituita da PowerShell Universal.

Esempio: certificato autofirmato

In questo esempio mostreremo come creare un certificato autofirmato e utilizzarlo con PowerShell Universal.

Innanzitutto, crei un certificato autofirmato e lo memorizzi nell'archivio del computer locale. Dovrà eseguire PowerShell come amministratore. L'archivio del computer locale è necessario perché PowerShell Universal potrebbe essere in esecuzione come servizio e non con il suo account.

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

Successivamente, dovrà configurare PowerShell Universal per l'utilizzo del certificato. Può farlo modificando o creando il file appsettings.json in %ProgramData%\PowerShellUniversal. Questo file dovrebbe già esistere se ha effettuato l'installazione con il programma di installazione MSI. Il contenuto del file deve includere il nome DNS del certificato e la posizione.

Per i certificati autofirmati dovrà includere l'opzione AllowInvalid.

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

Dopo aver aggiornato il file appsettings.json, riavvii il servizio PowerShell Universal. Ora dovrebbe essere in grado di accedere al suo sito web PowerShell Universal all'indirizzo https://localhost.

Vedere anche

• Devolutions Academy – Creating a basic endpoint