PowerShell Universal
DownloadsIssuesDiscordForums
v5
v5
  • ❓About
  • 🆕What's New in v5?
  • ⏯️Get Started
  • 📺Video Library
  • 📚Additional Resources
  • ⬇️Installation
    • Docker
    • Upgrade
    • Uninstall
    • Downgrade
    • Migrate and Restore
  • 🔑Licensing
  • 📊System Requirements
  • 🌐Supported Browsers
  • Cmdlet Help
  • 🔌API
    • About
    • Endpoints
    • OpenAPI
    • Event Hubs
    • Security
    • Error Handling
    • Rate Limiting
  • 🤖Automation
    • About Automation
    • Scripts
      • Parameters
    • Jobs
    • Schedules
    • Terminals
    • Tests
    • Triggers
  • 📊Apps
    • About
    • Apps
    • Components
      • Pages
      • Data Display
        • Alert
        • Badge
        • Chip
        • Data Grid
        • Date and Time
        • Icon
        • List
        • Markdown
        • Table
        • Timeline
        • Tooltip
        • Tree View
        • Typography
      • Data Visualization
        • Charts
        • Image
        • Map
      • Feedback
        • Backdrop
        • Modal
        • Progress
        • Skeleton
      • Inputs
        • Autocomplete
        • Button
        • Checkbox
        • Code Editor
        • Date Picker
        • Editor
        • Floating Action Button
        • Form
        • Radio
        • Rating
        • Select
        • Slider
        • Switch
        • Textbox
        • Time Picker
        • Transfer List
        • Upload
      • Navigation
        • Drawer
        • Link
        • Menu
        • Stepper
        • Tabs
      • Layout
        • Grid Layout
        • Grid
        • Hidden
        • Stack
      • Utilities
        • Dynamic Regions
        • Element
        • Error Boundary
        • Protect Section
        • Transitions
        • HTML
      • Surfaces
        • AppBar
        • Card
        • Paper
        • Expansion Panel
      • Custom Components
        • Building Custom JavaScript Components
    • Custom Variable Scopes
    • Interaction
    • Role Based Access
    • Scheduled Endpoints
    • Sessions
    • Static Apps
    • Themes
      • Colors
      • Cascading Style Sheets
      • Styles
  • 🌐Portal
    • About the Universal Portal
    • Portal Pages
    • Portal Widgets
      • Syntax
      • Conditions
      • Dynamic
      • Forms
      • Properties
      • Services
      • Tables
  • 🏗️Platform
    • Cache
    • Computers
    • Health Checks
    • Gallery
    • Middleware
    • Modules
    • Monitoring
    • Notifications
    • Plugins
    • Published Folders
    • Tags
    • Telemetry
    • Translations
    • User Sessions
    • Variables
  • 🔒Security
    • About
    • Local Accounts
    • Forms Authentication
    • Authorization
    • App Tokens
    • Enterprise Security
      • Client Certificate
      • OpenID Connect
      • SAML2
      • WS-Federation
      • Windows SSO
      • Permissions
  • ⚙️Configuration
    • Agent
    • App Settings
    • Best Practices
    • Branding
    • Command Line Options
    • Deployments
    • Environments
    • Feature Flags
    • Git
    • Hosting
      • Azure
      • High Availability
      • IIS
      • Reverse Proxy
    • Management API
    • Module
    • Persistence
    • psu Command Line Tool
    • Repository
    • Running as a Service Account
  • 👩‍💻Development
    • Debugging Scripts
    • Editor
    • Hangfire
    • Logging
    • Profiling
    • Visual Studio Code Extension
  • Changelogs
    • Changelog
    • Extension Changelog
    • Roadmap
    • CVEs
Powered by GitBook

PowerShell Universal

  • Downloads
  • Pricing
  • Gallery

Community

  • Issues
  • Forums
  • Discord

Support

  • Portal
  • Knowledgebase

Copyright 2025 Ironman Software

On this page
  • Creating a Variable
  • Creating a Secret Variable
  • Credential Format
  • Group Managed Service Accounts
  • Credential Validation
  • Roles
  • Vaults
  • Database
  • BuiltInLocalVault
  • PSUSecretStore
  • Az.KeyVault
  • vaults.ps1
  • Importing Secret Variables
  • Using Variables
  • Secret Scope
  • Access Variables by Name
  • Access Values Dynamically
  • ForEach-Object -Parallel
  • Configuring the PSUSecretStore Password
  • Built-In Variables
  • API
  • Apps
  • Scripts
  • Preference Variables
  • API

