App Settings

Describes how to set application settings and a definition of the settings.

Application settings can be found within the appsettings.json file within the installation directory. This file defines various settings you can apply to PowerShell Universal. Although you can edit this file directly, it's recommended that you use one of the following methods to persist settings as the appsettings.json file in the installation directory will be overridden on upgrades.

When installed from the MSI, the installation directory for PowerShell Universal is ${env:ProgramFiles(x86)}\Universal.

ProgramData AppSettings.json

You can create an appsettings.json file within the $Env:ProgramData\PowerShellUniversal folder. You can use a subset of the settings from within the appsettings.json file. For example, if you wanted to override the JWT settings, you could have an appsettings.json file like this.

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

Environment Variables

You can also set environment variables for your settings. Environment variables should have an underscore between each subset of the appsettings.json file. For example, if you want to change the JWT signing key via environment variable, you would set the variable $Env:Jwt__SigningKey. If you wanted to set the external API URL, you would set $Env:Api__Url.

Examples

Using an environment variable for the OpenID Connect secret.

$Env:Authentication__OIDC__ClientSecret = "mySecret"

Using an environment variable for JWT signing key.

$Env:Jwt__SigningKey = "mySigningKey"

Command Line

You can specify the location of the appsettings.json file by using the --appsettings command line argument for Universal.Server.exe .

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

Setting Descriptions

Kestrel / Endpoints

Default Value

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

The Kestrel endpoints section allows you to configure the web server. This settings are not used when hosting in IIS. In this section you can configure options like HTTPS and the port that PowerShell Universal will listen on.

Kestrel is the web server implementation for ASP.NET Core that PowerShell Universal uses. For more information on the configuration options for Kestrel, visit this Microsoft Documentation page.

Key

Description

RedirectToHttps

When true, the web server will redirect HTTP requests to HTTPS

BasePath

Required when configuring PowerShell Universal as a nested site within IIS. This should contain the nested IIS route. Such as /psu

Hsts \ MaxAgeDays

Sets the max age in days for HTTP Strict Transport Security.

CookiePolicy

When set to SameSiteNone, the SameSite=None value will be set on cookies in PSU. This is useful for when hosting PSU in iframes.

Headers

An object where the keys are the headers to set on each request with the value being the value of the header.

Azure Application Insights

Default value

"ApplicationInsights": {
  "ConnectionString": ""
},

Key

Description

ConnectionString

Sets the connection string for Application Insights.

Logging

Default Value

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

Sets the system log path and level. This will be overridden by the log level in settings.ps1 after it loads. This setting is useful for debugging issues during system start up.

Key

Description

SystemLogPath

Path to the log file.

SystemLogLevel

The system log level. You can set values such as Debug, Information, Warning and Error.

AllowedHosts

Default Value

    "AllowedHosts": "*",

The hosts that are allowed to connect to the webserver. Defaults to any host.

CorsHosts

Default Value

    "CorsHosts": "",

Configures the hosts that are allowed to make cross-origin resource sharing requests (CORS) to the server. To allow multiple hosts, separate each host by a semicolon.

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

Data

Default Value

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

Key

Description

RepositoryPath

Path to the storage location of the configuration files used by Universal.

ConnectionString

Path to the database used by Universal.

GitRemote

Git remote used to sync to Universal.

GitBranch

Git branch to checkout when syncing to Universal.

GitUserName

Git user name used to sync to the GitRemote. When using a PAT, this can be any value.

GitPassword

The Git user password or personal access token used to sync to the GitRemote.

ConfigurationScript

Location of a custom configuration script to load. You can return objects like scripts, dashboards and endpoints from this script.

ExternalGitClient

When set to true the Operating Systems Git client will be used instead of the inbuilt library client

Mode

Sets the git mode. It can be either manual or automatic. Defaults to manual.

SlowQueryLimit

The number of milliseconds a SQL query needs to run before a log message is written. Defaults to 500ms. Only available for MS SQL.

API

Default Value

"Api": {
  "Url": ""
},

Key

Description

