Creating a Consumer Using Powershell

In this exercise we are going to use Powershell to create a widget that will do one thing in Tachyon - Quarantine a specific device. We will name our consumer QWidget. This could be used in an emergency situation to perform a quarantine of a specific device. This could especially be useful when an administrator leaves an organization and still retains the company laptop.  The former employee's user account can be disabled but what happens if that employee has knowledge of service account passwords?  This is the scenario that QWidget will be used for, that device can be quarantined and when the former employee returns the laptop the quarantine can be removed with Tachyon.  We will write an instruction to do the quarantine action but not require the approval workflow. For security we will lock down this instruction to only be able to be run by our QWidget principal.

Create the Instruction

First we will write the instruction that QWidget will be using to perform the quarantine. The first thing we will need to do is enroll our Code Signing Certificate on the Tachyon server and the workstation we will be using. We will then need to install TIMS on the workstation we will be using (1ETRNW71). If you do not remember how to perform these steps go to the Tachyon Operator course starting at this exercise.

Ex 1 - Tachyon v5.1 - Using - Creating Instructions and Fragments Using TIMS: Configuring TIMS prerequisites

1. Logged in as 1ETRN\Tachyon_Admin1
2. Open TIMS from the shortcut on the desktop (if it is not already open)
3. In the Code Block type in the following

Security.QuarantineDevice();

4. In the Instruction Definition pane Comments field type in QWidget Quarantine
5. In the Description field type in Provides quarantine for one device for QWidget
6. In the InstructionType field change to Action. Since we do not want to use the approval workflow for our instruction, we will toggle that off. Click on Workflow in the ribbon and select No user approval from the drop-down. Click Ok
7. In the Name field type in 1ETRN-QWidgetQuarantine
8. In the ReadablePayload field type in QWidget Quarantine
9. Click on Schema. Click the + sign to add a column. Leave the Column Name, Data Type and Length to defaults. Click Ok.
10. In the ribbon click Code Signing and choose always sign then select the Code Signing certificate that we imported. Click OK
11. Save the file as c:\tools\1ETRN-QWidgetQuarantine.xml - click Ok on the message about not running the instruction before saving. Since we are running TIMS in user context quarantine produces an error when invoked from TIMS.
12. Minimize TIMS. Open the ConfigMgr Content Source shortcut on the desktop and copy the Instruction from c:\tools to that location. We will then be able to access the file from the Tachyon Server to upload.

Upload Into Tachyon and Move to Instruction Set

We could do all of the next steps on Postman or with our powershell that we will be writing for QWidget but for ease of learning we will do these manually.

13. Log into 1ETRNAP as 1ETRN\AppInstaller this is an account that is an Instruction Set Administrator
14. Open the Config Mgr Content Source shortcut from the Desktop and copy 1ETRN-QWidgetQuarantine.xml to c:\temp
15. Open Chrome and navigate to the Settings Application
16. Upload the Instruction and move it to an Instruction Set called QWidget

Create the Consumer

17. Still logged into Chrome in the Settings application navigate to Configuration - Consumers and click on Add
18. In the Name field type in QWidget
19. In the Maximum simultaneous instructions type in 5
This is how we can limit the number of instructions that are run at one time from each consumer. We may have a few Admins that want to use our consumer, so we will allow 5 at each time. This number will be different for each consumer.
The next two fields would be where we configure our web service in order to send all of our responses to our consumer. QWidget will only get a return code for a successful quarantine, so we will not need to offload the responses. If nothing is configured here the responses will be available in the Explorer application.
20. Check the Enabled box
21. Click Add

Create the Account in AD

22. Open Active Directory Users and Computers
23. Create a user called QWidget
24. Set the password to Passw0rd uncheck the box to require password change at next login and Check the box for password never expires

Create the User and Role in Tachyon

25. Back in Chrome in the Settings Application navigate to Permissions - Users and add our QWidget user
26. Navigate to Permissions - Roles and click on Add this will create our custom role for QWidget
27. Name the role QWidget and put in a meaningful description
28. Find the new QWidget role in the list and open it by clicking on the name of the role
29. In the Permissions tab click Add in the far right
30. Choose Add and in the Type field select Instruction Set. In the Name field select QWidget and check Actioner, Approver, Questioner, and Viewer click Add
31. Click the Management Groups tab and Click Add select All Devices. Click Add
32. Click on the Members tab and click Add. Select our QWidget user. Click Add.

Create QWidget

Now we will write the Powershell script that will actually be our Consumer. We will use a Windows Form to display an input box to ask for our Device name.