Was this helpful?

Edit on GitHub
Export as PDF
  1. Platform

Variables

Information about PowerShell Universal variables.

PreviousUser SessionsNextAbout

Last updated 9 days ago

Was this helpful?

Variables allow for the global definition of variables that are available within scripts. You can also import secrets that are also available within scripts or as run as credentials.

Variables are stored in the variables.ps1 configuration file.

Creating a Variable

To create a variable, navigate to the Platform \ Variables page. Click Create Variable to define a new variable.

Variables will be added to your scripts before they are run.

Creating a Secret Variable

Secret variables are stored within the selected vault. The value of those variables is never stored within Universal. To define a new secret variable, click Create Secret Variable on the variables page and select the Secret tab.

From this dialog, you'll be able to define string and PSCredentials in the specified vault.

Credential Format

In some environments, it may be necessary to specify the domain name in the user name field. You can specify in either the domain\user or user@domain format. If you do not do so, you will receive errors when attempting to start processes, like scripts or dashboards, as that user account.

Group Managed Service Accounts

Credential Validation

On Windows, you can validate credentials before saving their value. Click the Validate button on the password field to attempt to login the user locally. This button will not appear on non-Windows systems.

Roles

Applying roles to a secret will prevent the secret from being accessible in scheduled jobs because no roles are applied in the scheduler.

Secret variables can include role-based access. Roles limit who can use the secret in their scripts and as run as credentials.

When a secret has a role defined, it will not be accessible in resources that cannot provide that role. This can include the following:

  • Schedule Jobs

  • Unauthenticated APIs or Apps

  • Terminals

Vaults

Database

The database vault stores secrets within the PowerShell Universal database. These secrets are encrypted using AES encryption using a customizable key. You can customize the key by specifying the Secrets \ Database \ EncryptionKey.

appsettings.json

You can configure this setting in appsettings.json.

"Secrets": {
  "Database": {
    "EncryptionKey": "=b0ywQA@VOSdr&R7an5g&XK6NVO%s4Tf"
  }
}

Environment Variable

You can configure this setting with an environment variable.

$Env:Secrets__Database__EncryptionKey = "=b0ywQA@VOSdr&R7an5g&XK6NVO%s4Tf"

BuiltInLocalVault

If PowerShell Universal is run as a group managed service account, it cannot use the BuiltInLocalVault.

Values for secrets with the BuiltInLocalVault are stored within the Windows Credential Manager instance of the security principal that is running PSU. For example, the service account of the user running the Universal service. If you change users (such as running as a service account), the account will not have access to the previous user's secrets and you will need to add those secrets again.

PSUSecretStore

If PowerShell Universal is run as a group managed service account, it cannot use the PSUSecretStore.

The PSUSecretStore vault is integrated with the Microsoft SecretStore module to store secrets in a cross-platform file. Ths file is tied to the current user account running PowerShell Universal. The password for the vault is stored in appsettings.json.

Az.KeyVault

Below you will find how to configure it. This example uses an Azure hosted web-app version of PowerShell Universal.

In Azure, we'll need to configure a managed identity for our web app. This step isn't necessarily required if you are running outside of Azure. You can enable the managed identity under the Identity page for your web app.

Next, you'll need to allow your managed identity to access your key vault and read your subscription. You can add the managed identity to the builtin Reader group to allow access to the subscription.

Then, I provided all privileges to secret and key management for my managed identity in my Key Vault resource.

Finally, we will need to register the key vault and connect to Azure when the web app starts. This can be accomplished by using the Az.Account and Az.KeyVault modules.

After deploying your web-app, you will need to first install the Az.Account and Az.KeyVault modules. You can do so on the modules page. They will be installed to the local repository within the web app.

Next, create a script within PowerShell Universal to connect to Azure and register the vault. Run the script to verify it works properly.

$sub = 'affdf0d4-eed5-48a6-889c-599d482xxxxx'
Connect-AzAccount -Id -Scope CurrentUser -SubscriptionId $sub

Register-SecretVault -ModuleName Az.KeyVault -Name AzureKeyVault -VaultParameters @{ 
    AZKVaultName = 'psu-demo'
    SubscriptionId = $sub
} -AllowClobber

Now, when you are creating secrets, you will see the AzureKeyVault available.

