Requirements for using the 1E PowerShell Toolkit

Running PowerShell

PowerShell Integrated Scripting Environment (ISE): When you request PowerShell by typing PowerShell at the Windows start prompt, you are taken into an instance of the PowerShell ISE, not a standard PowerShell session. While the 1E PowerShell Toolkit will work within the ISE, there are two important considerations:

The interactive search feature is not available because the PowerShell ISE does not emulate the single character keyboard input functionality that is used.
Scripts under the ISE run much slower than they do in a regular PowerShell environment. This is because the ISE is primarily intended for script debugging.

Consequently, in most situations, you should run the 1E PowerShell Toolkit from a regular PowerShell session. You can start a regular session by just typing PowerShell from the Windows command prompt.

To learn about how to install the Toolkit, refer to Installing the 1E PowerShell Toolkit.

Setting the 1E Platform server

Before you can use the 1E PowerShell Toolkit, you must define the 1E Platform server to which it will connect. Set the 1E Platform server you want to communicate with using the following:

Copy

set-1Eserver <server name>

For example, if the 1E Platform server is platform.urth.local, use the following:

Copy

set-1Eserver platform.urth.local

If you fail to set the 1E Platform server, any command you subsequently invoke will throw an exception and indicate that you need to set this first.

The above PowerShell command also confirms that the platform server responds appropriately when set. If you specify an invalid server address, or the server is not responding correctly, an error will be thrown.

If, while using Windows authentication, you wish to connect to the 1E Platform server using alternate credentials (that is, not in the context of your current user account), then you can use the optional -Credential parameter to set-1Eserver. To be prompted for these credentials, use the standard PowerShell get-credential cmdlet. For example: -Credential (get-credential).

When connecting using modern authentication, you can either connect interactively and be prompted for credentials or use a certificate to connect non-interactively. For more information on the Set-1EServer cmdlet, refer to Platform server management cmdlets.

Script customization

To customize the ps1EToolkit.psm1 script, simply change the variables at the top of the script to reflect the environment in which you are working. The current set of customizable variables is shown below.

Copy

1
2
3
4
$TACHYONCONSUMER = "Explorer" # Consumer to use when executing instructions
$INSTPREFIX = "1E-Exchange" # Instruction prefix that you have a license for and corresponding code signing certificate in your local machine cert store
$INSTRUCTIONSET = "DynamicScripting" # Instruction set name where dynamic instructions are created in Tachyon
$MAXTARGETDEVICES = 10 # Maximum number of devices allowed to be targeted by scope; this is a safety-catch to prevent you accidentally sending stuff out to a large device count

If you make changes to this script, you should reload the module using the -force option to ensure that the cached module code is correctly replaced in your PowerShell command instance, as follows:

Copy

import-module .\ps1EToolkit.psd1 -force

Account privileges in the 1E Platform and the 1E PowerShell Toolkit

The 1E PowerShell Toolkit has a number of capabilities, and some of these require additional privileges.

To use the Dynamic Scripting, Dynamic File Copy, Dynamic Activity Record Query, or Dynamic SCALE functionality, the user requires a valid code signing certificate, just as they would if they were using the Tachyon Instruction Management Studio (TIMS) authoring tool. The certificate is placed in the user's local machine certificate store as it would be for TIMS usage. Refer to Code signing certificate.

It is also possible to query 1E Platform Activity Records without requiring a code certificate as an alternative mechanism that uses a dedicated platform instruction. For more information, refer to Querying Activity Records.

To use the remaining functionality, which involves executing and managing platform instructions and instruction sets, the account must be able to perform some or all of the below functions , depending on the activity they are invoking.

Upload instructions and assign them to an instruction set.
Create instruction sets.
Execute instructions.
Cancel instructions.

At the time of writing, Least Privilege testing has not been conducted, so for preliminary evaluation, it is recommended that you use a privileged platform account with global administrator rights.

Code signing certificate

