Modulo

Connessione a PowerShell Universal

Il modulo PowerShell Universal richiede alcune informazioni per connettersi al server. Per prima cosa, deve conoscere l'URL o il nome del computer; in secondo luogo, ha bisogno delle credenziali per accedere alle risorse da remoto.

Può utilizzare il cmdlet Connect-PSUServer per configurare una connessione al server. La chiamata di questo cmdlet imposta le informazioni di connessione per l'intero processo. Se sta eseguendo il codice in un processo multiutente, deve considerare le implicazioni dell'uso di questo comando.

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

Quando esegue script nell'ambiente Integrated o all'interno di App o API in PowerShell Universal, valuti di utilizzare i valori del nome computer e delle credenziali direttamente nei cmdlet, per evitare di condividerli all'interno del processo.

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

Autenticazione

App Token

Può utilizzare il parametro -AppToken per autenticarsi con l'API tramite il token specificato. Tratti l'App Token come una password, poiché concede l'accesso in base ai ruoli ad esso assegnati.

Credenziali predefinite

Può utilizzare anche le credenziali predefinite, o credenziali di Windows. Questo meccanismo è supportato solo se il server di destinazione ha l'autenticazione Windows abilitata. I ruoli e le autorizzazioni verranno concessi al momento della connessione al server.

Credenziali

Se ha abilitato l'autenticazione tramite modulo, può utilizzare l'autenticazione Basic specificando un oggetto PSCredential nel parametro -Credential di Connect-PSUServer.

Ambito

Connect-PSUServer supporta un parametro di ambito per definire come rendere persistenti le informazioni di connessione. Per impostazione predefinita, l'ambito è Process. L'ambito di processo memorizza le informazioni di connessione in un ambito statico .NET. Tutti i cmdlet eseguiti nel processo corrente utilizzeranno queste informazioni di connessione.

Se utilizza Connect-PSUServer in un ambiente con più runspace, come l'ambiente Integrated o all'interno di app in PowerShell Universal, potrebbe voler memorizzare le informazioni di connessione solo per il runspace corrente. Utilizzi il valore di parametro -Scope Runspace per modificare la modalità di memorizzazione delle informazioni di connessione.

Disconnessione

Può disconnettersi dal server PowerShell Universal utilizzando il cmdlet Disconnect-PSUServer. Se ha utilizzato l'ambito Runspace, verranno cancellate le variabili necessarie e, se ha utilizzato l'ambito Process, verranno cancellate le proprietà statiche necessarie.

Connessioni interne

Quando si utilizza il modulo Universal all'interno di PowerShell Universal, non è necessario specificare le credenziali o il nome del computer nelle installazioni di base. L'autorizzazione corrisponderà all'utente corrente e l'URL dell'API verrà dedotto dal server corrente.

Autorizzazione

Quando si utilizza il modello di sicurezza Strict, l'autorizzazione si basa sul chiamante. Ad esempio, se un utente chiama un endpoint API e tale endpoint chiama Invoke-PSUScript, la chiamata viene effettuata per conto del chiamante dell'endpoint. Le autorizzazioni del chiamante vengono applicate all'esecuzione dello script.

Quando si utilizzano altri modelli di sicurezza, i cmdlet vengono chiamati per conto dell'utente System e l'autorizzazione non viene applicata in base al chiamante della risorsa.

Modello di sicurezza dell'autorizzazione

Può modificare il modello di autorizzazione per consentire a qualsiasi chiamata proveniente da PowerShell Universal di funzionare senza un app token. Sebbene alcuni possano considerarlo meno sicuro, dipende dall'uso che la sua organizzazione fa della piattaforma. Questo valore può essere impostato in appsettings.json o nella variabile d'ambiente API__SecurityModel.

Per l'autenticazione è necessario un contesto utente. Ciò significa che, quando utilizza il modulo in contesti privi di utente, come le pianificazioni, dovrà fornire un app token.

Negli ambiti che dispongono di un contesto utente, come un'app, le chiamate ai cmdlet vengono effettuate con i privilegi di quell'utente. Ad esempio, se un utente che accede a un'app non dispone dell'accesso per chiamare Get-PSUScript, il cmdlet non sarà utilizzabile senza un app token con tali privilegi.

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

