ScriptRunner PowerShell Module

Cmdlet Required Parameter Description
Add-AsrCorsOrigin Origin ScriptRunner will by default accept Web App requests from any origin.

To restrict the accepted origins, add the allowed origins here, i.e. the URI of your web server hosting the Delegate / Admin Web App.

Check the Windows Application Eventlog for ScriptRunner CORS warnings, which list a rejected origin.

Restart of ScriptRuner Service is required.

Add-AsrPsModule Modules The ScriptRunner Service can provide module functions to directly create Actions, without requiring a script.

Changes applied here will affect all ScriptRunner users working with this ScriptRunner installtion.

Restart of ScriptRuner Service is required.

Disable-AsrLicensedUser ExactLicensedUserString Disable a licensed user, freeing the user license for someone else. Caution: There is no way to re-enable a disabled licensed user!
Enable-AsrLicensedUser ActivationKey

ExactLicensedUserString

Reactivate a previously disabled user for ScriptRunner; this reserves a user license for this exact name!
Get-AsrCorsOrigin   ScriptRunner will by default accept Web App requests from any origin.

To restrict the accepted origins, add the allowed origins here, i.e. the URI of your web server hosting the Delegate / Admin Web App.

Check the Windows Application Eventlog for ScriptRunner CORS warnings, which list a rejected origin.

Changes of the origins require a restart of the ScriptRunner Service to take effect

Get-AsrEmailInboundConnector   Get the current settings of the ScriptRunner Email Inbound Connector.
Get-AsrEMailNotificationConnector   Get the current settings of the ScriptRunner Email Notification Connector.
Get-AsrLicense   Get the current license status of ScriptRunner.
Get-AsrLicensedUser   Lists all users who are a registered user of the ScriptRunner Service.
Get-AsrLicensedUserEx   Not supported!
Get-AsrPasswordServerConnector   Get the current settings of the ScriptRunner Password Server Connector.
Get-AsrPsModule   The ScriptRunner Service can provide module functions to directly create Actions, without requiring a script.

Settings applied here will affect all ScriptRunner users working with this ScriptRunner installtion.

Restart of ScriptRuner Service is required.

Get-AsrService   Get the ScriptRunner service.
Get-AsrSettings   Writes the current global ScriptRunner settings to the console.
Get-AsrSqlConnector   If ScriptRunner SQL-DB Connector is licensed and configured, returns the configured connection string.

Specify the database credentials in the ScriptRunner Admin App on the Global Settings window to avoid cleartext passwords in the connection string.

Restart of ScriptRuner Service is required.

Get-AsrSTSOptions   Get the current STS pipeline configuration options for the ScriptRunner Service.

If enabled, ScriptRunner will open a second REST pipeline, on a second IP port, intended for token based authentication (Windows Integrated or AD FS authentication).

Note that this pipeline will use HTTPS and therefore requires an SSL certificate!

Get-AsrUri   Get the URI of the ScriptRunner OData Service that is used by the ScriptRunner Apps.
Get-AsrVersion   Get the version number of the installed ScriptRunner Service.
Get-AsrWinEvent   Get the ScriptRunner events from the Windows Event Log.
Initialize-AsrLicense ActivationKey

Company

Email

Online Activation: Register your ScriptRunner license online with a License Server in the Internet.

The user performing this should have Internet access with a browser window.

Offline Activation: If your infrastructure is completely offline, use the UnlockKey parameter to enter the Unlock Key you received with your activation key.

Register-AsrAzureADApp   Registering ScriptRunner Server and ScriptRunner Portal in Azure AD to use Azure Queries and to switch user login to Azure AD accounts
Register-AsrLicensedUser ExactLicensedUserString Manually register a user for ScriptRunner; this reserves a user license for this exact string!
Remove-AsrCorsOrigin   ScriptRunner will by default accept Web App requests from any origin.

To restrict the accepted origins, add the allowed origins here, i.e., the URI of your web server hosting the Delegate / Admin Web App.

Check the Windows Application Eventlog for ScriptRunner CORS warnings, which list a rejected origin.

Restart of ScriptRuner Service is required.

Remove-AsrPsModule   The ScriptRunner Service can provide module functions to directly create Actions, without requiring a script.

Changes applied here will affect all ScriptRunner users working with this ScriptRunner installtion.

