> 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/it/config/module.md). # 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. ```powershell 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. ```powershell 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. ```json { "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. ```json { "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. ```json { "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. ```json { "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`. ```powershell 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`. ```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. --- # 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/it/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.