Connect your SAP system by deploying your data connector agent container

Article
12/17/2024

For the Microsoft Sentinel solution for SAP applications to operate correctly, you must first get your SAP data into Microsoft Sentinel. To accomplish this, you need to deploy the solution's SAP data connector agent.

This article describes how to deploy the container that hosts the SAP data connector agent and connect to your SAP system, and is the third step in deploying the Microsoft Sentinel solution for SAP applications. Make sure to perform the steps in this article in the order that they're presented.

Diagram of the SAP solution deployment flow, highlighting the Deploy your data agent container step.

Content in this article is relevant for your security, infrastructure, and SAP BASIS teams.

Prerequisites

Before you deploy the data connector agent:

Make sure that all of the deployment prerequisites are in place. For more information, see Prerequisites for deploying Microsoft Sentinel solution for SAP applications.
Make sure that you have the Microsoft Sentinel solution for SAP applications installed in your Microsoft Sentinel workspace.
Make sure that your SAP system is fully prepared for the deployment. If you're deploying the data connector agent to communicate with Microsoft Sentinel over SNC, make sure that you completed Configure your system to use SNC for secure connections.

Create a virtual machine and configure access to your credentials

We recommend creating a dedicated virtual machine for your data connector agent container to ensure optimal performance and avoid potential conflicts. For more information, see System prerequisites.

We recommend that you store your SAP and authentication secrets in an Azure key vault. How you access your key vault depends on where your virtual machine (VM) is deployed:

Deployment method	Access method
Container on an Azure VM	We recommend using an Azure system-assigned managed identity to access Azure Key Vault. If a system-assigned managed identity can't be used, the container can also authenticate to Azure Key Vault using a Microsoft Entra ID registered-application service principal, or, as a last resort, a configuration file.
A container on an on-premises VM, or a VM in a third-party cloud environment	Authenticate to Azure Key Vault using a Microsoft Entra ID registered-application service principal.

If you can't use a registered application or a service principal, use a configuration file to manage your credentials, though this method isn't preferred. For more information, see Deploy the data connector using a configuration file.

For more information, see:

Your virtual machine is typically created by your infrastructure team. Configuring access to credentials and managing key vaults is typically done by your security team.

Managed identity
Registered application

Create a managed identity with an Azure VM

Run the following command to Create a VM in Azure, substituting actual names from your environment for the <placeholders>:

az vm create --resource-group <resource group name> --name <VM Name> --image Canonical:0001-com-ubuntu-server-focal:20_04-lts-gen2:latest --admin-username <azureuser> --public-ip-address "" --size  Standard_D2as_v5 --generate-ssh-keys --assign-identity --role <role name> --scope <subscription Id>

For more information, see Quickstart: Create a Linux virtual machine with the Azure CLI.

Important

After the VM is created, be sure to apply any security requirements and hardening procedures applicable in your organization.

This command creates the VM resource, producing output that looks like this:

{
  "fqdns": "",
  "id": "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/resourcegroupname/providers/Microsoft.Compute/virtualMachines/vmname",
  "identity": {
    "systemAssignedIdentity": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy",
    "userAssignedIdentities": {}
  },
  "location": "chinaeast2",
  "macAddress": "00-11-22-33-44-55",
  "powerState": "VM running",
  "privateIpAddress": "192.168.136.5",
  "publicIpAddress": "",
  "resourceGroup": "resourcegroupname",
  "zones": ""
}

Copy the systemAssignedIdentity GUID, as it will be used in the coming steps. This is your managed identity.

Register an application to create an application identity

Run the following command from the Azure command line to create and register an application:

az ad sp create-for-rbac

This command creates the application, producing output that looks like this:

{
  "appId": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
  "displayName": "azure-cli-2022-01-28-17-59-06",
  "password": "ssssssssssssssssssssssssssssssssss",
  "tenant": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb"
}

For more information, see the Azure CLI reference documentation.