If you wish to use Dynamic Scripting, Dynamic Activity Records Query, or Dynamic SCALE, you will require the following to sign 1E Platform instructions.

You do not require these to use the remaining functionality in the Toolkit.

Requirement	Description
Updated platform license	A valid 1E Platform license that includes an instruction prefix that you will use when creating dynamic instructions. For more information, refer to Prefixes, code signing certificates and licensing. The PowerShell module file assumes an instruction prefix of 1E-Exchange for the code signing certificate. To learn how to change the prefix to match your license, refer to Script customization. For details of a cmdlet that allows the prefix to be dynamically overridden, refer to Instruction XML management cmdlets.
Code signing certificate	A valid code signing certificate that has a trust chain that can be validated on the device on which you are running PowerShell, as well as the platform server and its associated infrastructure and devices. To sign instructions, you must have copied the code signing certificate to the local machine personal certificate store on the device from which you are running PowerShell. If you intend to run PowerShell from a non-elevated command prompt under your platform account context, you may need to go into the Certificate Manager utility (certlm.msc) and set the certificate private key permissions to allow your account to access the private key. This will remove the need to elevate during the code signing phase.

Requirement

Description

Updated platform license

A valid 1E Platform license that includes an instruction prefix that you will use when creating dynamic instructions. For more information, refer to Prefixes, code signing certificates and licensing.

The PowerShell module file assumes an instruction prefix of 1E-Exchange for the code signing certificate. To learn how to change the prefix to match your license, refer to Script customization.

For details of a cmdlet that allows the prefix to be dynamically overridden, refer to Instruction XML management cmdlets.

Code signing certificate

A valid code signing certificate that has a trust chain that can be validated on the device on which you are running PowerShell, as well as the platform server and its associated infrastructure and devices.

To sign instructions, you must have copied the code signing certificate to the local machine personal certificate store on the device from which you are running PowerShell.

If you intend to run PowerShell from a non-elevated command prompt under your platform account context, you may need to go into the Certificate Manager utility (certlm.msc) and set the certificate private key permissions to allow your account to access the private key. This will remove the need to elevate during the code signing phase.

PowerShell execution policy

Before you can use the PowerShell Toolkit, you must ensure that your local PowerShell execution policy settings allow scripts to be executed. At the time of writing, the Toolkit files are not digitally signed, so you need to set a PowerShell policy that allows unsigned scripts to be executed. You will normally only need to do this once on a specific device.

You use the set-executionpolicy cmdlet to define a PowerShell policy. Note that if you choose to use the RemoteSigned execution policy, then you must ensure that the PowerShell Toolkit core files (ps1EToolkit.psd1 and ps1EToolkit.psm1) are not tagged with an external trust zone alternate data stream. This is a mechanism that Windows uses to tag files which are downloaded from an external source such as the internet. Files which contain this alternate data stream are checked to ensure that the trust zone associated with the stream contents is appropriate. Files whose trust zone lies outside the local internet will be blocked from executing if the PowerShell execution policy specifies RemoteSigned.

To remove a trust zone alternate data stream, you can use the standard File Explorer UI and select Unblock from the File Properties screen. There are also PowerShell cmdlets to manage ADS content. To detect if a file is tagged with an alternate data stream, you can use the dir /r command from the command prompt.

For more information on alternate data streams, see this Netwrix blog post.

When you are using the PowerShell Toolkit to execute platform instructions that run PowerShell scripts on remote devices, the device execution policy is managed by the 1E Platform. The requirements discussed here apply only to the device on which you are executing the Toolkit cmdlets, not any remote devices managed by the platform that you may communicate with while using the Toolkit. You will not have to change the PowerShell policy on these devices. The 1E Platform can manage this for you automatically.

Signing PowerShell scripts

You may be able to sign PowerShell scripts using the same code signing certificate used to sign platform instructions. Then to use the script, the certificate's public key must exist in the Trusted Publishers store.