Restart of ScriptRuner Service is required.

Restart-AsrService   Restarts the ScriptRunner service.
Set-AsrCorsOrigin Origins ScriptRunner will by default accept Web App requests from any origin.

To restrict the accepted origins, add the allowed origins here, i.e., the URI of your web server hosting the Delegate / Admin Web App.

Check the Windows Application Eventlog for ScriptRunner CORS warnings, which list a rejected origin.

Restart of ScriptRuner Service is required.

Set-AsrCyberArkConnector   Set additional ScriptRunner Password Server Connector settings specific to the CyberArk Password Server.
Set-AsrEMailInboundConnector   Change your ScriptRunner Email Inbound Connector settings.
Set-AsrEMailNotificationConnector   Change your ScriptRunner Email Notification Connector settings used for sending email notifications.
Set-AsrPasswordServerConnector   Change your ScriptRunner Password Server Connector settings used for password retrieval.
Set-AsrPsModule Modules The ScriptRunner Service can provide module functions to directly create Actions, without requiring a script.

Settings applied here will affect all ScriptRunner users working with this ScriptRunner installtion.

Restart of ScriptRuner Service is required.

Set-AsrSettings   Configure global settings for the ScriptRunner Service backend.

Settings applied here will affect all ScriptRunner users working with this ScriptRunner installation.

Restart of ScriptRuner Service is required.

Set-AsrSqlConnector   ScriptRunner can optionally log all script execution reports, in detail, into your audit database.

This requires an SQL Server database, with the correct table layout.

You specify here the respective connection string and the user credentials.

Restart of ScriptRuner Service is required.

Set-AsrSTSOptions   Set STS pipeline configuration options for the ScriptRunner Service.

If enabled, ScriptRunner will open a second REST pipeline, on a second IP port, intended for token based authentication (Windows Integrated or AD FS / AAD authentication).

Note that this pipeline will use HTTPS and therefore requires an SSL certificate!

Set-AsrURI   Set the URI of the ScriptRunner OData Service that is used by the ScriptRunner Apps.
Start-AsrService   Starts the ScriptRunner service.
Stop-AsrService   Stops the ScriptRunner Service
Test-AsrEMailInboundConnector ClearPassword Test the current settings of the ScriptRunner Email Inbound Connector, by connecting to the IMAP host and opening the folder to check.

Note that the mailbox password is required to run this test.

Test-AsrEMailNotificatonConnector Recipient Test the current settings of the ScriptRunner Email Notification Connector, by connecting to the SMTP host using these settings.

Note that the mailbox password is required to run this test.

Test-AsrUri   Tests the URI of the ScriptRunner OData Service that is used by the ScriptRunner Apps.
Unregister-AsrAzureADApp   Unregister ScriptRunner Server and ScriptRunner Portal and remove from Azure AD.
Update-AsrLicense Key Update your license of ScriptRunner with a license key, to change certain license features.

The license must have been initialized using Initialize-AsrLicense to allow update license keys.

 

Https Configuration

To switch ScriptRunner to https, you have to configure the following settings:

  • Provide certificates
  • Changeover Web Server
  • Changeover ScriptRunner Server
  • Adjust the ScriptRunner Web Apps configuration
  • Optional: Customize the ScriptRunner ISE Add-On and Team Apps configuration
  • Optional: Adjust browser settings

Note: The conversion to https must be done on the ScriptRunner Server, the Web Server and the Team Apps, mixed operation of http and https is not permitted. Parallel operation of http and https can be set with specific settings only for special cases.

You need a valid certificate to set up https on ScriptRunner Server and Web Server. You’ll need to create this in the certificate infrastructure.

Web Server

Open the Microsoft Management Console (MMC) and load the certificate management module. Import the certificate or chain of certificates into the Personal Store on the local computer.

Certificates

Presonal store of the local computer

After you have successfully imported the certificate, you can configure the bindings in the Web Server. To do this, open the IIS Manager and select the website where the ScriptRunner Web Apps have been installed. Open the Bindings configuration and create an https binding with the assignment of the imported certificate.

Https certificate

Configuration of the https certificate

Note: Authentication is not required to load the ScriptRunner Web Apps. Therefore the authentication setting should allow anonymous access to the web page. User authentication and role assignment is done on the ScriptRunner Server.

