> 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/settings.md).

# Impostazioni dell'app

Configuri le impostazioni dell'applicazione PowerShell Universal in appsettings.json, che riguardano gli endpoint Kestrel, l'autenticazione, JWT e la persistenza dei dati.

Le impostazioni dell'applicazione si trovano nel file `appsettings.json` all'interno della directory di installazione. Questo file definisce varie impostazioni che può applicare a PowerShell Universal. Sebbene sia possibile modificare direttamente questo file, si consiglia di utilizzare uno dei metodi seguenti per rendere persistenti le impostazioni, poiché il file `appsettings.json` nella directory di installazione verrà sovrascritto durante gli aggiornamenti.

{% hint style="info" %}
Quando viene installato dall'MSI, la directory di installazione di PowerShell Universal è `${env:ProgramFiles(x86)}\Universal`.
{% endhint %}

## AppSettings.json in ProgramData

Può creare un file appsettings.json nella cartella `$Env:ProgramData\PowerShellUniversal`. Può utilizzare un sottoinsieme delle impostazioni presenti nel file `appsettings.json`. Ad esempio, se volesse sovrascrivere le impostazioni JWT, potrebbe avere un file `appsettings.json` come questo.

```javascript
{
  "Jwt": {  
    "SigningKey": "PleaseUseYourOwnSigningKeyHere",  
    "Issuer": "IronmanSoftware",
    "Audience": "PowerShellUniversal"
  }
}
```

## Variabili di ambiente

Può anche impostare variabili di ambiente per le sue impostazioni. Le variabili di ambiente devono avere un trattino basso tra ogni sottoinsieme del file `appsettings.json`. Ad esempio, se desidera modificare la chiave di firma JWT tramite variabile di ambiente, imposterebbe la variabile `$Env:Jwt__SigningKey`. Se volesse impostare l'URL dell'API esterna, imposterebbe `$Env:Api__Url`.

### Esempi

Utilizzo di una variabile di ambiente per il segreto OpenID Connect.

```
$Env:Authentication__OIDC__ClientSecret = "mySecret"
```

Utilizzo di una variabile di ambiente per la chiave di firma JWT.

```
$Env:Jwt__SigningKey = "mySigningKey"
```

## Riga di comando

Può specificare la posizione del file `appsettings.json` utilizzando l'argomento della riga di comando `--appsettings` per `Universal.Server.exe` .

```powershell
.\Universal.Server.exe --appsettings C:\appsettings.json
```

## Descrizioni delle impostazioni

### Kestrel / Endpoint

**Valore predefinito**

```javascript
"Kestrel": {
  "Endpoints": {
    "HTTP": {
      "Url": "http://*:5000"
    }
  },
  "RedirectToHttps": "false"
},
```

La sezione degli endpoint Kestrel le consente di configurare il server web. Queste impostazioni non vengono utilizzate quando l'hosting avviene in IIS. In questa sezione può configurare opzioni come HTTPS e la porta su cui PowerShell Universal resterà in ascolto.

Kestrel è l'implementazione del server web per ASP.NET Core utilizzata da PowerShell Universal. Per maggiori informazioni sulle opzioni di configurazione di Kestrel, visiti questa [pagina della documentazione Microsoft](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/servers/kestrel?view=aspnetcore-3.1#listenoptionsusehttps).

| Chiave            | Descrizione                                                                                                                                                          |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| RedirectToHttps   | Se impostato su true, il server web reindirizzerà le richieste HTTP a HTTPS                                                                                          |
| BasePath          | Richiesto quando si configura PowerShell Universal come sito annidato all'interno di IIS. Deve contenere il percorso IIS annidato, ad esempio `/psu`                 |
| Hsts \ MaxAgeDays | Imposta l'età massima in giorni per [HTTP Strict Transport Security](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Strict-Transport-Security). |
| CookiePolicy      | Se impostato su SameSiteNone, il valore SameSite=None verrà impostato sui cookie in PSU. Questo è utile quando si ospita PSU in iframe.                              |
| Headers           | Un oggetto in cui le chiavi sono le intestazioni da impostare su ogni richiesta e il valore è il valore dell'intestazione.                                           |

### Azure Application Insights

**Valore predefinito**

```javascript
"ApplicationInsights": {
  "ConnectionString": ""
},
```

