ScriptRunner PowerShell Modul

Cmdlet Pflichtparameter Beschreibung
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.

 

Einstellung https

Um ScriptRunner auf https umzustellen, müssen Sie folgende Einstellungen vornehmen:

  • Bereitstellen von Zertifikaten
  • Umstellung Web Server
  • Umstellung ScriptRunner Server
  • Anpassen der ScriptRunner Web Apps Konfiguration
  • Optional: Anpassen des ScriptRunner ISE Add-Ons und Team Apps Konfiguration
  • Optional: Anpassen von Browsereinstellungen

Hinweis: Die Umstellung auf https muss sowohl auf dem ScriptRunner Server, dem Web Server als auch auf den Team Apps erfolgen, ein Mischbetrieb von http und https ist nicht möglich. Der Parallelbetrieb von http und https ist mit spezifischen Einstellungen nur für notwendige Ausnahmefälle einstellbar.

Für die Einrichtung von https auf ScriptRunner Server und Web Server benötigen Sie ein gültiges Zertifikat. Dieses erstellen Sie in der Zertifikats-Infrastruktur.

Web Server

Öffnen Sie die Microsoft Management Console (MMC) und laden das Modul für die Zertifikatsverwaltung. Importieren Sie das Zertifikat bzw. die Kette von Zertifikaten in den Personal Store des Lokalen Computers.

Zertifikate

Personal Store des lokalen Computers

Nachdem Sie das Zertifikat erfolgreich importiert haben, können Sie die Bindings im Web Server konfigurieren. Öffnen Sie dazu den IIS-Manager und wählen die Webseite aus, in welche die ScriptRunner Web Apps installiert worden sind. Öffnen Sie die Bindings-Konfiguration und erstellen Sie ein https-Binding mit der Zuweisung des importierten Zertifikats.

Https Zertifikat

Konfiguration des https Zertifikats

Hinweis: Für das Laden der ScriptRunner Web Apps wird keine Authentifizierung benötigt. Aus diesem Grund sollte die Einstellung für die Authentifizierung den anonymen Zugriff auf die Webseite erlauben. Die Benutzerauthentifizierung und Rollenzuweisung erfolgt am ScriptRunner Server.

Web Apps

Um ScriptRunner im Nachgang auf https umzustellen, muss die uri.js in mehreren Verzeichnissen angepasst werden. Hierzu gehen Sie in $env:ProgramFiles\ScriptRunner\WebApps und editieren die jeweilige uri.js in den Unterverzeichnissen:

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

Dazu öffnen Sie sie die uri.js mit editieren und passen die letzte Zeile folgendermaßen an:

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

Hinweis: Der Port 8091 richtet sich nach den Einstellungen bei der Installation des ScriptRunner Servers.

Nach der Editierung der uri.js muss der Web Server neugestartet werden. Hierzu führen Sie den Befehl iisreset.exe in der PowerShell aus.

Danach muss der ScriptRunner Service Endpoint ebenfalls auf https umgestellt werden, hierzu öffnen Sie die PowerShell als Administrator und geben folgende Befehle ein:

Get-ChildItem Cert:\LocalMachine\My

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

Um die Umstellung zu prüfen, geben Sie den Befehl Get-AsrUri in der PowerShell ein und führen diese aus.

Hinweis: Vergessen Sie nicht, ebenfalls in der Browser-Adressleiste https anzugeben.

Team Apps und ISE Add-On

Für die Umstellung der Team Apps bzw. des PowerShell ISE Add-Ons führen Sie das Team Apps Setup erneut aus und folgen den Anweisungen. Um die Team Apps auf https umzustellen, aktivieren Sie auf der Seite ScriptRunner Service Endpoint die Option use SSL (https).

Team Apps Konfiguration

Https Konfiguration der Team Apps

Nach Fertigstellung der Installation können Sie die jeweilige Team App starten. Das ScriptRunner ISE Add-On bzw. die entsprechende Team App verbindet sich automatisch mit dem ScriptRunner Service Endpoint.

AzureAD Logon