Web Apps

To switch ScriptRunner to https, the uri.js has to be adjusted in several directories. To do so, go to $env:ProgramFiles\ScriptRunner\WebApps and edit the uri.js in the subdirectories:

  • \AdminApp\
  • \DelegateApp\
  • \SelfServiceApp\

Edit the uri.js and adjust the last line as follows:

ScriptRunner.baseuri = 'https:// <fqdn-scriptrunner-server>:8091/ScriptRunner/';

Note: Port 8091 is determined by the settings you made during installation of the ScriptRunner Server.

After editing the uri.js, the Web Server must be restarted. Do this by executing the command iisreset.exe in PowerShell.

Afterwards the ScriptRunner Service Endpoint must also be switched to https. Open the PowerShell as administrator and enter the following commands:

Get-ChildItem Cert:\LocalMachine\My

Set-AsrUri -SSLCertThumbprint <Thumbprint> -SSLEnable -Restart

To verify the change, type and run the Get-AsrUri command in PowerShell.

Note: Do not forget to specify https in the browser address bar as well.

Teams Apps and ISE Add-On

To change the Team Apps or the PowerShell ISE Add-On, run the Team Apps Setup again and follow the instructions. To switch the Team Apps to https, enable the use SSL (https) option on the ScriptRunner Service Endpoint page.

Team Apps configuration

Https configuration of the Team Apps

After the installation is completed, you can start the respective Team App. The ScriptRunner ISE Add-On or the corresponding Team App connects automatically to the ScriptRunner Service Endpoint.

AzureAD Logon

To grant access to Azure Active Directory (AzureAD) for applications, Microsoft identity platform defines the concept of App Registrations and Service Principals. Registering an application in AzureAD establishes a trust relationship between the application and AzureAD, so that the application can e.g. trust the authentication and authorization decisions of the Microsoft identity platform for users after AzureAD logon. Like a service account, you can grant an application access to your AzureAD tenant with an App registration, even if you use multi-factor authentication (MFA) to interactively login to AzureAD.

Integration of ScriptRunner into AzureAD works with two App Registrations, one for user logon from the ScriptRunner Web Apps (new: ScriptRunner Portal) and one for AzureAD read access for the ScriptRunner Service.

The process of integrating ScriptRunner with AzureAD for user logon is in three steps

  • In ScriptRunner: Prepare access for AzureAD users
  • In AzureAD: Configuration of app registrations for ScriptRunner
  • In ScriptRunner: Set up ScriptRunner for the AzureAD login

After completing these three steps, users can log on to AzureAD from the ScriptRunner WebApps.

Attention! It is not possible to mix logon with AzureAD and AD user accounts, but both directories can be synchronised. In this case you must choose one of the two logon options for users.

Requirements

  • An AzureAD tenant and an administrative user account (recommended: Global Admin) for this tenant
  • A certificate in Cert://LocalMachine/My on the ScriptRunner host used for AzureAD access (SSL certificate or self-signed certificate)
  • Security groups in AzureAD, for future user roles
  • Installed PowerShell modules on the ScriptRunner server:
    – AzureAD
    – Az
  • Activated TLS Version 1.2

Preparation: Access for AzureAD Users

/ScriptRunner

Before you make changes for the AzureAD login in ScriptRunner, make sure that the built-in “Initial Admin Access for Azure” is activated.
This allows any AzureAD user to access ScriptRunner, initially also from the Admin app. Finally AzureAD access must be restricted to the ScriptRunner Admins.

Activating/Deactivating Azure Initial Admin Access

Setup

/App Registration

ScriptRunner provides an automated way to set up AzureAD integration by using the cmdlet Register-AsrAzureADApp. The cmdlet automatically creates the required app registrations in AzureAD and the corresponding ScriptRunner configurations.

Note: The following command requires the AzureAD module (version 2.0.2 or later).

Install-Module AzureAD -Scope AllUsers #PowerShell Gallery requires TLS 1.2

To start the automatic installation, type the following command

Register-AsrAzureADApp -DnsName <DNSName> -SSLCertThumbprint <Thumbprint> -Port <Port> -TenantID <TenantID> -Verbose

Note: Make sure that the SSL port binding on your web server (such as IIS) is also configured for https port 443 where the ScriptRunner Web Apps are hosted.
(The port used in the register cmdlet is used by the ScriptRunner Service WebAPI, for example, 8092)