| Chiave           | Descrizione                                                 |
| ---------------- | ----------------------------------------------------------- |
| ConnectionString | Imposta la stringa di connessione per Application Insights. |

### Registrazione

**Valore predefinito**

```javascript
{
    "SystemLogPath": "%PROGRAMDATA%/PowerShellUniversal/Logs/System/log.txt",
    "SystemLogLevel": "Information"
}
```

Imposta il percorso e il livello del log di sistema. Questo verrà sovrascritto dal livello di log in settings.ps1 dopo il suo caricamento. Questa impostazione è utile per il debug dei problemi durante l'avvio del sistema.

| Chiave         | Descrizione                                                                                    |
| -------------- | ---------------------------------------------------------------------------------------------- |
| SystemLogPath  | Percorso del file di log.                                                                      |
| SystemLogLevel | Il livello del log di sistema. Può impostare valori come Debug, Information, Warning ed Error. |

### AllowedHosts

**Valore predefinito**

```javascript
    "AllowedHosts": "*",
```

Gli host a cui è consentito connettersi al server web. Il valore predefinito è qualsiasi host.

### **CorsHosts**

**Valore predefinito**

```javascript
    "CorsHosts": "",
```

Configura gli host a cui è consentito effettuare richieste di condivisione delle risorse tra origini diverse (CORS) al server. Per consentire più host, separi ogni host con un punto e virgola.

```javascript
"CorsHosts" : "https://www.google.com;https://login.microsoftonline.com"
```

### **Data**

**Valore predefinito**

```javascript
"Data": {
  "RepositoryPath": "%ProgramData%\\UniversalAutomation\\Repository",
  "ConnectionString": "%ProgramData%\\UniversalAutomation\\database.db",
  "GitRemote": "",
  "GitUserName": "",
  "GitPassword": "", 
  "GitBranch": "",
  "ConfigurationScript": "",
  "ExternalGitClient": false,
  "Mode": "automatic",
  "SlowQueryLimit": 500,
  "Persistence": {}
},
```

| Chiave                     | Descrizione                                                                                                                                                        |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| RepositoryPath             | Percorso della posizione di archiviazione dei file di configurazione utilizzati da Universal.                                                                      |
| ConnectionString           | Percorso del database utilizzato da Universal.                                                                                                                     |
| GitRemote                  | Remote Git utilizzato per la sincronizzazione con Universal.                                                                                                       |
| GitBranch                  | Branch Git di cui effettuare il checkout durante la sincronizzazione con Universal.                                                                                |
| GitUserName                | Nome utente Git utilizzato per la sincronizzazione con GitRemote. Quando si utilizza un PAT, può essere un valore qualsiasi.                                       |
| GitPassword                | La password utente Git o il token di accesso personale utilizzato per la sincronizzazione con GitRemote.                                                           |
| GitSyncTimeout             | Il numero di secondi prima che un comando del client git esterno vada in timeout. Il valore predefinito è 60 secondi.                                              |
| ConfigurationScript        | Posizione di uno script di configurazione personalizzato da caricare. Da questo script può restituire oggetti come script, dashboard ed endpoint.                  |
| ExternalGitClient          | Se impostato su true, verrà utilizzato il client Git del sistema operativo anziché il client della libreria integrata                                              |
| Mode                       | Imposta la modalità git. Può essere manuale o automatica. Il valore predefinito è manuale.                                                                         |
| SlowQueryLimit             | Il numero di millisecondi di esecuzione di una query SQL prima che venga scritto un messaggio di log. Il valore predefinito è 200 ms. Disponibile solo per MS SQL. |
| Persistence                | Configura la [persistenza delle risorse nel database](/powershell-universal/it/config/repository.md).                                                              |
| InvisibilityTimeoutMinutes | Il numero di minuti prima che un job vada in timeout in Hangfire. Il valore predefinito è 5. Si applica solo a PostgreSQL.                                         |

### **API**

**Valore predefinito**

```javascript
"Api": {
  "Url": "",
  "HideManagementDoc": false
},
```