To ensure the application is connected to Azure and the key vault is registered, run the script within vaults.ps1. We recommend running the script in an external PowerShell process to avoid assembly conflicts with PowerShell Universal DLLs.

$pwsh = (Get-Command pwsh).Path
& $pwsh -File "$PSScriptRoot\registerVault.ps1"

This script runs before variables are registered and vaults are located. You can create this file directly in the Repository\.universal directory. It will be run during system startup before other configuration scripts are run.

vaults.ps1

The vaults.ps1 file contains vault registration commands. While the above example defines an Azure KeyVault secret vault registration, you can actually include any vault registration you need in this file.

You can edit vaults by clicking Platform \ Variables \ Vaults and then navigate to the vaults.ps1 tab.

Importing Secret Variables

You can also import pre-existing secrets as variables into Universal. The variable values are not imported but will be looked up during execution. Click the Import Secret button to import secrets.

Using Variables

$MyVariable

You can customize which variables are allowed in an environment by customizing the environments -Variable parameter.

Secret Scope

To access secrets that you have added to PowerShell Universal, you can use the $Secret scope. For example, if you defined a secret named Credential, you could access that secret anywhere with the secret scope. You cannot set secrets using the secret scope.

Invoke-Command -Credential $Secret:Credential { Write-Host "Hello" }

Access Variables by Name

You can access variables by name using the $Secret: prefix.

# PSCredential
$Secret:MyNewSecret.UserName
$Secret:MyNewSecret.Password

# String
$Secret:DashboardSecret

Access Values Dynamically

You can access the secret scope dynamically by using Get-Item. The secret scope is implemented as a provider. This is helpful if you don't have static variable names.

# PSCredential
(Get-ChildItem "Secret:MyNewSecret").UserName
(Get-ChildItem "Secret:MyNewSecret").Password

# String
(Get-ChildItem "Secret:DashboardSecret")

ForEach-Object -Parallel

In order to use secrets when using ForEach-Object with the -Parallel parameter, you will need to take advantage of the $using keyword.

1..5 | ForEach-Object -Parallel {
  $using:Secret:MySecret
}

Configuring the PSUSecretStore Password

By default, the PSUSecretStore vault password is stored within appsettings.json in Secrets \ SecretStore \ Password.

Built-In Variables

The following variables are available throughout all environments within PowerShell Universal.

Name
Type
Description

$PSUEnvironment

string

The name of the environment the script is running within (e.g. Integrated)

$Repository

string

The absolute path to the repository folder.

API

There are a set of predefined variables that are available in API endpoints. You'll be able to use these variables in your scripts.

Variable
Description
Type

$Url

URL the client used to call the endpoint

String

$Method

The HTTP method used to call the endpoint

String

$Headers

Headers provided by the client to call the endpoint

Hashtable

$Body

The UTF8 encoded string of the content of the request

String

$Data

Binary byte array for the content of the request

Byte[]

$RemoteIpAddress

The remote IP address used to make the request.

String

$LocalIpAddress

The local IP address used to service the request.

String

$RemotePort

The remote port that was called to make the request.

Integer

$LocalPort

The local port that was used to service the request.

Integer

$Identity

The identity name of the principal accessing the API.

String

$UrlDefinition

The definition for the URL.

String

$ConnectionId

String

$SessionId

String

$RequestId

String

$ClaimsPrincipal

The claims principal of the current user. This is the same object that is provided to role-based access policies.

Apps

Below are variables that are available in apps in addition to the global variables.

Name
Description
Type

$User

The user name of the logged in user. $Null if authentication is disabled.

String

$Roles

The roles that the user has been granted. $Null if authentication is disabled.

String[]

$RemoteIpAddress

The remote IP address of the connected user.

String

$RemotePort

The remote port of the connected user.

Int

$ClaimsPrincipal

The claims principal of the current user. This is the same object that is provided to role-based access policies.

$Headers

The headers provided by the browser.

hashtable

$Cookies

The request cookies provided by the browser.

hashtable

$PSUAppToken

The app token of the current user. Only available when -GrantAppToken is enabled.

string

$PSUComputerName

The URL of the PSU server. Only available when -GrantAppToken is enabled.

string

$DashboardName

The name of the current app

string

$Query

The query string parameters from the URL of the app

Hashtable

$RefreshToken

The refresh token when using OpenID Connect

string

$AccessToken

The app token when using OpenID Connect

string

$UDPage

The name of the current page.

string

Scripts

There are several built-in variables that are defined when a job is run. You can use these variables in your scripts to retrieve information about the current job.

