Beginner's Question for using scripts in endpoints

[Nobs]

Product: PowerShell Universal
Version: 5.3.2

Hello everyone, I’m just beginning to understand how Powershell Universal works and I’m looking for an opportunity to ask “beginner” questions. I have created scripts under the automation section and am trying to use these scripts in endpoints. Unfortunately I get the message that these scripts cannot be found. what am I doing wrong or what have I overlooked?
Unfortunately, I couldn’t find anything in the documentation or intranet that could help me

Thank’s a lot

[Jesse.Peden]

To use a script created in the Automation section in an Endpoint, you’d need to do something like:

<# PSU-Internal Account App Token #> $AppToken = '<redacted>'
Connect-PSUServer -AppToken $AppToken -ComputerName 'https://<redacted>'

Invoke-PSUScript -Script 'Folder\Script.ps1'

Edit: As parzog pointed out below, this seems to have a caveat of requiring your PSU installation to be licensed. If yours is licensed, my response is still valid; if it’s not, parzog’s response would be a better fit.

[parzog]

If the script you are writing will be ran deterministically within the endpoint, it may be better to define the script AS the endpoint. This would allow the execution to be triggered by the API call.

To hopefully explain a little bit more - when you are triggering an API call, with normal methods you typically need to authenticate yourself against the system. PSU handles this through app tokens. If your instance is unlicensed, you will not have access to App Tokens, and thus will be unable to proceed in the manner Jesse helpfully provided.

So, you likely will need to leave your endpoint unauthenticated. When the endpoint is not authenticated, it cannot trust that the call it received is authorized to execute the action. As a safety measure, the default setup restricts running those scripts from the system from within an unauthenticated session (such as a barebones API call).

This is very much watering down the specifics, but more has been explained in this forum in other recent places if you are willing to do a bit of reading. If you are licensed, however, then you can use App Tokens and specify your security model accordingly to allow execution of scripts within endpoints.

Hope that helps, and welcome to PSU (and the forums)!

[Jesse.Peden]

I’ve never had an unlicensed instance of PSU, so I wasn’t aware of authentication being a paid-only feature. Good to know.

[parzog]

Yeah! For reference, to my knowledge the sections in the lighter grey (on dark mode) are paid:

Extrapolate this out to the other non-expanded columns as well. No app tokens = no auth!

[Jesse.Peden]

Never noticed since it never applied to our setup.

[Nobs]

Hello guys, thank you very much for the quick response. We have ordered a license but it still stuck within our ordering process, I’m currently experimenting without it. But thank you very much for your tips. My plan was to offer a series of scripts both via the GUI and via endpoints for automation solutions.
So if I understood it correctly then it obviously makes more sense to define the work in the endpoint and to call the endpoint in the script. Then I would have avoided the “permission” problem. Is that correct ?

[Jesse.Peden]

Reverse that (you call a script from within an endpoint), assuming you’re saying that you want to go with the method I provided.

[Nobs]

OK thanks - then I’ll wait for the license and try your suggestion

[TriggerAu]

Welcome @Nobs !

If you havent used it already, and you want to of course, you can get a trial license via Trial | PowerShell Universal - 14 days of unlocked - and be able to test

We did the same sort of testing your talking about here.

For our use cases we have scripts that are used by people via the portal and also used from automation/external events via an endpoint, the endpoint code gets the data that’s posted to it and extracts the parameters of the script to Invoke it, and people can run the same process - as well as us while testing/developing. Theres a bunch of ways to do it in PSU though

EDIT: Oo I could probably share a contrived example too, two secs

[TriggerAu]

For cut down example - with no error checking, etc, etc we do something like this - and ill apologize for typos up front, its early where I am and just brain dumping

And you do want to be careful how long the script takes to run as per the best practices doc

From the external system

#$payloadJson contains json, $headers contains the apptoken
$payloadJson = "{IdentityId = `"Trigger`"}" 

Invoke-RestMethod -Uri "https://psuniveralserver.local/api/disableperson" -Method POST -Body $payloadJson -Headers $headers

Endpoint

# log what we got in the body
Write-Information "Body: $($Body)"
# convert from json
$data = convertfrom-Json -InputObject $Body -Depth 5

#What params do I need for the function
$IdentityId = $data.IdentityId
$invokeParams = @{IdentityId=$IdentityId}

# This calls the script and waits for the result  - you can also add bits here to change what identity the script runs as - in this cae we just continuing with the endpoints auth via integrated
$scriptResponse = Invoke-PSUScript -Name "Identity\Disable-User.ps1" -Parameters $invokeParams -Integrated -Wait -TrustCertificate

#convert the object to JSON for rest consumption
$responseJson = "{Result = `"$($scriptResponse`"}"