| Chiave            | Descrizione                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Url               | Imposta l'URL esterno utilizzato internamente da Universal. Questo è necessario quando si esegue Universal all'interno di un proxy inverso come IIS. Quando si utilizzano cmdlet come `Get-UAScript` all'interno di un job in esecuzione, il server Universal deve determinare dove si trova il server web. Quando è in esecuzione all'interno di un proxy, non può determinarlo da solo. In questa configurazione dovrà impostare questo valore in modo che punti al nome e alla porta del sito web IIS. |
| HideManagementDoc | Se true, nasconde la documentazione OpenAPI dell'API di gestione di PowerShell Universal.                                                                                                                                                                                                                                                                                                                                                                                                                 |

{% hint style="warning" %}
\`Api.Url\` viene utilizzato internamente da PowerShell Universal quando i cmdlet devono richiamare il server PSU da job, endpoint o altri contesti di esecuzione interni. Negli ambienti con proxy inverso o bilanciamento del carico, si assicuri che questo valore punti a un URL stabile e direttamente raggiungibile per l'host PSU. L'utilizzo di un alias DNS o di un altro endpoint indiretto può causare errori intermittenti dei cmdlet se tale alias viene risolto attraverso un proxy o un percorso di backend instabile. Se necessario, specifichi esplicitamente \`-ComputerName\` per la chiamata del cmdlet.
{% endhint %}

### **Autenticazione**

**Valore predefinito**

```javascript
"Authentication" : {
    "Windows": {
      "Enabled": "false"
    },
    "WSFed": {
      "Enabled": "false",
      "MetadataAddress": "",
      "Wtrealm": "",
      "CallbackPath": "/auth/signin-wsfed",
      "Wreply": "",
      "UseTokenLifetime": true,
      "CorrelationCookieSameSite": ""
    },
    "OIDC": {
      "Enabled": "false",
      "CallbackPath": "/auth/signin-oidc",
      "ClientID": "",
      "ClientSecret": "",
      "Resource": "",
      "Authority": "",
      "ResponseType": "",
      "SaveTokens": "false",
      "CorrelationCookieSameSite": "",
      "UseTokenLifetime": true
    },
    "OIDC": {
      "Enabled": "false",
      "CallbackPath": "/auth/signin-oidc",
      "ClientID": "",
      "ClientSecret": "",
      "Resource": "",
      "Authority": "",
      "ResponseType": "",
      "SaveTokens": "false",
      "CorrelationCookieSameSite": "",
      "UseTokenLifetime": true,
      "Scope": "openid profile groups",
      "GetUserInfo": false
    },
    "ClientCertificate": {
      "Enabled": "false"
    },
    "SessionTimeout": "25"
  },