Configuring the AccessToken version

ScriptRunner works with the Microsoft Authentication Library (MSAL) and integrates with the Microsoft Identity Platform (v2.0) endpoint to accept the respective v2.0 tokens.

Accepting the Access Token

Note: Change the manifest in the Parameter “accesTokenAcceptedVersion” from ‘null’ to ‘2’. (“accesTokenAcceptedVersion”: 2,)

Change the Reply URL type as shown in the following figure.

Manifest adjustment: SPA

Note: SPA = Single Page Application

Allow access

For users to access the application, the approval of an administrator is required. This can be granted to all users in the company if required. To grant the admin approval, open the ScriptRunner portal and log in as admin via AzureAD. After a successful login you will be asked to approve the application.

Approval of the application

Going live

Finally, configure user access in the ScriptRunner Admin App for AzureAD users as you would for Windows domain users.
To do this, add permissions for AzureAD Users according to your requirements and define appropriate entitlements for individual AzureAD Users and/or AzureAD Security Groups.

  1. Add a new Claim setting to the “ScriptRunner Admins” authorization (+)
  2. Enter a display name, like “AzureAD Admin Access”
  3. Select the “Azure AD” authorization method
  4. Select the “Azure AD Home Tenant” target that contains your tenant settings
  5. Enter (part of) the name of your ScriptRunner Admin security group in your AzureAD, that you have created in the previous step, click “Search”, and select the proper element.
    • click on Search and select the proper element.

ScriptRunner automatically selects the required Claim Typeand Claim Value.

Define authorization group

Note: Disable the generic “Azure Initial Admin Access” entry.

Theming

With the ScriptRunner Theming Feature you are able to customize the appearance of the Web Apps Admin, Delegate and SelfService to the corporate design of your organization.

This affects the following components:

  • Start screen
  • Logo in the top bar
  • Color of the top bar

Note: It is not possible to customize the Team Apps.

Theming

Modified design in the Admin Web App

Follow these steps to customize the Web Apps:

  1. Open the respective directory of the Web App. If the IIS is used with the default installation, they are located in :
    – $env:ProgramFiles\ScriptRunner\WebApps\AdminApp\custom
    – $env:ProgramFiles\ScriptRunner\WebApps\DelegateApp\custom
    – $env:ProgramFiles\ScriptRunner\WebApps\SelfServiceApp\custom
    Note: Settings in these directories will be saved for future updates.
  2. Save two image files in PNG format in the respective directory:
    – Logo: as “custom_headerlogo.png” with max. 30px height
    – Start screen: as “custom_splashscreen.png” with max. 530px width

    Path

    Directory of the images

  3. Edit the file customstyle.css as shown in the following picture. Pay particular attention to all comment characters (/* , */). Enter the color value for the background as name, e.g. green or as hex value e.g. #a1cc1f.

    customstyle.css

    Modified customstyle.css

  4. Start the web server by executing the iisreset.exe command in the PowerShell.

The Web Apps are now available in the Corporate Design of your company.

Firewall and Virus Scanner

To ensure proper functioning of ScriptRunner, we recommend the following settings in your firewall or antivirus program.

Firewall

Perform the following port sharing on your firewall:

  • 80 for http
  • 443 for https
  • 5985 / 5986 for PS Remoting (WSMan)
  • 8091 used by ScriptRunner
  • Additional ports, depending on 3rd Party PowerShell modules

Note: More information about our system requirements can be found here.

Antivirus program

  • Make sure that the ScriptRunner service is not blocked
  • Create an exception for the process SRXPSHost.exe
  • Give access to the folder<$env:ProgramFilesScriptRunnerServiceBin>
  • Give access to the folder<$env:ProgramDataScriptRunnerServiceLocalEngines>

Notes and recommendations

  • Make sure that OCSP requests are not blocked.
  • Grant no or very limited sharing to the ScriptRunner repository.
  • Develop and test scripts using PowerShell ISE, Visual Studio Code, Visual Studio or other editors.
    Note: More information about script development and versions control can be found here.
  • Use the system variables from the ScriptRunner PowerShell module within the scripts executed by ScriptRunner.
    Note: More information about system variables can be found in our Knowledge Base.
Suggest Edit