> 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/sicurezza/forms-authentication.md).

# Autenticazione basata su form

{% hint style="warning" %}
Lo script di autenticazione con moduli viene chiamato solo quando gli utenti accedono tramite la pagina di login. Se utilizza un altro metodo di autenticazione, questo script non viene chiamato. Gli script dei criteri dei ruoli vengono chiamati per tutti i tipi di autenticazione.
{% endhint %}

Per impostazione predefinita, lo script di autenticazione con moduli è configurato per accettare l'utente Admin e qualsiasi password. È possibile configurare questo criterio di autenticazione affinché interagisca con qualsiasi sistema desideri. Lo script riceverà un oggetto `PSCredential` che contiene il nome utente e la password inseriti dall'utente nella pagina di login.

{% hint style="info" %}
Le impostazioni di autenticazione vengono memorizzate anche con `authentication.ps1`
{% endhint %}

Per aggiornare l'autenticazione con moduli, può fare clic su Impostazioni Sicurezza e quindi fare clic sul pulsante Modifica codice per l'autenticazione con moduli.

Può aggiornare lo script PowerShell disponibile nelle impostazioni per configurare la modalità di autenticazione dell'utente. Sarà necessario restituire un `New-PSUAuthenticationResult` dallo script per indicare se l'utente è stato autenticato correttamente.

```powershell
param(
    [PSCredential]$Credential
)

#
#   You can call whatever cmdlets you like to conduct authentication here.
#   Just make sure to return the $Result with the Success property set to $true
#

if ($Credential.UserName -eq 'Admin') 
{
    New-PSUAuthenticationResult -Success -UserName 'Admin'
}
else 
{
    New-PSUAuthenticationResult -ErrorMessage 'Bad username or password'
}
```

## Impostazione di una password

Può verificare la password della credenziale utilizzando il metodo `GetNetworkCredential()` di `PSCredential`.

```powershell
param(
    [PSCredential]$Credential
)

#
#   You can call whatever cmdlets you like to conduct authentication here.
#   Just make sure to return the $Result with the Success property set to $true
#

if ($Credential.UserName -eq 'Admin' -and $Credential.GetNetworkCredential().Password -eq 'MySuperSecretPassword') 
{
    New-PSUAuthenticationResult -Success -UserName 'Admin'
}
else 
{
    New-PSUAuthenticationResult -ErrorMessage 'Bad username or password'
}
```

## Impostazione dei claim

Durante l'autenticazione con moduli, può impostare i claim che saranno disponibili all'interno dei criteri dei ruoli. Questo può offrire un vantaggio in termini di prestazioni durante l'interazione con sistemi remoti, poiché è possibile eseguire una singola ricerca dei claim e quindi valutarli localmente anziché dover effettuare chiamate aggiuntive al sistema remoto.

Questo esempio utilizza Active Directory per cercare l'appartenenza ai gruppi e assegnarla come claim che saranno disponibili all'interno degli script dei ruoli.

```powershell
param(
    [PSCredential]$Credential
)

#
#   You can call whatever cmdlets you like to conduct authentication here.
#   Just make sure to return the $Result with the Success property set to $true
#

$Result = [Security.AuthenticationResult]::new()
if ($Credential.UserName -eq 'Admin') 
{
    #Maintain the out of box admin user
    New-PSUAuthenticationResult -UserName 'Admin' -Success
}
else
{
    # Get current domain using logged-on user's credentials - this validates their credential
    $CurrentDomain = "LDAP://DC=mydemodomain,DC=com"  # Insert Your Domain Here
    $domain = New-Object System.DirectoryServices.DirectoryEntry($CurrentDomain,($Credential.UserName),$Credential.GetNetworkCredential().password)

    if ($domain.name -eq $null)
    {
        "Authentication failed for $($Credential.UserName)!" | Out-File "C:\test\adlogin.txt"
        write-host "Authentication failed - please verify your username and password."
        New-PSUAuthenticationResult -UserName $Credential.UserName
    }
    else
    {
        write-host "Successfully authenticated with domain $($domain.name)"
        "Authentication success for $($Credential.UserName)!" | Out-File "C:\test\adlogin.txt"

        New-PSUAuthenticationResult -UserName $Credential.UserName -Success -Claims { 
            Get-ADPrincipalGroupMembership $Credential.UserName | Select-Object -ExpandProperty name | ForEach-Object {
                New-PSUAuthorizationClaim -Type Role -Value $_
            }
        }
    }
}
```

All'interno del file `roles.ps1`, potrà utilizzare questi claim per convalidare l'appartenenza ai gruppi.

Questo esempio verifica se l'utente fa parte del gruppo SOC\_Admins.

```powershell
param($User)

$Roles = $User.Claims | Where-Object Type -eq Role | Select-Object -ExpandProperty Value
$Roles -contains 'SOC_Admins'
```

## Variabili

Queste sono le variabili definite all'interno degli script di sicurezza.

| Nome             | Descrizione                                     | Tipo      |
| ---------------- | ----------------------------------------------- | --------- |
| $Cookies         | Cookie forniti nella richiesta HTTP del client. | hashtable |
| $Headers         | Header forniti nella richiesta HTTP del client. | hashtable |
| $LocalIpAddress  | L'indirizzo IP locale della richiesta.          | string    |
| $LocalPort       | La porta locale della richiesta.                | string    |
| $RemoteIpAddress | L'indirizzo IP remoto della richiesta.          | string    |
| $RemotePort      | La porta remota della richiesta.                | string    |

## Autenticazione Basic

Quando chiama gli endpoint API o l'API di gestione di PowerShell, può utilizzare l'autenticazione Basic per passare un nome utente e una password. Questo richiamerà gli script di autenticazione e autorizzazione con moduli per convalidare il login. Il nome utente e la password devono essere codificati in Base64 nel formato `username:password` e inviati nell'header Authorization con il prefisso `Basic`.

```powershell
$credentials = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes("admin:admin"))
Invoke-RestMethod $Env:UniversalUrl/api/v1/accessible -Headers @{
    Authorization = "Basic $credentials"
} 
```

Può anche utilizzare il parametro integrato -Credential su Invoke-RestMethod per evitare di dover codificare autonomamente le credenziali Basic. Il `$AdminCredential` riportato di seguito deve essere un `PSCredential`.

```powershell
Invoke-RestMethod $Env:UniversalUrl/api/v1/accessible -Credential $AdminCredential -Authentication Basic
```

## Accesso Windows

Se abilita il Native Login sul metodo di autenticazione con moduli, PowerShell Universal tenterà di accedere al computer o al dominio corrente utilizzando le credenziali specificate. Una volta effettuato l'accesso, i gruppi dell'utente verranno raccolti e quindi forniti al sistema di autorizzazione.

Può configurare un dominio non predefinito specificando il dominio del native login. Se non specifica questo dominio, verrà utilizzato il dominio predefinito del computer o il dominio specificato dall'utente.

## Log in tempo reale

Può utilizzare la visualizzazione del log in tempo reale nella pagina di autenticazione per visualizzare informazioni sull'esecuzione dello script. La visualizzazione del log in tempo reale mostrerà i flussi di PowerShell.


---

# 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/sicurezza/forms-authentication.md?ask=<question>&goal=<endgoal>
```

`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.