Url

Sets the external URL used internally by Universal. This is necessary when running Universal from within a reverse proxy like IIS. When using cmdlets like Get-UAScript from within a running job, the Universal server needs to determine where the web server. When running within a proxy, it cannot determine this itself. You will want to configure this to point to the name and port of the IIS website in this configuration.

Authentication

Default Value

"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

Key

Description

Enabled

Enables or disables Windows Authentication.

OIDC

OpenID Connect authentication settings.

Key

Description

Enabled

Whether OIDC is enabled.

CallbackPath

The path that the OIDC provider will call back to.

ClientID

The configured OIDC client ID.

ClientSecret

The configured OIDC client secret.

Resource

Resources granted with this OIDC token.

Authority

The authority to invoke when authenticating. This is the URL of your OIDC provider.

ResponseType

The type of response returned by the provider. This most common value here is code

SaveTokens

Whether to save the token so it is available to endpoints like dashboards.

CorrelationCookieSameSite

Correlation cookie same settings.

UseTokenLifetime

If set to true, the cookie life time will be set to the token life time. This overrides the session time out value.

GetUserInfo

Returns additional user information for use within roles.ps1 files. You can access the additional information using the $UserInfo variable.

WSFed

WS-Federation authentication settings.

Key

Description

Enabled

Whether WS-Fed is enabled.

MetadataAddress

The metadata address to retrieve information about the WS-Fed instance.

Wrealm

Wreply

CallbackPath

The path that the OIDC provider will call back to.

UseTokenLifetime

If set to true, the cookie life time will be set to the token life time. This overrides the session time out value.

CorrelationCookieSameSite

Correlation cookie same settings.

Session timeout threshold (minutes)

Key

Description

SessionTimeout

Number of minutes before a logged in session times out (defaults to 25)

JWT

JSON Web Token configuration settings

Default Value

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

Key

Description

SigningKey

The signing key for the JWT tokens.

Issuer

The issuer that will be included in the token.

Audience

The audience that will be included in the token.

Secrets

Options for configuring the default secret vaults.

Default Value

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

Key

Description

SecretStore \ Password

The password for the PSUSecretStore vault. This uses the Microsoft SecretStore module.

Database \ EncryptionKey

The AES 128 encryption key used to encrypt secrets stored in the database.

Database \ Password

A password used to generate an encryption key. EncryptionKey will be ignored if password is specified.

Database \ KeySize

The number of bytes in the key. Should be a multiple of 128 and defaults to 128.

Generating an Encryption Key

Encryption keys are 128-bit and require the proper length. They are encoded as a base64 string and converted to bytes on startup.

You can use the following code to generate a secret key of the proper length.

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

UniversalAutomation

Settings for automation specific features.

Default Value

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

Key

Description

Queues

Custom queues that this PSU instance is a part of.

JobHandshakeTimeout

The number of seconds to wait before failing a job after starting the PowerShell process to execute it if the process does not communicate back to the server.

JobDebugging

Whether to generate files in the temporary directory when starting job. This is useful for debugging if jobs are timing out before starting.

ContinueJobOnServerStop

Whether to continue running a job after the service has stopped. Job progress will fail to be reported but the script will continue to run.

HangfireWorkerCount

The number of Hangfire worker threads to start on the server. This setting is node specific. It defaults to 100. This is the total number of jobs that can run on the particular node at a single time.

HideAdminConsole

{
    "HideAdminConsole": false
}

Prevents the service from serving the admin console. This will prevent the admin console from being used by any user, including administrators.

NodeName

{
    "NodeName": ""
}

The node name option is used to change the name of the PowerShell Universal instance. By default, this is the local computer's name. When using PowerShell Universal in a container, this can become probematic because the name can change whenever the container is restarted.

To set a static node name, change this parameter.

Profiling

{
    "Profiling": "false"
}

Enables profiling of scripts within PowerShell Universal. This is disabled by default as there is a memory impact when enabling profiling.

PreviousAgent NextBest Practices

Last updated 27 days ago

Was this helpful?