Name
Description

$UAJob

The current job that is running. This will include properties such as the script, the user that started the job and when the job was started.

$UAJobId

The ID of the running job.

$UAScript

The script that is running. This will include properties such as the name of the script and path to the script.

$UAScriptId

The ID of the running script.

$UASchedule

The schedule that was used to start the script.

$UAScheduleId

The ID of the schedule that started the script.

$AccessToken

When using OIDC authentication, you can retrieve the current user's access token for access resources on their behalf.

$UAJob Object Structure

Note that properties may be null. DateTime objects are return in UTC time zone.

class Job {
    public long Id { get; set; }
    public DateTime CreatedTime { get; set; }
    public DateTime StartTime { get; set; }
    public DateTime EndTime { get; set; }
    public JobStatus Status { get; set; }
    public string Output { get; set; }
    public string ScriptFullPath { get; set; }
    public Identity Identity { get; set; }
    public Job ParentJob { get; set; }
    public int ParentLineNumber { get; set; }
    public string ComputerName { get; set; }
    public int ProcessId { get; set; }
    public long MemoryBytes { get; set; }
    public int RunspaceId { get; set; }
    public string Activity { get; set; }
    public string CurrentOperation { get; set; }
    public int PercentComplete { get; set; }
    public int SecondsRemaining { get; set; }
    public string StatusDescription { get; set; }
    public string Environment { get; set; }
    public Computer Computer { get; set; }
    public ActionPreference ErrorAction { get; set; }
    public IEnumerable<Job> Children { get; set; }
    public IEnumerable<JobParameter> Parameters { get; set; }
    public string Credential { get; set; }
    public long ScheduleId { get; set; }
    public bool Triggered { get; set; }
    public string Trigger { get; set; }
    public int RetryCount { get; set; }
    public string Tags { get; set; }
    public string Schedule { get; set; }
    public bool Archived { get; set; }
    public bool Batch { get; set; }
    public Guid? RunId { get; set; }
    public string Roles { get; set; }
}

public enum JobStatus
{
    Queued,
    Running,
    Completed,
    Failed,
    WaitingOnFeedback,
    Canceled,
    Canceling,
    Historical,
    Active,
    TimedOut,
    Warning,
    Error
}

Retrieving the user that started a script

You can retrieve the name of the user that started the script by using the UAJob variable

$UAJob.Identity.Name

Checking if a job was run manually

You can check if a job was run manually by using the Schedule and Trigger properties.

$Manual = $UAJob.Schedule -eq $null -and $UAJob.Trigger -eq $null

Preference Variables

Preference variables can be configured on a script, during the execution of a job and on a global level. These include:

  • DebugPreference

  • ErrorActionPreference

  • InformationPreference

  • ProgressPreference

  • VerbosePreference

  • WarningPreference

The preference variables have precedence. The following list is ordered in precedence. For example, if a script manually sets the $DebugPreference variable, it will override the value set in the script's properties dialog.

  • Script

  • Run Dialog or Invoke-PSUScript

  • Script Properties

  • Global Settings

API

When using Group Managed Service Accounts (GMSA), you will need to ensure that the machine and account has access to the GSMA account. You can follow . Once configuration is complete, create a new credential in PowerShell Universal secret management and select the Password Not Required option. Enter the GSMA account (e.g. domain\user$). As long as the hosting account has the proper privileges, you will be able to run jobs are the GMSA account.

By default, we do not include the Azure Key Vault extension directly in PowerShell Universal As of Powershell Universal v4.0.11, a container including the required Az.Accounts and Az.KeyVault modules is avilable to allow you use KeyVault out of the box. This can be found on .

Variables can be used in APIs, Scripts and Dashboards. When using the default environments, all variables are automatically imported. This is accomplished by specifying the -Variable parameter of New-PSUEnvironment with a wild card (*). If you are using your own environments, you will have to configure . You can reference a variable like you would any other PowerShell variable. The variable will contain the value you set. If you use a secret, it will contain the secret's value.

See for more information.

The .

The

The

🏗️
Microsoft's guide here
Docker Hub
which variables you would like included
New-PSUVariable
Get-PSUVariable
Remove-PSUVariable
Set-PSUVariable
HTTP Context connection ID
HTTP Context session ID.
HTTP Context request ID.
ClaimPrincipal
ClaimPrincipal
Environments
Create Variable dialog
Secret Variable Dialog
Secret Variables Vault Selector