Copy the appId, tenant, and password from the output. You need these for assigning the key vault access policy and running the deployment script in the coming steps.
Before proceeding any further, create a virtual machine on which to deploy the agent. You can create this machine in Azure, in another cloud, or on-premises.

Create a key vault

This procedure describes how to create a key vault to store your agent configuration information, including your SAP authentication secrets. If you're using an existing key vault, skip directly to step 2.

To create your key vault:

Run the following commands, substituting actual names for the <placeholder> values.

az keyvault create \
  --name <KeyVaultName> \
  --resource-group <KeyVaultResourceGroupName>

Copy the name of your key vault and the name of its resource group. You'll need these when you assign the key vault access permissions and run the deployment script in the next steps.

Assign key vault access permissions

In your key vault, assign the following Azure role-based access control or vault access policy permissions on the secrets scope to the identity that you created and copied earlier.

Permission model Permissions required

Azure role-based access control Key Vault Secrets User

Vault access policy get, list

Use the options in the portal to assign the permissions, or run one of the following commands to assign key vault secrets permissions to your identity, substituting actual names for the <placeholder> values. Select the tab for the type of identity you created.

The policy specified in the commands allows the VM to list and read secrets from the key vault.
- Azure role-based access control permission model:
  - Managed identity
  - Registered application
```
az role assignment create --assignee-object-id <ManagedIdentityId> --role "Key Vault Secrets User" --scope /subscriptions/<KeyVaultSubscriptionId>/resourceGroups/<KeyVaultResourceGroupName> /providers/Microsoft.KeyVault/vaults/<KeyVaultName>
```
```
az role assignment create --assignee-object-id <ServicePrincipalObjectId> --role "Key Vault Secrets User" --scope /subscriptions/<KeyVaultSubscriptionId>/resourceGroups/<KeyVaultResourceGroupName>/providers/Microsoft.KeyVault/vaults/<KeyVaultName>
```
  To find the object ID of the app registration’s service principal, go to the Microsoft Entra ID portal's Enterprise applications page. Search for the name of the app registration there, and copy the Object ID value.
  
  Important
  
  Do not confuse the object ID from the Enterprise Applications page with the app registration's object ID found on the App registrations page. Only the object ID from the Enterprise applications page will work.
- Vault access policy permission model:
  - Managed identity
  - Registered application
```
az keyvault set-policy -n <KeyVaultName> -g <KeyVaultResourceGroupName> --object-id <ManagedIdentityId> --secret-permissions get list
```
```
az keyvault set-policy -n <KeyVaultName> -g <KeyVaultResourceGroupName> --spn <ApplicationId> --secret-permissions get list
```
  To find the object ID of the app registration, go to the Microsoft Entra ID portal's App registrations page. Search for name of the app registration and copy the Application (client) ID value.
In the same key vault, assign the following Azure role-based access control or vault access policy permissions on the secrets scope to the user configuring the data connector agent:

Permission model Permissions required

Azure role-based access control Key Vault Secrets Officer

Vault access policy get, list, set, delete

Use the options in the portal to assign the permissions, or run one of the following commands to assign key vault secrets permissions to the user, substituting actual names for the <placeholder> values:
- Azure role-based access control permission model:
```
az role assignment create --role "Key Vault Secrets Officer" --assignee <UserPrincipalName> --scope /subscriptions/<KeyVaultSubscriptionId>/resourceGroups/<KeyVaultResourceGroupName>/providers/Microsoft.KeyVault/vaults/<KeyVaultName>
```
- Vault access policy permission model:
```
az keyvault set-policy -n <KeyVaultName> -g <KeyVaultResourceGroupName> --upn <UserPrincipalName>--secret-permissions get list set delete
```

Permission model	Permissions required
Azure role-based access control	Key Vault Secrets User
Vault access policy	`get`, `list`