33. Click on Start - type in Power and select Powershell ISE when the suggestions appear to open the Powershell Integrated Scripting Environment.
34. In the Powershell ISE type the following in your code block

Add-Type -AssemblyName System.Windows.Forms
Add-Type -AssemblyName System.Drawing

This will add the assembly for the Windows Form we will use to display a window in powershell
35. Under those two lines add a blank line and type in the following

$tachyon = "Tachyon.1etrn.local"

This variable will be used to build our URL to make our call to the Consumer API. This variable could also be used to test for someone accidentally entering the name of the tachyon server. We would want to exit the widget if someone tries to quarantine the actual server for an additional layer of security.
36. Add a blank line to the bottom of the code block and enter the following

$form = New-Object System.Windows.Forms.Form
$form.Text = 'QWidget'
$form.Size = New-Object System.Drawing.Size(500,250)
$form.StartPosition = 'CenterScreen'

This block of code determines the size of the window that opens in pixels - enclosed in ( ), the placement on the screen, and the text it displays at the top
37. Click Run at the top. You should see the return in the bottom pane. It won't be very exciting yet until we add some additional code. Ensure that you have no errors.
38. Under those lines add a blank line and type in the following

$OKButton = New-Object System.Windows.Forms.Button
$OKButton.Location = New-Object System.Drawing.Point(150,120)
$OKButton.Size = New-Object System.Drawing.Size(75,23)
$OKButton.Text = 'OK'
$OKButton.DialogResult = [System.Windows.Forms.DialogResult]::OK
$form.AcceptButton = $OKButton
$form.Controls.Add($OKButton)

This bit of code controls the look and placement of our OK button
39. Under the last line of code add a blank line and type in the following

$CancelButton = New-Object System.Windows.Forms.Button
$CancelButton.Location = New-Object System.Drawing.Point(220,120)
$CancelButton.Size = New-Object System.Drawing.Size(75,23)
$CancelButton.Text = 'Cancel'
$CancelButton.DialogResult = [System.Windows.Forms.DialogResult]::Cancel
$form.CancelButton = $CancelButton
$form.Controls.Add($CancelButton)

This bit of code controls the look and placement of our cancel button
40. Click Run ensure there are no errors.
41. Under the last line of code create a blank line and type in the following

$label = New-Object System.Windows.Forms.Label
$label.Location = New-Object System.Drawing.Point(75,20)
$label.Size = New-Object System.Drawing.Size(290,20)
$label.Text = 'Enter the Device Name to Quarantine:'
$form.Controls.Add($label)

This bit of the code controls the size and placement of the text - this is what tells the user what needs to be entered in the box that will be displayed with the next bit of code.
42. Under the last line hit enter to create a blank line and then enter the following

$textBox = New-Object System.Windows.Forms.TextBox
$textBox.Location = New-Object System.Drawing.Point(75,50)
$textBox.Size = New-Object System.Drawing.Size(289,100)
$form.Controls.Add($textBox)

This controls the size and placement of the box the user will enter in the device name
43. Under the last line add a blank space and type in the following

$form.Topmost = $true
$form.Add_Shown({$textBox.Select()})
$result = $form.ShowDialog()

This bit of code makes the window that opens be the window on top of any other open windows
44. Click Run at the top and now you should be able to see our form. Type something in the text box and click OK. Notice nothing in our bottom pane.
45. Add a blank line and enter the following in our code block

if ($result -eq [System.Windows.Forms.DialogResult]::OK)
{
    $x = $textBox.Text
    $xarray = $x.split(" ") 

We are using the powershell spit with no delimeter because Tachyon is expecting an array here and there is a limitation in powershell that a single value cannot be an array.
46. Click Run. Did you get an error? That is because our closing curly brace is lower in our code. Add a closing curly brace and on the next line type in Echo $xarray then click run again.
47. Type something in the box and click Ok. Note the return, our xarray variable is set to what we typed into the box
This starts our IF block when the user selects OK. 
48. Now we will add the rest of our code under the last line of our code block but first delete the closing curly brace and the Echo line that you added for testing.

    $URI = "https://$tachyon/consumer/Instructions/Targeted"
    $headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
	$headers.add("X-Tachyon-Consumer", "QWidget")
	$headers.add("Content-Type","Application/Json")
    $body = @{
				DefinitionId = "216"
				InstructionTtlMinutes = "120"
				ResponseTtlMinutes = "120"
				Devices = $xarray

}
	$json = $body | ConvertTo-Json

    Invoke-WebRequest -URI $URI -Method Post -UseDefaultCredential -Body $json -Headers $headers
   
}

