Configuring Trusted Agent with PowerShell

role administrators minimum version 2024 2 you can configure an agent to automate specific tasks or workflows by executing external powershell scripts using powershell script an agent can receive and process requests to execute prerequisites a self signed certificate is required during the configuration procedure the certificate is required to sign the powershell script so it can be executed securely ensure that you have completed the following prerequisites before you configure trusted agent for powershell to validate the self signed certificate, you will need a powershell script ( ps1) file, and locate this file on the system you are working on, taking note of the file path create a self signed certificate self signed certificate is required for signing the powershell script open windows powershell ise, and then enter the following code in the script pane (you need to provide a name for the certificate) #certificate name should be provided $certificatename = "\<name of certificate>" \#create a self signed ssl certificate $certificate = new selfsignedcertificate certstorelocation cert \currentuser\my subject "cn=$certificatename" keyspec signature type codesigningcert write host "certificate thumbprint " $certificate thumbprint run the code this creates a code signing certificate in your personal\certificates folder in windows certificate manager open the windows certificate manager console (search "manage user certificates" to locate this app), and locate the certificate file in the personal\certificares folder copy the certificate file to the trusted root certification authorities\certificates folder copy the certificate thumbprint a select the certificate file in trusted root certification authorities\certificates b right click, select open , and then select the details tab c scroll down to find the thumbprint entry, select it, and then copy it from the text field in windows powershell ise, run the following script, entering the thumbprint you copied in the previous step, and the file path to the powershell script ( ps1) file you created as mentioned in the note under "prerequisites" this verifies and signs the code signing certificate in the trusted root certification authorities\certificates folder $thumbprint = "\<enter the thumbprint you copied>" $scriptpath = "\<enter the file path to the powershell script>" \#get the certificate from cert store$codesigncert = get childitem path cert \currentuser\my | where object {$ thumbprint eq $thumbprint} \#sign the ps1 fileset authenticodesignature filepath $scriptpath certificate $codesigncert export the self signed certificate in windows certificate manager, select the certificate you copied to the trusted root certification authorities\certificates folder right click and select all tasks > export the export wizard opens click next , select no, do not export the private key , and then click next again select der encoded binary x 509 ( cer) , and then click next enter a file name, click browse and navigate to the folder you want to save in, and then click save click next , check the settings are as expected, and then click finish configure a script policy and add a powershell execution follow the procedures below to add a script only connection, and then add a new powershell execution configure a script policy once you have completed the prerequisites and have a validated self signed certificate, add a new script only policy log in to as an open the configuration console and click extend > integration tools > trusted agent connection click new trusted agent connection to open the trusted agent connections form the new trusted agent connection button is enabled only at the first use enter the connection settings in the configuration section of the trusted agent for connections form field description setting name a unique name for this script policy policy type select script when this option is selected, the update validation certificate section is displayed upload validation certificate upload the self signed certificate you created earlier for prerequisites docid\ njlu9ljfcpi3urigwiglq only cer file type is accepted click select a file , and then navigate to the folder where you saved the self signed certificate, select the file, and then click open click push policy settings add a powershell script you must configure and push a script policy before you can add a powershell execution open the configuration console and click extend > integration tools > trusted agent connection click new powershell execution to open the new powershell execution form enter the configuration settings in the configuration section of the form field description setting name a unique name for this powershell execution trusted agent select the script policy upload signed powershell click select a file and upload the signed powershell script file for the agent only ps1 file type is accepted if you attempt to upload a powershell script that is not signed, a fail message is displayed when you attempt to save the configuration click save upgrade to a hybrid policy you can upgrade an existing ldap policy to hybrid with both powershell and ldap features when you update an ldap policy to hybrid, you cannot revert the policy back to ldap only upgrade to hybrid before starting this procedure, you need to complete the procedures as described in prerequisites docid\ njlu9ljfcpi3urigwiglq above to provide a self signed certificate for the hybrid configuration from the configuration console, click extend > integration tools > trusted agent connection select the ldap policy to open the trusted agent connections form click the policy type drop down and select hybrid click select a file , and then navigate to the folder where you saved the self signed certificate, select the file, and then click open click update policy settings add a powershell script add the powershell script you want to execute click extend > integration tools > trusted agent connection click new powershell execution to open the new powershell execution form enter the configuration settings in the configuration section of the form field description setting name a unique name for this powershell execution trusted agent select the script policy upload signed powershell click select a file and upload the signed powershell script file for the agent only ps1 file type is accepted if you attempt to upload a powershell script that is not signed, a failure message is displayed when you attempt to save the configuration click save create a new hybrid policy you can create a new hybrid policy with both powershell and ldap features before starting this procedure, you need to complete the procedures as described in prerequisites docid\ njlu9ljfcpi3urigwiglq above to provide a self signed certificate for the hybrid configuration create a hybrid policy this procedure must be completed prior to installing trusted agent as described in install trusted agent docid\ a0haynshu5n26tgcudpss also note that in the current version of , you can add only one trusted agent connection in the configuration console, select extend > integration tools > trusted agent connections the trusted agent connections form is displayed you configure a new connection or edit an existing connection using this form click new trusted agent connection to open the trusted agent connections form enter the connection settings in the configuration section of the trusted agent for connections form field description setting name a unique name for this ldap server connection policy type select hybrid when this option is selected, the update validation certificate section is displayed upload validation certificate upload the self signed certificate you created earlier for prerequisites docid\ njlu9ljfcpi3urigwiglq only cer file type is accepted click select a file , and then navigate to the folder where you saved the self signed certificate, select the file, and then click open server the ldap domain controller host ip address base dn optional the distinguished name for the ldap object in the ldap server this value is not case sensitive user name if the server requires authentication, enter the ldap domain server name password if the server requires authentication, enter the ldap domain server password encryption method select an encryption method no encryption use ssl encryption (ldaps\ //) use starttls extension authentication type select an authentication type for no encryption method, select ntlm for ssl or tls method, select simple (basic) authentication api key optional the signalr api key required to enable external authentication the signalr api key is required if you want to enable users to login externally, if you do not want to enable external authentication this key is not required for information on signalr, see https //learn microsoft com/en us/aspnet/signalr/overview/getting started/introduction to signalr https //learn microsoft com/en us/aspnet/signalr/overview/getting started/introduction to signalr to generate the api key, see step 4 below paste the generated api key into this field when the key is provided, and the ldap settings are pushed successfully, the enable authentication switch is displayed this switch can be toggled on after the trusted agent is installed if you toggle the switch on before the trusted agent is installed a warning is displayed refer to enable external authentication docid\ wfpurw9ip9cetalczxuql optional generate a signalr api key to enable external authentication this step is only required if you want to enable external authentication for information on signalr, see https //learn microsoft com/en us/aspnet/signalr/overview/getting started/introduction to signalr https //learn microsoft com/en us/aspnet/signalr/overview/getting started/introduction to signalr a in the configuration console, select security controls > api keys b in the api keys workspace, select add key group c in the name field, enter signalr, and then enter a brief description in the description field d click save key group e select the signalr group in the key groups list f in the api keys pane, select add api key g select the activated checkbox if not already selected h enter a description, on behalf of, and role information if required i click save key j copy the generated api key identifier to the clipboard k return to the trusted agent for ldap connections form, and then paste the key into the api key field click push policy settings while the ldap settings for the trusted agent are being processed, the status is displayed as pending the push policy settings button changes to update policy settings , and is disabled while the settings are being processed the settings push can take up to 20 minutes to complete click refresh to check if the push has completed when completed successfully, the status is displayed as success a pop up message is also displayed occasionally the status may revert to pending if this happens, push the ldap settings again by clicking update policy settings , and then click refresh the status changes to success if the push fails, a failed pop up message is displayed if a failed push occurs, check your settings are correct, and then push the settings again if the push still fails, refresh the page in the browser, and push the settings again when processing is complete, an enrollment key, comprising of the tenant id and activation key, is displayed in the enrollment key field under the download url for installer (windows) section, click download to download the installer files copy the ivanticloudagent exe and ivanticloudagent exe options files to the server on the private network where trusted agent is to be installed when completed successfully, proceed to installing the trusted agent before continuing with the remaining procedures in this topic, refer to install trusted agent docid\ a0haynshu5n26tgcudpss add a powershell script to add a powershell execution script, refer to add a powershell script docid\ njlu9ljfcpi3urigwiglq complete the procedures to enable and verify the trusted agent connect trusted agent to the directory server and test the connection docid\ wfpurw9ip9cetalczxuql configure root nodes, save and synchronize directory information and enable external authentication docid\ wfpurw9ip9cetalczxuql check the ldap import log, verify employee import and external authentication docid\ wfpurw9ip9cetalczxuql synchronizing existing ldap settings for trusted agent docid\ wfpurw9ip9cetalczxuql invoke a powershell operation with trusted agent invoke an agent that executes with powershell script to update a business object log in to as an from the service desk console, open the incident workspace open an incident, click more , and select edit actions create a quick action using by default, start block is selected enter the settings details for the mandatory fields name , description , enter category , publish to , and ui options in the manually enter "trusted agent" or "trustedagent" (the white space is not required for function) if the trusted agent category is not present in the enter category option drag the run program from the common actions to the block enter a unique name in the block label field select the powershell script in the connection drop down in the arguments field specify the argument that needs to be parsed through the powershell script declare arguments, for example declare a 10, b 5 variables you can also declare a variable and expression, for example, a 10, useremail $(primaryemail), where useremail is a parameter in the script, and $(primaryemail) is a field in the business object select the output field to verify if the powershell request was successfully submitted link the start block to the run program block and click save go back to the page, click more > trustedagent , and select the action you created now the agent will get triggered and update the associated incident as per the powershell script actions verify execution to verify the execution of the agent from the configuration console click extend > integration tools > trusted agent monitoring in the operational logs , select a powershell executed operation and verify the log entry for the associated operation the log entry shows whether the script executed successfully with the expected result creating a workflow for powershell script execution with trusted agent select a business object and create a workflow docid\ p4kb1hcf81wnxmoqhbcjs ensure the run program quick action is created and selected in the run program block properties set the workflow configuration before saving it in the respective business object workspace, select a record, and trigger the workflow once the workflow is executed, refresh the business object to view the powershell execution request status