Permission model	Permissions required
Azure role-based access control	Key Vault Secrets Officer
Vault access policy	`get`, `list`, `set`, `delete`

Deploy the data connector agent from the portal (Preview)

Now that you created a VM and a Key Vault, your next step is to create a new agent and connect to one of your SAP systems. While you can run multiple data connector agents on a single machine, we recommend that you start with one only, monitor the performance, and then increase the number of connectors slowly.

This procedure describes how to create a new agent and connect it to your SAP system using the Azure portal. We recommend that your security team perform this procedure with help from the SAP BASIS team.

While deployment is also supported from the command line, we recommend that you use the portal for typical deployments. Data connector agents deployed using the command line can be managed only via the command line, and not via the portal. For more information, see Deploy a SAP data connector agent from the command line.

Important

Deploying the container and creating connections to SAP systems from the portal is currently in PREVIEW. The Azure Preview Supplemental Terms include additional legal terms that apply to Azure features that are in beta, preview, or otherwise not yet released into general availability.

Prerequisites:

To deploy your data connector agent via the portal, you need:
- Authentication via a managed identity or a registered application
- Credentials stored in an Azure Key Vault
If you don't have these prerequisites, deploy the SAP data connector agent from the command line instead.
To deploy the data connector agent, you also need sudo or root privileges on the data connector agent machine.
If you want to ingest Netweaver/ABAP logs over a secure connection using Secure Network Communications (SNC), you need:
- The path to the sapgenpse binary and libsapcrypto.so library
- The details of your client certificate
For more information, see Configure your system to use SNC for secure connections.

To deploy the data connector agent:

Sign in to the newly created VM on which you're installing the agent, as a user with sudo privileges.
Download and/or transfer the SAP NetWeaver SDK to the machine.
In Microsoft Sentinel, select Configuration > Data connectors.
In the search bar, enter SAP. Select Microsoft Sentinel for SAP from the search results and then Open connector page.
In the Configuration area, select Add new agent (Preview).

In the Create a collector agent pane, enter the following agent details:

Name	Description
Agent name	Enter a meaningful agent name for your organization. We don't recommend any specific naming convention, except that the name can include only the following types of characters: a-z A-Z 0-9 _ (underscore) . (period) - (dash)
Subscription / Key vault	Select the Subscription and Key vault from their respective drop-downs.
NWRFC SDK zip file path on the agent VM	Enter the path in your VM that contains the SAP NetWeaver Remote Function Call (RFC) Software Development Kit (SDK) archive (.zip file). Make sure that this path includes the SDK version number in the following syntax: `<path>/NWRFC<version number>.zip`. For example: `/src/test/nwrfc750P_12-70002726.zip`.
Enable SNC connection support	Select to ingest NetWeaver/ABAP logs over a secure connection using SNC. If you select this option, enter the path that contains the `sapgenpse` binary and `libsapcrypto.so` library, under SAP Cryptographic Library path on the agent VM. If you want to use an SNC connection, make sure to select Enable SNC connection support at this stage as you can't go back and enable an SNC connection after you finish deploying the agent. If you want to change this setting afterwards, we recommend that you create a new agent instead.
Authentication to Azure Key Vault	To authenticate to your key vault using a managed identity, leave the default Managed Identity option selected. To authenticate to your key vault using a registered application, select Application Identity. You must have the managed identity or registered application set up ahead of time. For more information, see Create a virtual machine and configure access to your credentials.

For example:

Screenshot of the Create a collector agent area.

Select Create and review the recommendations before you complete the deployment:
Deploying the SAP data connector agent requires that you grant your agent's VM identity with specific permissions to the Microsoft Sentinel workspace, using the Microsoft Sentinel Business Applications Agent Operator and Reader roles.

To run the commands in this step, you must be a resource group owner on your Microsoft Sentinel workspace. If you aren't a resource group owner on your workspace, this procedure can also be performed after the agent deployment is complete.

