Azure AD, M365 services such as Exchange Online, Teams and others as well as Azure Cloud are increasingly used in many companies. Besides the basic management of users and services, the use of Azure AD accounts as well as targeted searches using the available graph queries are also significant.
ScriptRunner integrates all these capabilities under one roof and supports IT Pros optimally in IT Infrastructure & Operations Automation.
Let’s start by looking at the basic concept as well as the necessary components and parts of a cloud environment with M365 and Azure and how they work and interact.
The basic concept (fig. 1) of ScriptRunner follows the principle of “separation of powers” for access to systems and services. Users have roles in ScriptRunner and are granted access rights to functions depending on their role.
ScriptRunner Server handles access to central systems and services completely independently of user access. As an automation platform, it executes PowerShell scripts in the necessary and configured rights context. This prevents direct, uncontrolled access to IT systems and cloud services by users, regardless of their role.
Fig. 1: Basic concept of ScriptRunner and the main components
The main components working together are:
Azure AD as IdentityProvider
App Registration for the ScriptRunner Server as well as the configuration of the built-in-target “Azure AD Home Tenant “
App Registration for the ScriptRunner Portal to log in to the ScriptRunner Portal with Azure AD accounts
Registration of Service Principals for managing M365 and Azure Cloud with PowerShell
Use of AAD groups in ScriptRunner roles
Use of Microsoft Graph, Azure Resource Graph, and Azure Data Explorer in Azure Queries
Azure AD as Identity Provider
Every system environment needs what is called an IdentityProvider. The best-known implementation for this is known to every IT Pro: their own Active Directory.
In this context, Active Directory including certificate authorities etc. is a private Identity Provider and provides all resources for the identification of users, devices, systems, services and applications.
In the age of the cloud, “public” identity providers play an increasing role. These are provided by large vendors such as Microsoft, Amazon, Google and others. In addition to these vendors, there are also independent specialty meta-identity providers.
Microsoft’s identity provider for M365 and Azure Cloud is Azure Active Directory (AAD). Simply put, it has the task of identifying users, devices, systems, services and applications and regulating roles, access rights and functions.
As a result, there is no user login and no access to M365 and Azure Cloud services without the AAD. The AAD is therefore a necessary core component for the use and management of Microsoft Cloud services.
Since many companies already operate a private identity provider with their own AD, this can be coupled and synchronized with the AAD. Active Directory Federation Services is most commonly used for this purpose. The advantage: Users can access both internal and cloud services with a synchronized account. In the future, logging in with the AAD account will probably become the norm.
Before ScriptRunner can interact directly with the identity provider AAD, it must be made known to it. Subsequently, the system can be configured so that all users can log in to ScriptRunner Portal with their AAD account. To do this, use the App Registration.
App Registration in Azure AD
Every application and service that should be under the control of AAD must be known to the Identity Provider. For this purpose, AAD provides methods for registration (fig. 2). With the registration, a minimal digital image is created in the AAD for external services or applications such as ScriptRunner, which provides the access regulations for the own AAD tenant or also in multi-AAD tenant operation. The settings also control, among other things, whether the ScriptRunner Portal is directly clickable as an app in the O365 portal or remains hidden.
Fig. 2: The app registration process
The ScriptRunner Service registration makes the ScriptRunner Service known in the AAD, controls connection access by the service to the AAD, authorizes access by the service to the AAD via certificate and allows read access to the AAD by default. Upon registration, the built-in target “Azure AD Home Tenant” in ScriptRunner Server is automatically configured for AAD access.
In addition, AAD accounts and AAD security groups can now be used within ScriptRunner and assigned to application roles in ScriptRunner.
Note: the configuration allows ScriptRunner Server to access AAD information for configuring application roles in ScriptRunner and for Azure queries. This does not include management access to various services and resources via PowerShell!
ScriptRunner Portal registration switches user login from internal AD to the company’s AAD. Users can now log in using only their AAD user account.
Preparations for App Registration
In order to register ScriptRunner in the AAD, they should do some preliminary thinking and work:
Should users continue to log in with their AD account or with their AAD account in the future? If no, they can skip the next two points. Attention: If you are already using Basic Auth on a Web Service Connector, the port for user login via AAD is already reserved.
Create security groups in the AAD analogous to the groups in the AD
Enable the “Azure Initial Admin Access” in ScriptRunner in the role ScriptRunner Main Admin
Install .NET 4.7.2 or higher on ScriptRunner Server
Activate TLS 1.2 on ScriptRunner Server
Install the two PowerShell modulesAzureAD and Az in the latest version on ScriptRunner Server. Be sure to uninstall the AzureADPreview module
Provide at least one certificate for secure connection and certificate-based authentication on ScriptRunner Server
Finally, test the connection from ScriptRunner Server to AAD Endpoint by connecting in PowerShell and displaying the domains.
Register the ScriptRunner App
After you have completed all preparations and checked again, you can make the app registrations for ScriptRunner. For this you need the rights as Global Administrator in AAD.
The AAD login window opens. After the login, a more extensive script processing takes place. At the end, a lengthy enrollment completion notice appears.
You can now check the app registrations in the Azure Portal, under the “App registrations” tab (Fig. 3).
Fig. 3: You can check the successful app registration in the Azure Portal
You can also check the Application ID and Thumbprint for certificate-based access in the Built-in Target “Azure AD Home Tenant” in the ScriptRunner Admin App in the main menu “Targets” (Fig. 4).
Fig. 4: In the ScriptRunner Admin App, you can check the tenant ID, application ID, and thumbprint for certificate-based access for the Azure AD target
If you want to continue using classic AD accounts for user login, run the following command:
In this case, the registration is complete.
If you want to use AAD accounts for user login, the following steps must be completed:
Customize the ScriptRunner Service manifest
Customize the ScriptRunner Portal manifest
Assign AAD Security groups to roles in ScriptRunner
Disable Azure Initial Admin Access in the ScriptRunner Main Admins role
In the manifest of the ScriptRunner service, the authentication method is manually switched to the latest method. This means that corresponding access tokens are now used (Fig. 5).
Fig. 5: The access tokens for ADD registration are visible in the ScriptRunner Service manifest
In the ScriptRunner Portal manifest (Fig. 6), the web application is switched to SPA mode
Fig. 6: The ScriptRunner Portal Manifest shows that the ScriptRunner Web Apps have been set to “SPA” mode
Log in with Azure AD accounts and use Azure AD security groups
Then you have to add the corresponding AAD Security Groups in ScriptRunner in the main menu “Delegation” in a role group (Fig. 7). The effect on access authorization by members of the groups to functions in ScriptRunner is equivalent to the behavior known from AD groups.
Fig. 7: ADD Security groups can be added via the ScriptRunner Admin App
From this point on, when your users access the ScriptRunner Portal or Admin App in their web browser, they will be redirected to logging into Azure AD. After successful authentication, users are now authorized to use ScriptRunner. You can identify logging in using Azure AD Account by the JWT label on the top right of the login name.
Please note that the rights and functions in the ScriptRunner Portal and the ScriptRunner Admin App are managed by the application roles within ScriptRunner.
Azure Queries in ScriptRunner
Azure Queries allow interactive selection of objects available in Azure AD, Azure Cloud or M365 (Fig. 8). As with the familiar AD queries in ScriptRunner, it is possible to make these queries both directly and via PowerShell (fig. 9).
Fig 9: Queries from ScriptRunner to Azure AD, M365 and Azure
Direct Azure queries use Microsoft Graph, Azure Resource Graph, or Azure Data Explorer to query the data objects and pass them as JSON objects to the PowerShell scripts.
Scripted queries use a PowerShell script to query the data objects. The result in each case is a data set that is displayed in the Portal and from which the user can select.
Fig. 9: The query type “Azure” is available for selection since ScriptRunner version 2020R2
A small example shall illustrate this: You want to let the help desk employee select from a list of users from Azure AD with their properties. You assign an Azure Query to the parameter in the main script.
The Azure Query itself uses its home tenant, but can also use other tenant configurations, which is especially interesting for MSPs.
For Azure Queries, there are a few pre-configured elements for simplicity: Users, Groups, Group Members, Member of etc. In the example, we use Users (Figure 10).
As ParameterValue, JSON is suitable because multiple user properties can be queried in one request. As DisplayValue we use the Azure AD property DisplayName.
Fig. 10: Configuration of an Azure query in the ScriptRunner Admin App
A test run shows us the list of Users, the parameter Value is coded. Using mouse-over, we can display the actual values in JSON. To use these values in the main script, the Splatting feature is used.
This is done by defining a hash table whose parameters use the same names as in the JSON object. The actual values are automatically assigned and can be further processed in the script.
With the use of pattern filters, you can specifically restrict the data query. The example in Figure 11 queries all groups that are “Mail enabled”.
Figure 11: Query of all groups that are “Mail enabled” via the pattern filter
Cascading of Azure queries is also possible. This way, use cases like the following can be implemented: A help desk employee queries the AAD groups and selects one. Then, all members of that group are displayed, and they can select one or more members. The members are removed from the group via PowerShell script.
Azure queries can also directly target Microsoft Graph. Microsoft Graph Explorer can be used to create and test Graph queries. The Graph queries tested there can be used 1:1 in ScriptRunner by copying the created Graph URI into the ScriptRunner Azure query (Fig. 12).
Figure 12: Using a Microsoft Graph query in a ScriptRunner Azure query
GET queries do not have a JSON body. POST queries on the other hand, require a JSON body with the parameters to be queried.
Attention when using POST: The service principal of the registered “ScriptRunner Service App” is by default set to read only. You can change this setting in the Azure Portal on the app directly in the API permissions.
Another variant is the direct use of Azure Resource queries. This makes it possible to access all Azure Cloud resources and manage them via PowerShell. The queries are coded using Kusto.
Figure 13: Using an Azure Resource Graph Query within a ScriptRunner Azure Query
With Azure Integration, ScriptRunner can now be used to implement a variety of use cases for managing Azure AD, Azure Cloud and M365 with PowerShell. This applies to both single-tenant and multi-tenant operations.
ScriptRunner users can now primarily use their Azure AD account to log in. Role capabilities can be controlled with Azure AD security groups.
Azure Queries in ScriptRunner are a powerful tool to query objects and resources from Azure AD, Azure Cloud and M365 and use the data in your own PowerShell scripts.