```

**Windows**

| **Chiave** | Descrizione                                                                                                                              |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| Enabled    | Abilita o disabilita l'[autenticazione di Windows](/powershell-universal/it/api/security.md#authenticating-with-windows-authentication). |

#### OIDC

Impostazioni di autenticazione OpenID Connect.

| Chiave                    | Descrizione                                                                                                                                                         |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Enabled                   | Indica se OIDC è abilitato.                                                                                                                                         |
| CallbackPath              | Il percorso a cui il provider OIDC effettuerà la richiamata.                                                                                                        |
| ClientID                  | L'ID client OIDC configurato.                                                                                                                                       |
| ClientSecret              | Il segreto client OIDC configurato.                                                                                                                                 |
| Resource                  | Risorse concesse con questo token OIDC.                                                                                                                             |
| Authority                 | L'autorità da richiamare durante l'autenticazione. Si tratta dell'URL del suo provider OIDC.                                                                        |
| ResponseType              | Il tipo di risposta restituito dal provider. Il valore più comune qui è `code`                                                                                      |
| SaveTokens                | Indica se salvare il token in modo che sia disponibile per endpoint come le dashboard.                                                                              |
| CorrelationCookieSameSite | [Impostazioni SameSite del cookie di correlazione.](https://docs.microsoft.com/en-us/aspnet/core/security/samesite?view=aspnetcore-5.0)                             |
| UseTokenLifetime          | Se impostato su true, la durata del cookie verrà impostata sulla durata del token. Questo sovrascrive il valore di timeout della sessione.                          |
| GetUserInfo               | Restituisce informazioni aggiuntive sull'utente da utilizzare nei file roles.ps1. È possibile accedere alle informazioni aggiuntive tramite la variabile $UserInfo. |

#### WSFed

Impostazioni di autenticazione WS-Federation.

| Chiave                    | Descrizione                                                                                                                                |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| Enabled                   | Indica se WS-Fed è abilitato.                                                                                                              |
| MetadataAddress           | L'indirizzo dei metadati da cui recuperare le informazioni sull'istanza WS-Fed.                                                            |
| Wrealm                    |                                                                                                                                            |
| Wreply                    |                                                                                                                                            |
| CallbackPath              | Il percorso a cui il provider OIDC effettuerà la richiamata.                                                                               |
| UseTokenLifetime          | Se impostato su true, la durata del cookie verrà impostata sulla durata del token. Questo sovrascrive il valore di timeout della sessione. |
| CorrelationCookieSameSite | [Impostazioni same site del cookie di correlazione.](https://docs.microsoft.com/en-us/aspnet/core/security/samesite?view=aspnetcore-5.0)   |

#### Soglia di timeout della sessione (minuti)

| Chiave         | Descrizione                                                                                            |
| -------------- | ------------------------------------------------------------------------------------------------------ |
| SessionTimeout | Numero di minuti prima che una sessione con accesso effettuato vada in timeout (valore predefinito 25) |

### **JWT**

Impostazioni di configurazione dei JSON Web Token

**Valore predefinito**

```javascript
"Jwt": {  
  "SigningKey": "PleaseUseYourOwnSigningKeyHere",  
  "Issuer": "IronmanSoftware",
  "Audience": "PowerShellUniversal"
},
```

| Chiave     | Descrizione                                  |
| ---------- | -------------------------------------------- |
| SigningKey | La chiave di firma per i token JWT.          |
| Issuer     | L'emittente che verrà incluso nel token.     |
| Audience   | Il destinatario che verrà incluso nel token. |

### Secrets

Opzioni per configurare le casseforti dei segreti predefinite.

**Valore predefinito**

```json
"Secrets": {
  "SecretStore": {
    "Password": "PSUSecretStore"
  },
  "Database": {
    "EncryptionKey": "=b0ywQA@VOSdr&R7an5g&XK6NVO%s4Tf",
    "Password": "",
    "KeySize": 128
  },
  "SecretManagement": {
    "OutOfProcess": false
  }
}
```

| Chiave                          | Descrizione                                                                                                                      |
| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| SecretStore \ Password          | La password per la cassaforte PSUSecretStore. Utilizza il modulo Microsoft SecretStore.                                          |
| Database \ EncryptionKey        | La chiave di crittografia AES 128 utilizzata per crittografare i segreti archiviati nel database.                                |
| Database \ Password             | Una password utilizzata per generare una chiave di crittografia. EncryptionKey verrà ignorata se viene specificata una password. |
| Database \ KeySize              | Il numero di byte della chiave. Deve essere un multiplo di 128 e il valore predefinito è 128.                                    |
| SecretManagement \ OutOfProcess | Indica se le operazioni di gestione dei segreti devono essere eseguite fuori processo. Il valore predefinito è false.            |

#### Generazione di una chiave di crittografia

Le chiavi di crittografia sono a 128 bit e richiedono la lunghezza corretta. Sono codificate come stringa base64 e convertite in byte all'avvio.

È possibile utilizzare il codice seguente per generare una chiave segreta della lunghezza corretta.

```powershell
$random = [System.Security.Cryptography.RandomNumberGenerator]::Create();
$buffer = New-Object byte[] 16;
$random.GetBytes($buffer);
[Convert]::ToBase64String($buffer)
```

### UniversalAutomation

Impostazioni per le funzionalità specifiche dell'automazione.

**Valore predefinito**

```json
"UniversalAutomation": {
    "Queues": [],
    "JobHandshakeTimeout": 30,
    "JobDebugging": false,
    "ContinueJobOnServerStop": false,
    "HangfireWorkerCount" : 100
  }