49. In Postman run your request to pull your Instruction Definition IDs and replace 216 in your code block if your QWidget Instruction Definition ID is not 216.
The next lines build our Web Call into Tachyon. The next line is setting our URI for the API endpoint we are going to request to create our action. We then build our two headers (remember those from the Postman exercises). Finally, we are building the Body of our request (this should look familiar from Postman) setting the instruction definition we will use and limiting our coverage to the device we are entering into the form. We then are converting those to a json. The final line is the actual request to the API.
50. Save the file as c:\sources\QWidget.ps1

Your Code Block for QWidget should look like this

Add-Type -AssemblyName System.Windows.Forms
Add-Type -AssemblyName System.Drawing
$tachyon = "Tachyon.1etrn.local"

$form = New-Object System.Windows.Forms.Form
$form.Text = 'QWidget'
$form.Size = New-Object System.Drawing.Size(500,250)
$form.StartPosition = 'CenterScreen'

$OKButton = New-Object System.Windows.Forms.Button
$OKButton.Location = New-Object System.Drawing.Point(150,120)
$OKButton.Size = New-Object System.Drawing.Size(75,23)
$OKButton.Text = 'OK'
$OKButton.DialogResult = [System.Windows.Forms.DialogResult]::OK
$form.AcceptButton = $OKButton
$form.Controls.Add($OKButton)

$CancelButton = New-Object System.Windows.Forms.Button
$CancelButton.Location = New-Object System.Drawing.Point(220,120)
$CancelButton.Size = New-Object System.Drawing.Size(75,23)
$CancelButton.Text = 'Cancel'
$CancelButton.DialogResult = [System.Windows.Forms.DialogResult]::Cancel
$form.CancelButton = $CancelButton
$form.Controls.Add($CancelButton)

$label = New-Object System.Windows.Forms.Label
$label.Location = New-Object System.Drawing.Point(75,20)
$label.Size = New-Object System.Drawing.Size(290,20)
$label.Text = 'Enter the Device Name to Quarantine:'
$form.Controls.Add($label)

$textBox = New-Object System.Windows.Forms.TextBox
$textBox.Location = New-Object System.Drawing.Point(75,50)
$textBox.Size = New-Object System.Drawing.Size(289,100)
$form.Controls.Add($textBox)

$form.Topmost = $true
$form.Add_Shown({$textBox.Select()})
$result = $form.ShowDialog()

if ($result -eq [System.Windows.Forms.DialogResult]::OK)
{
    $x = $textBox.Text
    $xarray = $x.split(" ")

 $URI = "https://$tachyon/consumer/Instructions/targeted"
    $headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
	$headers.add("X-Tachyon-Consumer", "QWidget")
	$headers.add("Content-Type","Application/Json")
    $body = @{
				DefinitionId = "216"
				InstructionTtlMinutes = "120"
				ResponseTtlMinutes = "120"
				Devices = $xarray

}
	$json = $body | ConvertTo-Json

    Invoke-RestMethod -URI $URI -Method Post -UseDefaultCredentials -Body $json -Headers $headers
   
}

Using QWidget

In this exercise we will actually use our new Consumer - QWidget from 1ETRNW102 and Quarantine 1ETRNW101.  We will perform this via the desktop shortcut.  We will also run QWidget from within the Powershell ISE so that you can also see the data that is returned.  Our web form does not display the return details as it is not necessary for the functionality of QWidget.

51. Log into 1ETRNW101 and make sure the device can get to the internet and Ping the Config Mgr Server 1ETRNCM

52. Create a Desktop Shortcut to c:\sources\qwidget.ps1
53. Right click the shortcut and choose Run with Powershell when the command window opens type in Y and hit enter
54. Enter 1ETRNW101.1etrn.local in the box. Click Ok

55. Make sure that you cannot access the internet or the Configuration Manager Server

56. In the powershell ISE, with QWidget still in the code block click the run button.  When QWidget opens type in 1ETRNW73.1etrn.local and click Ok

57. Open the Explorer Application and ask the question Are my devices quarantined?
58. You should see that 1ETRNW101 and 1ETRNW73 are quarantined

59. Issue the action to take 1ETRNW101 out of quarantine
60. Open Live Mail and authenticate with the code in the InBox

61. Open the Explorer Application and Navigate to Notifications and approve the request to remove the device from Quarantine

Lab Summary

In this exercise we learned how to use Powershell to accept some data from a user and then take action on that device in Tachyon. We could easily have taken any other action in Tachyon by using different instructions.

References

Scope Attributes

Defining the scope

Tachyon SDK Documentation