return $responseJson

Script

param(
[Parameter(
    Mandatory = $true
)]
[string]
$IdentityId = "DEFAULT/TESTVALUE"

# Using Write Information so it doesnt put this on the pipeline in the results, but will show in the script logs in the PSU server
Write-Information "Starting Disable of User"

## Do all the things with the param
$result = "WooHoo we are done!"

# This can return data objects so when run in PS, or in the portal/apps the results arent JSON encoded here
return $result

[Nobs]

I received the license and implemented your suggestion for testing purposes – it works exactly as I hoped. Thank you for the detailed explanation.

[sacmar]

I wonder if its possible to run a script with the api but have it be interactive ?

[parzog]

I’m not sure what this would look like - API’s are meant not to be interactive. What point at which would the interaction occur?

[sacmar]

I would like to give some users the ability to open a PowerShell terminal, then “connect” to an “environment” and have a startup script with a Read-Host menu to choose which script to start and possibly provide more information using additional Read-Host prompts.

The script would run on PowerShell Universal (PSU), and the user would only select what to run in the environment. Basically, it would work like an app but using a PowerShell console - like a menu for scripts.

It’s easy to do locally, but if some scripts use a connection to Azure, it’s good to avoid installing the certificates on the computer of the user.

Note: “Connect” and “environment” can be replaced by any appropriate terms in PSU that would work. I just used them as general terms.

TLDR :

How it works:

1. Users open a PowerShell terminal
2. Users connect to a PowerShell Universal (PSU) environment
3. A menu appears showing available scripts
4. Users select scripts and provide any required inputs
5. Scripts execute in the PSU environment, not locally

[adam]

You could create a function using the Universal module to list out scripts in a menu. The user could then select the script and you could retrieve the parameters and provide a way to enter the values.

using namespace System.Management.Automation.Host
Import-Module Universal

function Enter-PSUServer {
    $AppToken = '<token>'
    Connect-PSUServer -ComputerName 'http://localhost:5000' -AppToken $AppToken
    
    $MenuItems = Get-PSUScript | ForEach-Object {
        @{
            Script   = $_
            MenuItem = [ChoiceDescription]::new("&$($_.Id) - $($_.Name)", $_.Description)
        }
    }
        
    $options = [ChoiceDescription[]]($MenuItems.MenuItem)

    $result = $host.ui.PromptForChoice("Select script", "Please select a script", $Options, 0)

    $selectedScript = $MenuItems[$result].Script

    $selectedScript.ScriptParameters

}

Enter-PSUServer

Select script
Please select a script
[1] 1 - s.ps1  [2] 2 - Script1.ps1  [3] 3 - Script2.ps1  [?] Help (default is "1"): 1
Id                          : 1
Name                        : Parameter
DisplayName                 : Parameter
Type                        : System.Object
ScriptId                    : 0
DefaultValue                :
Required                    : False
DisplayType                 : String
ValidValues                 :
HelpText                    :
ParameterSet                : Default
ResolvedDefaultValue        :
IValidateSetValuesGenerator :
Using                       :
Dynamic                     : False

You could also look into using terminals somehow.

Terminals | PowerShell Universal

There are cmdlets for controlling those as well.

• Start-PSUTerminalInstance
• Invoke-PSUTerminalCommand

You’d want to be a little careful providing terminals like this since the users could potentially run whatever.

[adam]

Someday, I hope the PowerShell Team\Contributors implement custom remoting protocols.

Archive/Draft/RFC0063-Custom-Remote-Connections.md

Then we could just do:

$Session = New-PSUSession -ComputerName '' -AppToken
Enter-PSSession -Session $Session

And it would be like any other remoting session.

[sacmar]

Damn. your first script seems perfect. I just need to test if it can support read-host but i managed to connect and i see the script. Just need to filter them.

for the Terminal. It would work too but i can’t seem to get the environement to see any startup script. I did put it in the files, Repo and some other places but it just see nothing. Can you tell me exactly where i must put it ? Relative to what ?

thanks again

[parzog]

Plan to implement: Yes with Comments Due: 10/22/2021 hurts my soul. This would be an amazing implementation!!!

[sacmar]

Exception setting “CursorPosition”: “A command that prompts the user failed because the host program or the command type does not support user interaction. Try a host program that supports user interaction, such as the PowerShell Console, and remove prompt-related commands from command types that do not support user interaction.”

Hmm. Yeah maybe this would be better as another forum post. it’s not as simple as i hope.