La modalità Permissive utilizza comunque le API esterne di PowerShell Universal e comunica il contesto utente, se disponibile, quando chiama le API di PowerShell Universal. La modalità Permissive consente l'uso dello switch -Integrated per bypassare l'autorizzazione e utilizzare la connessione TCP back-channel anziché l'API esterna di PowerShell Universal.

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

Può anche utilizzare il modello di sicurezza Integrated per evitare completamente la necessità di configurare app token, URL o certificati. Il modello di sicurezza Integrated non comunica il contesto utente, nemmeno quando l'utente è autenticato. Utilizza inoltre la connessione TCP back-channel anziché l'API esterna di PowerShell Universal.

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

Attendibilità del certificato HTTPS

In alcuni ambienti può essere necessario consentire a PowerShell Universal di considerare attendibile il certificato del server web affinché la comunicazione avvenga correttamente. Su ogni chiamata può utilizzare il parametro -TrustCertificate per abilitare questo comportamento. Inoltre, può impostare il valore a livello di server per consentire le comunicazioni interne.

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

Modalità Integrated

La modalità Integrated utilizza la connessione backchannel interna di PowerShell Universal per comunicare con i servizi tramite il modulo Universal. Quando si utilizza la modalità Integrated, l'autorizzazione viene eseguita solo se l'API è in modalità di sicurezza Strict.

Può richiamare i cmdlet in modalità Integrated utilizzando il parametro switch -Integrated.

Il modello di sicurezza del server può anche essere impostato su Integrated. Ciò impone a tutte le chiamate dei cmdlet di utilizzare la modalità Integrated e non richiede più l'uso del parametro -Integrated.

Pianificazioni

Le pianificazioni non hanno un utente corrente. Dovrà specificare un App Token o una credenziale predefinita quando utilizza i cmdlet all'interno di script pianificati. Sebbene si tratti di un passaggio aggiuntivo, garantisce che allo script pianificato vengano applicate solo le autorizzazioni necessarie.

Le pianificazioni non hanno un contesto utente, pertanto dovrà specificarne uno affinché vengano eseguite correttamente quando utilizza questi cmdlet.

Reverse proxy (IIS)

PowerShell Universal utilizza tutti i dati disponibili per determinare l'URL corretto da chiamare quando si utilizza l'API. Ciò può essere problematico quando si utilizza un reverse proxy, come IIS. L'URL che PowerShell Universal rileva è diverso dall'URL effettivo e accessibile. Questo può causare problemi quando i cmdlet tentano di accedere all'API.

Per ovviare a questo problema, può specificare l'URL corretto per ogni chiamata di cmdlet oppure personalizzare l'URL dell'API nelle impostazioni dell'applicazione.

Specificare l'URL

Per specificare l'URL, è sufficiente fornirlo al parametro -ComputerName.

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

Impostazioni dell'applicazione

Può anche impostare il valore dell'URL dell'API nelle impostazioni dell'applicazione per fornire lo stesso valore su tutta la piattaforma. Imposti il valore in una variabile d'ambiente oppure nel file appsettings.json.

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

Considerazioni tecniche

Il modulo Universal utilizza gRPC per tutte le comunicazioni con il server PowerShell Universal. A seconda della configurazione del server, la comunicazione gRPC sarà leggermente diversa.

HTTPS

Quando si utilizza HTTPS, verrà impiegato il canale di comunicazione gRPC standard. Si tratta della configurazione più veloce, poiché non richiede serializzazioni speciali o adattamenti per protocolli di livello inferiore. Per gRPC è necessario HTTP/2.

Se si utilizza HTTPS, il certificato deve essere considerato attendibile dal sistema. Se il certificato è autofirmato, può utilizzare il parametro -TrustCertificate sui cmdlet per evitare il controllo del certificato.

HTTP e autenticazione Windows

Quando si utilizza HTTP o l'autenticazione Windows, HTTP/2 non è supportato e gRPC non può essere eseguito nativamente perché i trailing header non sono supportati. Per ovviare a ciò, il modulo Universal utilizzerà una tecnologia chiamata gRPC-Web per tradurre le chiamate gRPC in HTTP e JSON, in modo da chiamare metodi REST HTTP anziché i metodi gRPC standard.

Questa configurazione è leggermente più lenta, ma nella maggior parte degli ambienti non dovrebbe essere percepibile.

Modalità Integrated

La modalità Integrated non utilizza l'API esterna e comunica tramite il backchannel gRPC di PowerShell Universal. Non è necessario configurare URL dell'API, certificati o credenziali.