Um den Zugriff auf das Azure Active Directory (AzureAD) für Anwendungen zu ermöglichen, definiert die Microsoft-Identitätsplattform das Konzept der App-Registrierungen und Service-Principals. Die Registrierung einer Anwendung in AzureAD stellt eine Vertrauensstellung zwischen der Anwendung und AzureAD her, so dass die Anwendung z. B. den Authentifizierungs- und Autorisierungsentscheidungen der Microsoft-Identitätsplattform für Benutzer nach der AzureAD-Anmeldung vertrauen kann. Wie bei einem Service-Konto können Sie mit einer App-Registrierung einer Applikation Zugang zu Ihrem AzureAD-Tenant gewähren, auch wenn Sie die Multi-Faktor-Authentifizierung (MFA) zum interaktiven Login bei AzureAD verwenden.
Die Integration von ScriptRunner in AzureAD funktioniert durch zwei App-Registrierungen, eine für die Benutzeranmeldung aus den ScriptRunner Web Apps (neu: ScriptRunner Portal) und eine für den AzureAD Lesezugriff für den ScriptRunner Service.
Der gesamte Prozess der Integration von ScriptRunner mit AzureAD für die Benutzeranmeldung erfolgt in drei Schritten:

  • In ScriptRunner: Zugang für AzureAD-Benutzer vorbereiten
  • In AzureAD: Konfiguration von App-Registrierungen für ScriptRunner
  • In ScriptRunner: ScriptRunner für die AzureAD-Anmeldung einrichten

Nach Abschluss dieser drei Schritte können Benutzer sich von den ScriptRunner WebApps aus bei AzureAD anmelden.

Achtung! Eine Mischung von Logon mit AzureAD und AD-Benutzerkonten ist nicht möglich, jedoch können beide Directories synchronisiert sein. Sie müssen sich in diesem Fall für eine der beiden Anmeldemöglichkeiten für Benutzer entscheiden.

Voraussetzungen

  • Ein AzureAD-Tenant und ein administratives Benutzerkonto (empfohlen: Global Admin) für diesen Tenant
  • Ein Zertifikat in Cert://LocalMachine/My auf dem ScriptRunner-Host, das für den AzureAD-Zugriff verwendet wird (SSL-Zertifikat oder self-signed Zertifikat)
  • Sicherheitsgruppen im AzureAD, für zukünftige Benutzerrollen
  • Installierte PowerShell Module auf dem ScriptRunner Server:
    – AzureAD
    – Az
  • Aktivierte TLS Version 1.2

Vorbereitung: Zugang für AzureAD-Benutzer

/ScriptRunner

Bevor Sie Änderungen für die AzureAD-Anmeldung in ScriptRunner vornehmen, stellen Sie sicher, dass der eingebaute „Initial Admin Access for Azure“ aktiviert ist.
Dadurch kann jeder AzureAD-Benutzer, zunächst auch von der Admin-App aus auf ScriptRunner zugreifen. Als letztes muss AzureAD Zugang auf die ScriptRunner Admins beschränkt werden.

Aktivierung/Deaktivierung Azure Initial Admin Access

Einrichtung

/App Registrierung

ScriptRunner bietet eine automatisierte Variante zum Einrichten der AzureAD-Integration mit dem Cmdlet Register-AsrAzureADApp. Das Cmdlet kann automatisch die erforderlichen App-Registrierungen in AzureAD und die entsprechenden ScriptRunner-Konfigurationen erstellen.

Hinweis: Der folgende Befehl erfordert das Modul AzureAD (mindestens Version 2.0.2).

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

Geben Sie folgendes Cmdlet ein, um die automatische Installation zu starten.

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

Hinweis: Stellen Sie sicher, dass die SSL-Portbindung an Ihrem WebServer (z.B. IIS) auch für den https-Port 443 konfiguriert ist, auf dem die ScriptRunner Web Apps gehostet werden.
(Der im Cmdlet „register“ verwendete Port wird von der ScriptRunner Service-WebAPI verwendet, z. B. 8092)

Konfiguration der AccessToken-Version

ScriptRunner arbeitet mit der Microsoft Authentication Library (MSAL) und lässt sich in den Endpunkt der Microsoft Identitätsplattform (v2.0) integrieren und akzeptiert die entsprechenden v2.0-Token.

Akzeptierung des Access Tokens

Hinweis: Ändern Sie das Manifest im Parameter accesTokenAcceptedVersion von ’null‘ auf den ‚2‘. („accesTokenAcceptedVersion“: 2,)

Ändern Sie den Typ der Reply-URLs, wie im folgenden Bild.

Anpassung des Manifests: SPA

Hinweis: SPA = Single Page Application

Zugang zulassen

Für den Zugriff von Benutzern auf die Anwendung ist die Zustimmung eines Admins erforderlich. Diese kann bei Bedarf allen Benutzern im Unternehmen erteilt werden. Um die Admin-Zustimmung zu erteilen, öffnen Sie das ScriptRunner-Portal und melden Sie sich als Admin über AzureAD an. Nach einem erfolgreichen Login werden Sie aufgefordert, der Anwendung zuzustimmen.

Zustimmung der Anwendung

Auf Produktiv stellen