```

| Chiave                  | Descrizione                                                                                                                                                                                                                                       |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Queues                  | Code personalizzate di cui questa istanza PSU fa parte.                                                                                                                                                                                           |
| JobHandshakeTimeout     | Il numero di secondi di attesa prima di far fallire un processo dopo l'avvio del processo PowerShell che lo esegue, se il processo non comunica con il server.                                                                                    |
| JobDebugging            | Indica se generare file nella directory temporanea all'avvio del processo. Utile per il debug se i processi vanno in timeout prima di avviarsi.                                                                                                   |
| ContinueJobOnServerStop | Indica se continuare l'esecuzione di un processo dopo l'arresto del servizio. L'avanzamento del processo non verrà segnalato, ma lo script continuerà a essere eseguito.                                                                          |
| HangfireWorkerCount     | Il numero di thread worker Hangfire da avviare sul server. Questa impostazione è specifica del nodo. Il valore predefinito è 100. Corrisponde al numero totale di processi che possono essere eseguiti contemporaneamente su un determinato nodo. |

### **HideAdminConsole**

```json
{
    "HideAdminConsole": false
}
```

Impedisce al servizio di erogare la console di amministrazione. In questo modo la console di amministrazione non potrà essere utilizzata da alcun utente, inclusi gli amministratori.

### NodeName

```json
{
    "NodeName": ""
}
```

L'opzione del nome del nodo viene utilizzata per modificare il nome dell'istanza di PowerShell Universal. Per impostazione predefinita, corrisponde al nome del computer locale. Quando si utilizza PowerShell Universal in un container, ciò può risultare problematico perché il nome può cambiare ogni volta che il container viene riavviato.

Per impostare un nome di nodo statico, modificare questo parametro.

## Risorse statiche

È possibile definire risorse statiche utilizzando le impostazioni dell'applicazione. Queste includono le variabili di ambiente e appsettings.json. Per definire una risorsa, utilizzare il nodo `Resources` all'interno di appsettings.json oppure il prefisso `Resources` con una variabile di ambiente.

Ad esempio, per definire un ruolo statico in appsettings.json, utilizzare quanto segue.

```json
{
    "Resources": {
        "Roles": [
            {
                "Name": "Static Role",
                "ClaimType": "group",
                "ClaimValue": "xyz123"
            }
        }
    }
}
```

È possibile definire lo stesso ruolo utilizzando le variabili di ambiente.

```powershell
$ENV:Resources__Roles__0__Name = "Static Role"
$ENV:Resources__Roles__0__ClaimType = "group"
$ENV:Resources__Roles__0__ClaimValue = "xyz123"
```

### Esempio: Docker Compose

È possibile utilizzare le variabili di ambiente in un file YML di Docker Compose per definire risorse che saranno disponibili in PowerShell Universal dopo l'avvio. L'esempio seguente crea tag e un ruolo, imposta un titolo di amministrazione personalizzato, aggiunge una licenza e imposta l'ambiente predefinito.

```yaml
services:    
    psu:         
      image: devolutions/powershell-universal:latest
      environment:
          - Resources__Tags__0__Name=Production  
          - Resources__Tags__1__Name=Development
          - Resources__Roles__0__Name=PSUAdmin
          - Resources__Roles__0__ClaimType=groups
          - Resources__Roles__0__ClaimValue=1234567890abcdef1234567890abcdef
          - Resources__Roles__0__Permissions_0=*
          - Resources__Settings__DefaultEnvironment=PowerShell 7
          - Resources__Branding__AdminConsoleTitle=PSU Admin Console
          - Authentication__OIDC__Enabled=true
          - Authentication__OIDC__ClientId=123-123-123-123-123
          - Authentication__OIDC__ClientSecret=secret
          - Authentication__OIDC__Authority=https://login.microsoftonline.com/123-123-123-123
          - PSULICENSE=<License></License>
      ports:
        - "5000:5000"
```

## Impostazioni del runtime .NET

Anche il runtime .NET supporta impostazioni che si applicano a PowerShell Universal. Potrebbe essere necessario modificare queste impostazioni in base alle proprie esigenze.

Tutte le informazioni sono disponibili nelle [impostazioni del runtime .NET su Microsoft Docs](https://learn.microsoft.com/en-us/dotnet/core/runtime-config/).

### File temporanei eccessivi

Negli ambienti Linux, il runtime potrebbe creare molti file temporanei per abilitare le funzionalità di debug. [Disabilitando le impostazioni di diagnostica](https://learn.microsoft.com/en-us/dotnet/core/runtime-config/debugging-profiling#enable-diagnostics) del runtime si eviterà che ciò accada. Con questa opzione disabilitata non sarà possibile utilizzare gli strumenti di debug .NET.

```powershell
$Env:DOTNET_EnableDiagnostics = $false
```

### Vedere anche

* [Devolutions Academy – Creating a basic endpoint](https://academy.devolutions.net/student/activity/3466014-creating-a-basic-endpoint)


---

# 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/settings.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.