Under Just a few more steps before we finish, copy the Role assignment commands from step 1 and run them on your agent VM, replacing the [Object_ID] placeholder with your VM identity object ID. For example:

To find your VM identity object ID in Azure:
- For a managed identity, the object ID is listed on the VM's Identity page.
- For a service principal, go to Enterprise application in Azure. Select All applications and then select your VM. The object ID is displayed on the Overview page.
These commands assign the Microsoft Sentinel Business Applications Agent Operator and Reader Azure roles to your VM's managed or application identity, including only the scope of the specified agent's data in the workspace.

Important

Assigning the Microsoft Sentinel Business Applications Agent Operator and Reader roles via the CLI assigns the roles only on the scope of the specified agent's data in the workspace. This is the most secure, and therefore recommended option.

If you must assign the roles via the Azure portal, we recommend assigning the roles on a small scope, such as only on the Microsoft Sentinel workspace.
Select Copy next to the Agent deployment command in step 2. For example:
Copy the command line to a separate location and then select Close.

The relevant agent information is deployed into Azure Key Vault, and the new agent is visible in the table under Add an API based collector agent.

At this stage, the agent's Health status is "Incomplete installation. Please follow the instructions". Once the agent is installed successfully, the status changes to Agent healthy. This update can take up to 10 minutes. For example:

Note

The table displays the agent name and health status for only those agents you deploy via the Azure portal. Agents deployed using the command line aren't displayed here. For more information, see the Command line tab instead.
On the VM where you plan to install the agent, open a terminal and run the Agent deployment command that you copied in the previous step. This step requires sudo or root privileges on the data connector agent machine.

The script updates the OS components and installs the Azure CLI, Docker software, and other required utilities, such as jq, netcat, and curl.

Supply extra parameters to the script as needed to customize the container deployment. For more information on available command line options, see Kickstart script reference.

If you need to copy your command again, select View to the right of the Health column and copy the command next to Agent deployment command on the bottom right.
In the Microsoft Sentinel solution for SAP application's data connector page, in the Configuration area, select Add new system (Preview) and enter the following details:
- Under Select an agent, select the agent you created earlier.
- Under System identifier, select the server type:
  - ABAP Server
  - Message Server to use a message server as part of an ABAP SAP Central Services (ASCS).
- Continue by defining related details for your server type:
  - For an ABAP server, enter the ABAP Application server IP address/FQDN, the system ID and number, and the client ID.
  - For a message server, enter the message server IP address/FQDN, the port number or service name, and the logon group
When you're done, select Next: Authentication.

For example:
On the Authentication tab, enter the following details:
- For basic authentication, enter the user and password.
- If you selected an SNC connection when you set up the agent, select SNC and enter the certificate details.
When you're done, select Next: Logs.
On the Logs tab, select the logs you want to ingest from SAP, and then select Next: Review and create. For example:
(Optional) For optimal results in monitoring the SAP PAHI table, select Configuration History. For more information, see Verify that the PAHI table is updated at regular intervals.
Review the settings you defined. Select Previous to modify any settings, or select Deploy to deploy the system.

The system configuration you defined is deployed into the Azure key vault you defined during the deployment. You can now see the system details in the table under Configure an SAP system and assign it to a collector agent. This table displays the associated agent name, SAP System ID (SID), and health status for systems that you added via the portal or otherwise.

At this stage, the system's Health status is Pending. If the agent is updated successfully, it pulls the configuration from Azure Key vault, and the status changes to System healthy. This update can take up to 10 minutes.

Check connectivity and health

After you deploy the SAP data connector agent, check your agent's health and connectivity. For more information, see Monitor the health and role of your SAP systems.

Next step

Once the connector is deployed, proceed to configure the Microsoft Sentinel solution for SAP applications content. Specifically, configuring details in the watchlists is an essential step in enabling detections and threat protection.

Enable SAP detections and threat protection