Abschließend konfigurieren Sie den Benutzerzugriff in der ScriptRunner Admin App für AzureAD-Benutzer, so, wie es für Windows-Domänenbenutzer getan wird.
Dazu fügen Sie die Berechtigungen für AzureAD-Benutzer entsprechend Ihren Anforderungen hinzu und definieren entsprechende Ansprüche für einzelne AzureAD-Benutzer und/oder AzureAD-Sicherheitsgruppen.

  1. Hinzufügen einer neuen Anspruchseinstellung zur Berechtigung „ScriptRunner Admins“ (+)
  2. Display name: Vergeben Sie einen Anzeigenamen; My Azure Group
  3. Authorization Method: Wählen Sie Azure AD
  4. Target: Wählen Sie Azure AD Home Tenant
  5. Geben Sie den Namen Ihrer ScriptRunner Admin-Sicherheitsgruppe in Ihrem AzureAD ein, die Sie im vorherigen Schritt erstellt haben
    • klicken Sie auf Search und wählen Sie das entsprechende Element aus.

ScriptRunner wählt automatisch den erforderlichen Claim Type und Claim Value aus.

Berechtigungsgruppe definieren

Hinweis: Deaktivieren Sie den generischen „Azure Initial Admin Access“-Eintrag.

Theming

Mit dem ScriptRunner Theming Feature sind Sie in der Lage, das Erscheinungsbild der Web Apps Admin, Delegate und SelfService an das Corporate Design Ihrer Organisation anzupassen.

Die Darstellung betrifft folgende Komponenten:

  • Logo der Top-Bar
  • Farbe der Top-Bar

Hinweis: Eine Anpassung der Team Apps ist nicht möglich.

Theming

Angepasstes Design in der Admin Web App

Führen Sie folgende Schritte aus, um die Web Apps anzupassen:

  1. Öffnen Sie das jeweilige Verzeichnis der Web App. Wird der IIS mit der Standardinstallation verwendet, befinden sich diese in:
    $env:ProgramFiles\ScriptRunner\WebApps\AdminApp\custom
    $env:ProgramFiles\ScriptRunner\WebApps\DelegateApp\custom
    $env:ProgramFiles\ScriptRunner\WebApps\SelfServiceApp\custom
    Hinweis: Einstellungen in diesen Verzeichnissen bleiben bei zukünftigen Updates erhalten.
  2. Speichern Sie zwei Bilddateien im PNG-Format im jeweiligen Verzeichnis:
    – Logo: als „custom_headerlogo.png“ mit max. 30px Höhe
    – Startbildschrim: als „custom_splashscreen.png“ mit max. 530px Breite

    Pfad

    Dateipfad der Bilder

  3. Editieren Sie die Datei customstyle.css wie im nachfolgenden Bild. Achten Sie besonders auf alle Kommentarzeichen (/* , */). Tragen Sie den Farbwert für den Hintergrund als Name, z. B. green oder Hexwert z. B. #a1cc1f, ein.

    customstyle.css

    Angepasste customstyle.css

  4. Starten Sie die den Web Server durch, führen Sie dazu den Befehl iisreset.exe in der PowerShell aus.

Die Web Apps sind sind jetzt im firmeneigenen Corporate Design verfügbar.

Firewall und Virenscanner

Für die ordnungsmäßige Funktionsweise von ScriptRunner empfehlen wir folgende Einstellungen in der Firewall bzw. Antivirusprogramm vorzunehmen.

Firewall

Nehmen Sie die folgende Portfreigabe an Ihrer Firewall vor:

  • 80 für http
  • 443 für https
  • 5985 / 5986 für PS Remoting (WSMan)
  • 8091 genutzt von ScriptRunner
  • Zusätzliche Ports, abhängig von 3rd Party PowerShell Modulen

Hinweis: Mehr Informationen zu unseren Systemvoraussetzungen finden Sie hier.

Antivirusprogramm

  • Stellen Sie sicher, dass der ScriptRunner Service nicht blockiert wird.
  • Legen Sie eine Ausnahme für den Prozess SRXPSHost.exe an
  • Geben Sie den Ordner <$env:\ProgramFiles\ScriptRunner\Service\Bin> frei
  • Geben Sie den Ordner <$env:\ProgramData\ScriptRunner\Service\Local\Engines> frei

Hinweise und Empfehlungen

  • Achten Sie darauf, dass OCSP Requests nicht blockiert werden.
  • Erteilen Sie keine bzw. sehr begrenzte Freigabe für das ScriptRunner Repository.
  • Entwickeln und Testen Sie Scripte mit PowerShell ISE, Visual Studio Code, Visual Studio oder anderen Editoren.
    Hinweis: Mehr Informationen zum Thema Script Entwicklung und Versionskontrolle finden sie hier.
  • Nutzen Sie innerhalb der Scripte, die über ScriptRunner ausgeführt werden, die Systemvariablen aus dem ScriptRunner PowerShell Modul.
    Hinweis: Mehr Informationen zu den Systemvariablen finden Sie in unserer Knowledge Base.
Änderung vorschlagen