> 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/api/security.md). # Sicurezza Una volta abilitata, potrà applicare autenticazione e autorizzazione ai suoi endpoint. ## Definizione di endpoint sicuri Può definire endpoint sicuri nell'interfaccia utente abilitando l'autenticazione. Troverà l'autenticazione e l'autorizzazione dell'endpoint nella scheda Sicurezza delle proprietà di un endpoint. Può anche definire endpoint sicuri utilizzando il file `.universal/endpoints.ps1` o l'API di gestione tramite `New-PSUEndpoint`. ```powershell New-PSUEndpoint -Url '/endpoint' -Method 'GET' -Endpoint { "Hello, world!" } -Authentication ``` Quando l'autenticazione è abilitata, verrà imposto l'uso di uno dei metodi di autenticazione configurati. Le API supportano i metodi seguenti. * Token applicativi JWT * Autenticazione Windows * Autenticazione tramite cookie * Autenticazione di base ## Accesso agli endpoint sicuri Una volta definito un endpoint sicuro, dovrà fornire autenticazione e autorizzazione per accedere all'endpoint. ### Autenticazione con token {% hint style="warning" %} Tenga presente che se l'hosting avviene in IIS e l'autenticazione anonima non è abilitata, non sarà possibile passare i token applicativi al server PowerShell Universal. {% endhint %} Per autenticarsi con i token, per prima cosa deve generare un nuovo token applicativo da utilizzare. Può usare il cmdlet `Grant-PSUAppToken` per farlo da remoto oppure può creare un token applicativo nell'interfaccia utente tramite la scheda Impostazioni Sicurezza AppTokens. Passi il mouse sul suo nome utente in alto a destra nella console di amministrazione, faccia clic su Tokens e poi su Create Application Token. Una volta creato il token applicativo, può utilizzarlo per autenticarsi verso l'endpoint sicuro. Per farlo, passi l'intestazione Authorization insieme alla richiesta. ```powershell Invoke-RestMethod http://localhost:5000/auth -Headers @{ Authorization = "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2NsYWltcy9uYW1lIjoiQWRtaW4iLCJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2NsYWltcy9oYXNoIjoiMWUyY2IzNzAtMmMyNS00ZDU5LTk4YzgtMzc5MTFjMDAyZmI5Iiwic3ViIjoiUG93ZXJTaGVsbFVuaXZlcnNhbCIsImh0dHA6Ly9zY2hlbWFzLm1pY3Jvc29mdC5jb20vd3MvMjAwOC8wNi9pZGVudGl0eS9jbGFpbXMvcm9sZSI6IkFkbWluaXN0cmF0b3IiLCJuYmYiOjE2MDU2NjEyNTUsImV4cCI6MTYzNzM2NzI1OCwiaXNzIjoiSXJvbm1hblNvZnR3YXJlIiwiYXVkIjoiUG" } ``` #### Intestazione di autorizzazione personalizzata PowerShell Universal fornisce un'intestazione di autorizzazione personalizzata per supportare scenari con reverse proxy che possono richiedere una propria intestazione Authorization. Se viene specificata l'intestazione `X-PSU-Authorization`, PSU ignorerà l'intestazione `Authorization` e utilizzerà invece questa intestazione. ``` Invoke-RestMethod http://localhost:5000/auth -Headers @{ Authorization = "Bearer msft_xyz_123" 'X-PSU-Authorization' = 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2NsYWltcy9uYW1lIjoiQWRtaW4iLCJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2NsYWltcy9oYXNoIjoiMWUyY2IzNzAtMmMyNS00ZDU5LTk4YzgtMzc5MTFjMDAyZmI5Iiwic3ViIjoiUG93ZXJTaGVsbFVuaXZlcnNhbCIsImh0dHA6Ly9zY2hlbWFzLm1pY3Jvc29mdC5jb20vd3MvMjAwOC8wNi9pZGVudGl0eS9jbGFpbXMvcm9sZSI6IkFkbWluaXN0cmF0b3IiLCJuYmYiOjE2MDU2NjEyNTUsImV4cCI6MTYzNzM2NzI1OCwiaXNzIjoiSXJvbm1hblNvZnR3YXJlIiwiYXVkIjoiUG' } ``` ### Autenticazione con l'autenticazione Windows Per autenticarsi con l'[autenticazione Windows](/powershell-universal/it/sicurezza/security.md#windows-authentication-in-iis), può utilizzare il parametro `-UseDefaultCredentials` di `Invoke-RestMethod` e `Invoke-WebRequest`. Questo eseguirà l'autenticazione negotiate sia che l'esecuzione avvenga in IIS sia come servizio. ```powershell Invoke-RestMethod http://localhost:5000/auth -UseDefaultCredentials ``` ### Autenticazione con i cookie Per autenticarsi con i cookie, dovrà innanzitutto chiamare l'API di login per ricevere un cookie valido dal sistema. Può utilizzare `Invoke-WebRequest` per farlo. Passi il nome utente e la password come corpo della richiesta. Specifichi il parametro `-SessionVariable` per stabilire una sessione. ```powershell Invoke-WebRequest http://localhost:5000/api/v1/signin -Body (@{ UserName = "Admin" Password = "Any" } | ConvertTo-Json) -ContentType 'application/json' -SessionVariable mySession -Method POST ``` Una volta effettuata l'autenticazione con successo, può utilizzare la variabile `$mySession` per chiamare gli endpoint sicuri. ```powershell Invoke-WebRequest http://localhost:5000/auth -WebSession $mySession ``` ## Applicazione dei ruoli Oltre a creare endpoint che richiedono l'autenticazione, può anche applicare i ruoli definendo un ruolo nel cmdlet `New-PSUEndpoint` o selezionandone uno nell'interfaccia utente. Se viene selezionato un ruolo, è necessario possedere tale ruolo. L'autenticazione Windows e tramite cookie assegnerà i ruoli in base all'identità dell'utente e alle policy dei ruoli così come vengono applicate. I token applicativi JWT utilizzeranno il ruolo definito al momento della loro generazione. ## Ruoli di esecuzione Utilizzando la proprietà Ruoli di esecuzione, può impostare quali ruoli vengono assegnati durante l'esecuzione dell'endpoint API. Per impostazione predefinita, l'endpoint verrà eseguito in base ai ruoli del chiamante. In alcuni scenari, ad esempio quando si utilizzano i Secrets con i ruoli, potrebbe voler fornire ruoli aggiuntivi che il chiamante potrebbe non possedere. I ruoli di esecuzione non richiedono che l'autenticazione API sia abilitata. ## API * [New-PSUEndpoint](/powershell-universal/it/comandi-powershell/new-psuendpoint.md) * [Get-PSUEndpoint](/powershell-universal/it/comandi-powershell/get-psuendpoint.md) * [Remove-PSUEndpoint](/powershell-universal/it/comandi-powershell/remove-psuendpoint.md) * [New-PSUApiResponse](/powershell-universal/it/comandi-powershell/new-psuapiresponse.md) * [Set-PSUSetting](/powershell-universal/it/comandi-powershell/set-psusetting.md) --- # 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/api/security.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.