Variables
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 Add Variable to define a new variable.
Standard variables are just name \ value pairs of strings. They 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 Add 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.
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.
Environment Variable
You can configure this setting with an environment variable.
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
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
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 Docker Hub.
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.
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 initialize.ps1
. We recommend running the script in an external PowerShell process to avoid assembly conflicts with PowerShell Universal DLLs.
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.
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
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 which variables you would like included. 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.
You can customize which variables are allowed in an environment by customizing the environments -Variable
parameter.
See Environments for more information.
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.
Access Variables by Name
You can access variables by name using the $Secret:
prefix.
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.
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.
Configuring the PSUSecretStore
Password
PSUSecretStore
PasswordBy 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 |
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.
Retrieving the user that started a script
You can retrieve the name of the user that started the script by using the UAJob
variable
Checking if a job was run manually
You can check if a job was run manually by using the Schedule and Trigger properties.
API
Last updated