ZSCALER AND

MICROSOFT SENTINEL
DEPLOYMENT GUIDE

DECEMBER 2023, VERSION 1.15 BUSINESS DEVELOPMENT GUIDE

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

Contents
Terms and Acronyms 7
Trademark Notice 8
About This Document 9
Zscaler Overview 9
Audience 9
Software Versions 9
Request for Comments 9
Zscaler and Microsoft Introduction 10
ZIA Overview 10
Zscaler Resources 10
Microsoft Sentinel Overview 11
Microsoft Sentinel Resources 11
Document Prerequisites 11
Syslog, CEF, and LEEF 12
Syslog 12

CEF 13
LEEF 13
Zscaler Logging Architecture 14
NSS 14
About Cloud-To-Cloud Log Streaming 15
ZIA Log Feeds 15
Configuring Sentinel for Cloud NSS-Based Log Ingestion 16
Step 1. In the Azure Portal, Create a Log Analytics Workspace,
and Add Microsoft Sentinel to the Workspace 16
Step 2: In the Azure Portal, Create a Data Collection Endpoint 18

©2023 Zscaler, Inc. All rights reserved. 2

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

Step 3. In the Azure Portal, Register an Azure Active Directory

Application and Create a Client Secret 20
Step 4. In the Azure Portal, Create a Table and Data Collection Rule 24
Step 5. Using Azure Cloud Shell, Change the Table’s Output Stream 35
Step 6. In the Azure Portal, Assign Permissions to the DCR 39
Configuring ZIA for Cloud NSS-Based Log Export 42
Step 1. In the ZIA Admin Portal, Add a Cloud NSS Feed 42
(Optional) Using PowerShell, Verify Log Data Arrives at the Endpoint 46
In Microsoft Sentinel, View Log Details 49

Configuring ZIA for NSS VM-Based Log Export 52

Logging in to ZIA 52
Configuring NSS 52
Configuring NSS 53
Verify NSS Server State 54
Add NSS Feed 54
Configure NSS Feed 55
Edit NSS Feed (Web) 55
Edit NSS Feed (Firewall) 56
Edit NSS Feed (DNS) 56

Activate your changes 57

Configuring Sentinel for NSS VM-Based Log Ingestion 58
Log in to Azure Portal 58
Deploy the Data Connector Host VM 59
Create Virtual Machine 60
Bind this VM to a Resource Group 61

Allowing Inbound Ports 62

Add Inbound Security Rule for Syslog 64
Add Inbound Security Rule for SSH 65

©2023 Zscaler, Inc. All rights reserved. 3

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

Create and Configure Sentinel Instance 66

Create Log Analytics Workspace 66
Name, Add, and Link a Resource Group to a Workspace 67
Add an Azure Sentinel Workspace 68

Configure Data Collection 69

Search for Zscaler Connector 70
Configure Syslog Agent 71
Pick a Zscaler Workbook 74
Explore Zscaler Workbook 74

Configuring Sentinel for ZPA 75

Log in to Azure Portal 75
Deploy the Data Connector Host VM 76
Create Virtual Machine 76
Bind this VM to a Resource Group 77

Allowing Inbound Ports 78

Add Inbound Security Rule for Syslog 80
Add Inbound Security Rule for SSH 81

Create and Configure Sentinel Instance 82

Create Log Analytics Workspace 82
Name, Add, and Link a Resource Group to a Workspace 83
Add Microsoft Sentinel Workspace 84

Configure Data Collection 85

Search for Zscaler Private Access Connector 85
Choose Where to Install the Linux Agent 86
Install and Onboard the Agent on an Azure Linux Virtual Machine 87
Configure Which Logs to Collect 88

©2023 Zscaler, Inc. All rights reserved. 4

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

Microsoft Sentinel Playbooks Overview 89

Microsoft Sentinel Playbooks Resources 89
ZIA API Architecture Overview 90
OAuth 2.0 Authentication 90
OAuth 2.0 Prerequisites 91
Benefits of OAuth 2.0 authentication 91

Configuring a ZIA API Role 92

Logging in to ZIA 92
Create an API Role 92

Configuring Microsoft Entra ID for OAuth 2.0 Authentication 94

Register the ZIA API Client Application 94
Configure Client Credentials 96
Configure the ZIA API Web Service Application 98
Configure the ZIA API Client Application to access the ZIA API Web Service Application
104
Collect Information for Zscaler OAuth 2.0 Server Configuration 106
Configuring the OAuth2.0 Authorization Server 107

Authenticating an OAuth 2.0 Session in Postman 108

Installing and Configuring Postman for Windows, macOS, or Linux 108

Deployment of Zscaler Playbooks for Microsoft Sentinel 113

Giving Permission to Microsoft Sentinel to Run Playbooks 113
Configuring an Azure Key Vault 115
Deploying the Zscaler-Oauth2-Authenticaton Playbook 119
Deploying the Zscaler-Oauth2-BlockIP Playbook 125
Deploying the Zscaler-Oauth2-BlacklistURL Playbook 127
Deploying the Zscaler-Oauth2-BlockURL Playbook 129
Deploying the Zscaler-Oauth2-LookupIP Playbook 131
Deploying the Zscaler-Oauth2-LookupSandboxReport Playbook 133
Deploying the Zscaler-Oauth2-LookupURL Playbook 136
Deploying the Zscaler-Oauth2-UnblacklistURL Playbook 138

©2023 Zscaler, Inc. All rights reserved. 5

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

Deploying the Zscaler-Oauth2-UnblockIP Playbook 141

Deploying the Zscaler-Oauth2-UnblockURL Playbook 143
Deploying the Zscaler-Oauth2-WhitelistURL Playbook 145

Appendix A: Requesting Zscaler Support 147

Save Company ID 147
Enter Support Section 148

©2023 Zscaler, Inc. All rights reserved. 6

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

Terms and Acronyms

This table defines acronyms used in this deployment guide. When applicable, a Request for Change (RFC) is included in
the Definition column for your reference.

Acronym Definition
AMA Azure Monitor Agent
CEF Common Event Format
GRE Generic Routing Encapsulation (RFC2890)
JWT JSON Web Token
LEEF Log Event Extended Format
LSS Log Streaming Service (For ZPA)
NSG Network Service Group (Azure)
NSS Nanolog Streaming Service (For ZIA)
SOC Security Operations Center
SSH Secure Socket Shell
SSL Secure Socket Layer (RFC6101)
TLS Transport Layer Security (RFC5246)
Vnet Virtual Network (Azure)
ZIA Zscaler Internet Access (Zscaler)
ZPA Zscaler Private Access (Zscaler)

©2023 Zscaler, Inc. All rights reserved. 7

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

Trademark Notice
© 2023 Zscaler, Inc. All rights reserved. Zscaler™ and other trademarks listed at zscaler.com/legal/trademarks are either (i)
registered trademarks or service marks or (ii) trademarks or service marks of Zscaler, Inc. in the United States and/or other
countries. Any other trademarks are the properties of their respective owners.

©2023 Zscaler, Inc. All rights reserved. 8

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

About This Document

The following sections describe the organizations and requirements of this deployment guide.

Zscaler Overview
Zscaler (NASDAQ: ZS) enables the world’s leading organizations to securely transform their networks and applications for
a mobile and cloud-first world. ZIA and ZPA, create fast, secure connections between users and applications, regardless
of device, location, or network. Zscaler delivers its services 100% in the cloud and offers the simplicity, enhanced
security, and improved user experience that traditional appliances or hybrid solutions can’t match. Used in more than
185 countries, Zscaler operates a massive, global cloud security platform that protects thousands of enterprises and
government agencies from cyberattacks and data loss. To learn more, see Zscaler’s website or follow Zscaler on Twitter @
zscaler.

Microsoft Overview
Microsoft (Nasdaq: MSFT), Microsoft develops and licenses consumer and enterprise software. It is known for its
Windows operating systems and Office productivity suite. The company is organized into three equally sized broad
segments: productivity and business processes (legacy Microsoft Office, cloud-based Office 365, Exchange, SharePoint,
Skype, LinkedIn, Dynamics), intelligence cloud (infrastructure- and platform-as-a-service offerings Azure, Windows Server
OS, SQL Server), and more personal computing (Windows Client, Xbox, Bing search, display advertising, and Surface
laptops, tablets, and desktops).

Audience
This guide is for network administrators, endpoint and IT administrators, and security analysts responsible for deploying,
monitoring, and managing enterprise security systems. For additional product and company resources, refer to the
Appendix sections:

• Zscaler Resources
• Microsoft Sentinel Resources
• Appendix A: Requesting Zscaler Support

Software Versions
This document was written using ZIA v5.7, NSS v4.0.4, Linux Ubuntu Server 18.04 LTS (any Linux version should work), and
the latest Microsoft Sentinel version as of January 2020.

Request for Comments

• For prospects and customers: Zscaler values reader opinions and experiences. Contact partner-doc-support@
zscaler.com to offer feedback or corrections for this guide.
• For Zscaler employees: Contact [email protected] to reach the team that validated and authored the integrations
in this document.

©2023 Zscaler, Inc. All rights reserved. 9

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

Zscaler and Microsoft Introduction

Overviews of the Zscaler and Microsoft applications are described in this section.

ZIA Overview
ZIA is a secure internet and web gateway delivered as a service from the cloud. Think of ZIA as a secure internet on-
ramp—just make Zscaler your next hop to the internet via one of the following methods:

• Setting up a tunnel (GRE or IPSec) to the closest Zscaler data center (for offices).
• Forwarding traffic via our lightweight Zscaler Client Connector or PAC file (for mobile employees).
No matter where users connect—a coffee shop in Milan, a hotel in Hong Kong, or a VDI instance in South Korea—they get
identical protection. ZIA sits between your users and the internet and inspects every transaction inline across multiple
security techniques (even within SSL).

You get full protection from web and internet threats. The Zscaler cloud platform supports Cloud Firewall, IPS,
Sandboxing, DLP, and Browser Isolation, allowing you to start with the services you need now and activate others as your
needs grow.

ZPA Overview
ZPA is a cloud service that provides secure remote access to internal applications running on a cloud or data center using
a Zero Trust framework. With ZPA, applications are never exposed to the internet, making them completely invisible
to unauthorized users. The service enables the applications to connect to users via inside-out connectivity rather than
extending the network to them.

ZPA provides a simple, secure, and effective way to access internal applications. Access is based on policies created by
the IT administrator within the ZPA Admin Portal and hosted within the Zscaler cloud. On each user device, software
called Zscaler Client Connector is installed. Zscaler Client Connector ensures the user’s device posture and extends a
secure microtunnel out to the Zscaler cloud when a user attempts to access an internal application.

Zscaler Resources
The following table contains links to Zscaler resources based on general topic areas.

Name Definition
ZIA Help Portal Help articles for ZIA.
ZPA Help Portal Help articles for ZPA.
NSS Deployment Guide Help article for NSS deployment.
NSS Troubleshooting Guide Help article for NSS troubleshooting.
Deploy NSS on Microsoft Azure Help article on deploying NSS on Azure.
Web Logs Help article on Zscaler web logs.
Firewall Logs Help article on Zscaler firewall logs.
DNS Logs Help article on Zscaler DNS logs.
Tunnel Logs Help article on Zscaler tunnel logs.
Zscaler NSS Azure Resource Manager Repository with an ARM template for deploying Zscaler NSS in Azure cloud.
(ARM) Template
Zscaler Tools Troubleshooting, security and analytics, and browser extensions that help
Zscaler determine your security needs.

©2023 Zscaler, Inc. All rights reserved. 10

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

Name Definition
Zscaler Training and Certification Training designed to help you maximize Zscaler products.
Submit a Zscaler Support Ticket Zscaler Support portal for submitting requests and issues.

Microsoft Sentinel Overview

Microsoft Sentinel is a scalable, cloud-native, security information and event management (SIEM) and security
orchestration, automation, and response (SOAR) solution. Microsoft Sentinel delivers intelligent security analytics and
threat intelligence across the enterprise, providing a single solution for attack detection, threat visibility, proactive hunting,
and threat response. Microsoft Sentinel is your birds-eye view across the enterprise alleviating the stress of increasingly
sophisticated attacks, increasing volumes of alerts, and long resolution time frames.

• Collect data at cloud scale across all users, devices, applications, and infrastructure, both on-premises and in multiple
clouds.
• Detect previously undetected threats and minimize false positives using Microsoft’s analytics and unparalleled threat
intelligence.
• Investigate threats with artificial intelligence, and hunt for suspicious activities at scale, tapping into years of
cybersecurity work at Microsoft.
• Respond to incidents rapidly with built-in orchestration and automation of common tasks.
For more information on Azure, refer to the Microsoft Azure website or follow them on Twitter @microsoft.

Microsoft Sentinel Resources

The following table contains links to Azure support resources.

Name Definition
Zscaler Private Access connector Help article on using ZPA with Microsoft Sentinel.
for Microsoft Sentinel
Microsoft Sentinel Documentation Article with use cases to get started using Microsoft Sentinel.
Azure support Support portal for Azure problems and help.
Sentinel Query Language Kusto query overview.
Reference

Document Prerequisites
To use this document, the following prerequisites are required:

• ZIA:
• An active instance of ZIA 5.7 or later.
• A working deployment of NSS (if not, see Understanding Nanolog Streaming Service for more information).
• Administrator login credentials to ZIA.
• Microsoft Sentinel:
• Administrator login credentials to Microsoft Azure.
• Active subscription with Microsoft Sentinel.

©2023 Zscaler, Inc. All rights reserved. 11

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

Syslog, CEF, and LEEF

This section explains Syslog. If you are already familiar with Syslog, skip to the section Appendix A: Requesting Zscaler
Support.

Syslog
Syslog has been used for many decades. Over time, new standards were created to define new message formats and
support new use cases. Briefly, a Syslog message has the following structure (in order): a header, structured data (SD), and
a message. In this section, the Syslog header and Syslog message (the body of the message) are explained.

RFC 3164 is considered the original BSD structure from 2001. The following is an example log message:

Figure 1. Syslog message in RFC 3164 format

• Syslog Header:
• <34> is a priority number. It represents the sum of the facility number multiplied by eight and severity. In this
case, facility=3 (Auth) and severity=4 (Critical).
• Oct 11 22:14:15 is the timestamp. It doesn’t include the year, time zone, and sub-second information.
• mymachine is a host name where the message was written.
• su is a tag. Typically, this is the process name – sometimes having a PID (e.g., su[1234]).
• Syslog Message:
• The remainder of the message (MSG) is everything after the su tag.
The new (2009) Syslog format (RFC 5424) is three parts: "Syslog Header," "Structured Data," and the actual log "message."

• Syslog Header. Consists of priority, version, timestamp, hostname, etc.

• Structured Data. This is in key=value format. It provides a mechanism to express information in a defined, parsable
and interpretable data format (e.g., SD-ID, SD-PARAM).
• Actual log message. This follows the two fields above (the Message field is free-form).

Figure 2. Syslog message in RFC 5424 format

• The dashes are places for the PID, message ID, and other structured data.

©2023 Zscaler, Inc. All rights reserved. 12

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

Figure 3. Another Syslog message in RFC 5424 format

CEF
Common Event Format (CEF) is an open log management standard that improves the interoperability of security-related
information from different security and network devices and applications.

Base CEF format:

CEF:Version|Device Vendor|Device Product|Device Version|Signature

ID|Name|Severity|Extension

LEEF
Log Event Extended Format (LEEF) is a customized event format created by IBM QRadar. It is designed to describe
(network) security events and uses encoding and transport like those used by CEF. However, the two formats differ in the
number and types of fields.

Base LEEF Format:

LEEF:2.0|Vendor|Product|Version|EventID|(Delimiter Character, optional if the

Delimiter Character is tab)|Extension

©2023 Zscaler, Inc. All rights reserved. 13

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

Zscaler Logging Architecture

Zscaler has two core products: ZIA and ZPA. ZIA’s and ZPA’s ability to send log messages outside of Zscaler’s cloud
requires a product known as Nanolog Streaming Service (NSS).

When customers use ZIA or ZPA, every customer-initiated transaction that traverses Zscaler generates a corresponding
log message. These logs messages are retained by Zscaler for six months (or longer through a paid-for service). Customers
can view and search these logs using the dashboard of the ZIA or ZPA Admin Portal.

NSS
Log messages are stored within Nanolog. When an organization deploys NSS for various log feeds, each NSS opens a
secure tunnel to the Nanolog in the Zscaler cloud. The Nanolog then streams copies of the logs to each NSS in a highly
compressed format to reduce bandwidth footprint. The original logs are retained on the Nanolog.

Figure 4. Nanolog Streaming Service (NSS) overview

When an NSS receives the logs from the Nanolog, it unscrambles them, applies the configured filters to exclude
unwanted logs, converts the filtered logs to the configured output format so they are parsed by your security information
and event management (SIEM), and then streams the logs to your SIEM over a raw TCP connection.

Zscaler NSS is required for customers who want to send these logs to a SIEM (on-premises or in-the-cloud). Think of NSS
as an intermediate log gateway. NSS uses a virtual machine (VM) to stream traffic logs in real time from ZIA.

Although Syslog usually uses UDP and destination port 514, NSS only supports TCP. By using TCP, NSS can detect
Clipboard-list if the SIEM becomes unavailable by the loss of the TCP connection. In the event of a failure, NSS queues log
messages until the SIEM returns (subject to storage).

©2023 Zscaler, Inc. All rights reserved. 14

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

About Cloud-To-Cloud Log Streaming

Your organization can optionally subscribe to cloud-to-cloud log streaming (Cloud NSS), which allows direct cloud-
to-cloud log streaming for all types of ZIA logs into a compatible cloud-based SIEM solution. Rather than deploying,
managing, and monitoring on-premises NSS VMs, you can simply configure an HTTPS API feed to push logs from the
Zscaler cloud service into an HTTPS API-based log collector on the SIEM.

ZIA Log Feeds

An NSS feed specifies the data from the logs that the NSS sends to the SIEM. You can filter the data to send only the data
you need to the SIEM. You can add one or more fields for the logs and one field for alerts. You can add up to eight NSS
feeds for each NSS. Each feed can have a different list of fields, a different format, and different filters. The following are
the supported feeds.

Zscaler Platform & Product Feed Types

ZIA NSS Web Logs
ZIA NSS Firewall Logs
ZIA NSS DNS Logs
ZIA NSS Alert Logs
ZIA NSS Tunnel Logs

©2023 Zscaler, Inc. All rights reserved. 15

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

Configuring Sentinel for Cloud NSS-Based Log Ingestion

The following steps let you configure Cloud NSS and Microsoft Sentinel.

Step 1. In the Azure Portal, Create a Log Analytics Workspace, and Add Microsoft
Sentinel to the Workspace
1. Log in to the Azure portal.
2. Go to Microsoft Sentinel.

Figure 5. Microsoft Sentinel tile

3. Click Create.

Figure 6. Microsoft Sentinel create

4. Click Create a new workspace.

Figure 7. Create a new workspace

5. The Create Log Analytics workspace wizard appears. In the Create Log Analytics workspace wizard:
a. Under the Resource group field, click Create new.
b. Enter a Name (e.g., test-1-RG).
c. Click OK.

Figure 8. Create Log Analytics workspace

©2023 Zscaler, Inc. All rights reserved. 16

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

d. Under Instance details, enter a Name (e.g., test-1-WS) and select a Region.

Figure 9. Project details

e. Click Review + Create, then click Create. You are redirected to the Add Microsoft Sentinel to a workspace
page and a success message appears.
6. Click Refresh to see your newly created workspace.

Figure 10. Add Microsoft Sentinel to a workspace

7. Select your newly created workspace, then click Add.

Figure 11. Newly created workspace

You are redirected to the Microsoft Sentinel | News & guides page and a success message appears.

Figure 12. Workspace successfully created

©2023 Zscaler, Inc. All rights reserved. 17

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

Step 2: In the Azure Portal, Create a Data Collection Endpoint

A Data Collection Endpoint (DCE) is the API endpoint. You can send multiple types of Cloud NSS logs (e.g., web, Firewall,
DNS, etc.) to the same DCE. The Data Collection Rules (DCRs) linked to the DCE differentiate the types of logs arriving at
the endpoint.

1. Go to Monitor.

Figure 13. Monitor tile

2. In the left-side navigation, go to Settings > Data Collection Endpoints.

Figure 14. Data Collection Endpoints

3. Click Create. The Create data collection endpoint wizard appears.

Figure 15. Monitor Data Collection Endpoints

©2023 Zscaler, Inc. All rights reserved. 18

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

4. In the Create data collection endpoint wizard:

a. Enter an Endpoint Name (e.g., test-1-DCE).
b. Search for and select your newly created Resource Group (e.g., test-1-RG).
c. Ensure the DCE is located in the same Region as your Log Analytics workspace.

Figure 16. Create data collection endpoint

d. Click Review + create, then click Create. You are redirected to the Data Collection Endpoints page and a
success message appears.
5. Click Refresh to see your newly created DCE.

Figure 17. Refresh Data Collection Endpoints

6. Select your newly created DCE to go to its overview page.

©2023 Zscaler, Inc. All rights reserved. 19

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

7. On the Overview page under Essentials, copy and save the Logs Ingestion URI, which is required for adding a Cloud
NSS feed in the ZIA Admin Portal.

Figure 18. Log ingestion URI

Step 3. In the Azure Portal, Register an Azure Active Directory Application and
Create a Client Secret
To register an Active Directory (AD) application and create a client secret:

1. Go to Azure Active Directory.

Figure 19. Azure Active Directory tile

2. In the left-side navigation, go to Manage > App registrations.

Figure 20. App registrations

3. Click New registration. The Register an application page appears.

Figure 21. New registration

©2023 Zscaler, Inc. All rights reserved. 20

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

4. On the Register an application page, enter a Name (e.g., test-1-app), then click Register.

Figure 22. Register an application

You are redirected to the application’s overview page and a success message appears.
5. On the Overview page under Essentials, copy and save the Application (client) ID and the Directory (tenant) ID,
which are required for adding a Cloud NSS feed in the ZIA Admin Portal.

Figure 23. Application and Directory ID

©2023 Zscaler, Inc. All rights reserved. 21

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

6. Create a client secret for your application:

a. In the left-side navigation, go to Manage > Certificates & secrets.

Figure 24. Certificates & secrets

b. Click New client secret. The Add a client secret window is displayed.

Figure 25. New client secret

©2023 Zscaler, Inc. All rights reserved. 22

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

c. In the Add a client secret window:

i. Enter a Description.
ii. Set an expiration.

Figure 26. Add client secret

7. Click Add to close the window. You are redirected to the Certificates & secrets page and a success message
appears.
8. On the Certificates & Secrets page, copy and save the client secret Value, which is required for adding a Cloud NSS
feed in the ZIA Admin Portal.

Figure 27. Client secret value

©2023 Zscaler, Inc. All rights reserved. 23

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

Step 4. In the Azure Portal, Create a Table and Data Collection Rule
To create a table and data collection rule (DCR) in Azure:

1. Go to Log Analytics workspaces.

Figure 28. Log Analytics Workspaces tile

2. Select your workspace (e.g., test-1-WS).

Figure 29. Log Analytics workspaces

3. In the left-side navigation, go to Settings > Tables.

Figure 30. Workspace tables

4. Click the Create drop-down menu and select New custom log (DCR-based). The Create a custom log wizard is
displayed.

Figure 31. Create new custom log

©2023 Zscaler, Inc. All rights reserved. 24

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

5. In the Create a custom log wizard:

a. Enter a Table name (e.g., table_1_web).
b. Click Create a new data collection rule. The Create a new data collection rule window is displayed.

Figure 32. Table details

c. In the Create a new data collection rule window, enter a Name for the DCR (e.g., test-1-DCR).

Figure 33. Create a new data collection rule

©2023 Zscaler, Inc. All rights reserved. 25

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

d. Click Done to close the window.

e. Select your newly created DCE (e.g., test-1-DCE) from the drop-down menu.

Figure 34. Create a custom log

f. Click Next. You are prompted to upload a sample of logs in JSON format.

Figure 35. Upload JSON logs

g. Based on the type of Cloud NSS feed you want to add, copy one of the following log samples to a .log file, then
upload the file as directed in the Create a custom log wizard.
Sample of Web Logs:
[{ "sourcetype" : "zscalernss-web", "TimeGenerated":"2023-02-17 22:55:01",
"act":"Blocked", "reason":"Blocked", "app":"HTTPS", "dhost":"www.etsy.com",
"dst":"104.94.233.143", "src":"10.2.3.4", "sourceTranslatedAddress":"40.83.138.250",
"in":"50", "out":"10", "request":"www.1etsy.com/dac/common/web-toolkit/
scoped/scoped_responsive_base.20220526203537%2csite-chrome/deprecated/global-
nav.20220526203537%2ccommon/web-toolkit/a11y_colors/overrides.20220526203537.
css", "requestContext":"www.1etsy.com/c/clothing-and-shoes?ref=catnav-10923",
"outcome":"200", "requestClientApplication":"Mozilla/5.0 (Windows NT 6.2; Win64; x64;
rv:16.0.1) Gecko/20121011 Firefox/21.0.1", "requestMethod":"GET", "suser":"test3@
bd-dev.com", "spriv":"Road Warrior", "externalId":"8106135709380313090",
"fileType":"GZIP ", "destinationServiceName":"Etsy", "cat":"Professional Services",
"deviceDirection":"1", "cn1":"10", "cn1Label":"riskscore", "cs1":"General

©2023 Zscaler, Inc. All rights reserved. 26

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

Group", "cs1Label":"dept", "cs2":"Phishing", "cs2Label":"urlcat", "cs3":"None",

"cs3Label":"malwareclass", "cs4":"None", "cs4Label":"malwarecat", "cs5":"Bad_Threat",
"cs5Label":"threatname", "cs6":"None", "cs6Label":"md5hash", "rulelabel":"None",
"ruletype":"None", "urlclass":"Advanced Security Risk", "DeviceVendor":"Zscaler" ,
"DeviceProduct":"NSSWeblog" ,"devicemodel":"Virtual Machine" , "flexString1":"Virtual
Machine", "flexString1Label":"devicemodel", "flexString2":"Advanced Security Risk",
"flexString2Label":"urlclass"},

{ "sourcetype" : "zscalernss-web", "TimeGenerated":"2023-02-17

22:55:02", "act":"Allowed", "reason":"Allowed", "app":"HTTP_PROXY",
"dhost":"c.bing.com", "dst":"204.79.197.200", "src":"40.90.198.229",
"sourceTranslatedAddress":"40.90.198.229", "in":"6500", "out":"110",
"request":"c.bing.com:443", "requestContext":"None", "outcome":"200", "re
questClientApplication":"Windows Microsoft Windows 10 Pro ZTunnel/1.0",
"requestMethod":"CONNECT", "suser":"[email protected]", "spriv":"Road
Warrior", "externalId":"7093275726860451849", "fileType":"None", "destinationSe
rviceName":"SharePoint", "cat":"Web Search", "deviceDirection":"1", "cn1":"0",
"cn1Label":"riskscore", "cs1":"Service Admin", "cs1Label":"dept", "cs2":"Web
Search", "cs2Label":"urlcat", "cs3":"None", "cs3Label":"malwareclass", "cs4":"None",
"cs4Label":"malwarecat", "cs5":"None", "cs5Label":"threatname", "cs6":"None",
"cs6Label":"md5hash", "rulelabel":"None", "ruletype":"None", "urlclass":"Business
Use", "DeviceVendor":"Zscaler" , "DeviceProduct":"NSSWeblog" , "devicemodel":"Lenovo"
, "flexString1":"Lenovo", "flexString1Label":"devicemodel", "flexString2":"Advanced
Security Risk", "flexString2Label":"urlclass" },

{ "sourcetype" : "zscalernss-web", "TimeGenerated":"2023-02-17 22:55:03",

"act":"Blocked", "reason":"Access denied due to bad server certificate", "app":"HTTP_
PROXY", "dhost":"hm.baidu.com", "dst":"103.235.46.191", "src":"52.233.90.167",
"sourceTranslatedAddress":"52.233.90.167", "in":"65", "out":"55", "request":"ps.
eyeota.net/pixel?pid=gdomg51&t=gif&cat=Economy&us_privacy=&random=1654532044229.2",
"requestContext":"None", "outcome":"200", "requestClientApplication":"Windows
Microsoft Windows 10 Pro ZTunnel/1.0", "requestMethod":"CONNECT", "suser":"test1@
bd-dev.com", "spriv":"Road Warrior", "externalId":"9346135709564534789",
"fileType":"None ", "destinationServiceName":"General Browsing", "cat":"Web Search",
"deviceDirection":"1", "cn1":"0", "cn1Label":"riskscore", "cs1":"General Group",
"cs1Label":"dept", "cs2":"Adware/Spyware Sites", "cs2Label":"urlcat", "cs3":"None",
"cs3Label":"malwareclass", "cs4":"None", "cs4Label":"malwarecat", "cs5":"None",
"cs5Label":"threatname", "cs6":"None", "cs6Label":"md5hash", "rulelabel":"Inspect_
All", "ruletype":"SSLPol", "urlclass":"Business Use", "DeviceVendor":"Zscaler" ,
"DeviceProduct":"NSSWeblog" ,"devicemodel":"macbookpro", "flexString1":"macbookpro",
"flexString1Label":"devicemodel", "flexString2":"Advanced Security Risk",
"flexString2Label":"urlclass" }]

Clipboard-list PDF files add line breaks to preserve the source text formatting. When copying code from a PDF into the Feed
Output Format, you must remove any line breaks from the text.

Copy the code text and paste it into this tool (or one similar) to remove the line breaks. When cleaned, copy the
code from the tool and paste it into the Feed Output Format.

©2023 Zscaler, Inc. All rights reserved. 27

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

Sample of Firewall Logs

[{"sourcetype":"zscaler-nss-fw", "TimeGenerated":"2022-08-15 21:47:01",
"act":"Allow", "suser":"[email protected]", "src":"10.2.3.4", "spt":"62398",
"dst":"168.63.129.16", "dpt":"53", "deviceTranslatedAddress":"165.225.242.244",
"deviceTranslatedPort":"52220", "destinationTranslatedAddress":"128.177.129.156",
"destinationTranslatedPort":"53", "sourceTranslatedAddress":"40.83.138.250",
"sourceTranslatedPort":"0", "proto":"UDP", "flexString2Label":"ttype" , "flexString2
":"ZscalerClientConnector" , "tunnelType":"ZscalerClientConnector", "dnat":"Yes",
"stateful":"Yes", "spriv":"Road Warrior", "reason":"Allow DNS", "inbytes":"141",
"out":"87", "deviceDirection":"1", "cs1":"General Group", "cs1Label":"dept"
, "cs2":"DNS", "cs2Label":"nwService" , "cs3":"dns", "cs3Label":"nwApp" ,
"cs4":"No", "cs4Label":"aggregated" , "cs5":"None", "cs5Label":"threatcat" ,
"cs6":"None", "cs6Label":"threatname" , "cn1":"2", "cn1Label":"durationms"
, "cn2":"1", "cn2Label":"numsessions" , "flexString1Label":"destCountry" ,
"flexString1":"Other", "cfp1Label":"avgduration" , "cfp1":"2", "DeviceVendor":"Zscaler"
, "DeviceProduct":"NSSFWlog"} ,

{"sourcetype":"zscaler-nss-fw", "TimeGenerated":"2022-08-15 22:48:01",

"act":"Allow due to insufficient app data", "suser":"testuser2@bd-siem.
com", "src":"10.2.3.4", "spt":"64701", "dst":"20.44.239.154", "dpt":"443",
"deviceTranslatedAddress":"165.225.242.244", "deviceTranslatedPort":"7996",
"destinationTranslatedAddress":"20.44.239.154", "destinationTranslatedPort":"443",
"sourceTranslatedAddress":"40.83.138.250", "sourceTranslatedPort":"0",
"proto":"TCP", "flexString2Label":"ttype" , "flexString2":"ZscalerClientConnec
tor" , "tunnelType":"ZscalerClientConnector", "dnat":"No", "stateful":"Yes",
"spriv":"Road Warrior", "reason":"FW Random Sites Block", "inbytes":"4111",
"out":"666", "deviceDirection":"1", "cs1":"General Group", "cs1Label":"dept"
, "cs2":"ZSCALER_PROXY_NW_SERVICES", "cs2Label":"nwService" , "cs3":"tcp",
"cs3Label":"nwApp" , "cs4":"No", "cs4Label":"aggregated" , "cs5":"None",
"cs5Label":"threatcat" , "cs6":"None", "cs6Label":"threatname" , "cn1":"28",
"cn1Label":"durationms" , "cn2":"1", "cn2Label":"numsessions" , "flexString1Label":
"destCountry" , "flexString1":"Singapore", "cfp1Label":"avgduration" , "cfp1":"28",
"DeviceVendor":"Zscaler" , "DeviceProduct":"NSSFWlog"}]

Clipboard-list PDF files add line breaks to preserve the source text formatting. When copying code from a PDF into the Feed
Output Format, you must remove any line breaks from the text.

Copy the code text and paste it into this tool (or one similar) to remove the line breaks. When cleaned, copy the
code from the tool and paste it into the Feed Output Format.

Sample of DNS Logs

[{"sourcetype":"zscaler-nss-fw","TimeGenerated":"2022-09-08 03:16:53", "suser":"user1@

bd-siem.com","act":"Req(allow),Res(allow)", "rulelabel":"Default Firewall DNS Rule"
,"cat":"Health","cs1":"General Group","cs1Label":"department","cs2":"Allow","cs2Label"
:"reqaction","cs3":"Allow","cs3Label":"resaction", "cs4":"A","cs4Label":"dns_reqtype",
"cs5":"pics.drugstore.com","cs5Label":"dns_req","cs6":"23.67.33.9","cs6Label":"dns_res
p","cn1":"1","cn1Label":"durationms", "flexString1":"Default Firewall DNS Rule","flexStr
ing1Label":"reqrulelabel","flexString2":"Default Firewall DNS Rule","flexString2Label":
"resrulelabel", "cat":"Health","src":"10.2.3.4","dst":"128.177.129.156","dpt":"53","s
priv":"Road Warrior","suid":"user1","dvchost":"es1client1","DeviceVendor":"Zscaler" ,

©2023 Zscaler, Inc. All rights reserved. 28

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

"DeviceProduct":"NSSDNSlog"},

{"sourcetype":"zscaler-nss-fw","TimeGenerated":"2022-09-08 03:16:53", "suser":"user1@

bd-siem.com","act":"Req(allow),Res(allow)", "rulelabel":"Default Firewall DNS
Rule" ,"cat":"Professional Services","cs1":"General Group","cs1Label":"departme
nt","cs2":"Allow","cs2Label":"reqaction","cs3":"Allow","cs3Label":"resaction",
"cs4":"A","cs4Label":"dns_reqtype", "cs5":"event.clientgear.com","cs5Label":"dns_
req","cs6":"47.252.78.131","cs6Label":"dns_resp","cn1":"1","cn1Label":"duratio
nms", "flexString1":"Default Firewall DNS Rule","flexString1Label":"reqrulelabe
l","flexString2":"Default Firewall DNS Rule","flexString2Label":"resrulelabel",
"cat":"Professional Services","src":"10.2.3.4","dst":"128.177.129.156","dpt":"53","sp
riv":"Road Warrior","suid":"user1","dvchost":"es1client1","DeviceVendor":"Zscaler" ,
"DeviceProduct":"NSSDNSlog"},

{"sourcetype":"zscaler-nss-fw","TimeGenerated":"2022-09-08 03:16:53", "suser":"user1@

bd-siem.com","act":"Req(allow),Res(allow)", "rulelabel":"Default Firewall DNS
Rule" ,"cat":"Professional Services","cs1":"General Group","cs1Label":"departme
nt","cs2":"Allow","cs2Label":"reqaction","cs3":"Allow","cs3Label":"resaction",
"cs4":"A","cs4Label":"dns_reqtype", "cs5":"www.storygize.net","cs5Label":"dns_re
q","cs6":"35.164.104.229","cs6Label":"dns_resp","cn1":"1","cn1Label":"duratio
nms", "flexString1":"Default Firewall DNS Rule","flexString1Label":"reqrulelabe
l","flexString2":"Default Firewall DNS Rule","flexString2Label":"resrulelabel",
"cat":"Professional Services","src":"10.2.3.4","dst":"128.177.129.156","dpt":"53","sp
riv":"Road Warrior","suid":"user1","dvchost":"es1client1","DeviceVendor":"Zscaler" ,
"DeviceProduct":"NSSDNSlog"}]
Clipboard-list PDF files add line breaks to preserve the source text formatting. When copying code from a PDF into the Feed
Output Format, you must remove any line breaks from the text.

Copy the code text and paste it into this tool (or one similar) to remove the line breaks. When cleaned, copy the
code from the tool and paste it into the Feed Output Format.

After you upload the sample file, the logs populate in the Create a custom log wizard and a success message
appears.

Figure 36. Upload workspace logs

©2023 Zscaler, Inc. All rights reserved. 29

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

h. Click Transformation editor. A Logs window is displayed.

Figure 37. Transformation editor button

i. In the Logs window:

i. Kusto Query Language (KQL) is a schema that identifies how Microsoft Sentinel maps the log data to different
columns in your log table. Copy one of the following KQLs based on your desired log type and paste it into
the editor.
ii. Web Logs KQL:
source | project TimeGenerated,

DeviceCustomString1Label = tostring(cs1Label) , DeviceCustomString1 = tostring(cs1) ,

DeviceCustomString2Label = tostring(cs2Label) , DeviceCustomString2 = tostring(cs2) ,

DeviceCustomString3Label = tostring(cs3Label) , DeviceCustomString3 = tostring(cs3) ,

DeviceCustomString4Label = tostring(cs4Label) , DeviceCustomString4 = tostring(cs4) ,

DeviceCustomString5Label = tostring(cs5Label) , DeviceCustomString5 = tostring(cs5) ,

DeviceCustomString6Label = tostring(cs6Label) , DeviceCustomString6 = tostring(cs6) ,

DeviceCustomNumber1Label = tostring(cn1Label) , DeviceCustomNumber1 = toint(cn1) ,

FlexString1Label = tostring(flexString1Label) , FlexString1 = tostring(flexString1) ,

FlexString2Label = tostring(flexString2Label) , FlexString2 = tostring(flexString2) ,

requestContext = tostring(requestContext),

DeviceAction = tostring(act) ,

ApplicationProtocol = tostring(app) ,

DestinationHostName = tostring(dhost) ,

DestinationIP = tostring(dst) ,

SourceIP = tostring(src) ,

RequestURL = tostring(request),

out = toint(out),

SentBytes = tolong(out),

ReceivedBytes = tolong("in"),

RequestClientApplication = tostring(requestClientApplication),

©2023 Zscaler, Inc. All rights reserved. 30

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

RequestMethod = tostring(requestMethod),

SourceUserName = tostring(suser),

SourceUserPrivileges = tostring(spriv),

ExternalID = toint(externalId),

ExtID = tostring(externalId),

FileType = tostring(fileType),

DestinationServiceName = tostring(destinationServiceName),

CommunicationDirection = tostring(deviceDirection),

rulelabel = tostring(rulelabel) ,

ruletype = tostring(ruletype),

urlclass = tostring(urlclass),

devicemodel = tostring(devicemodel),

DeviceVendor = tostring(DeviceVendor),

DeviceProduct = tostring(DeviceProduct),

DeviceEventClassID=tostring(act),

EventOutcome = tostring(outcome) ,

Reason = tostring(reason) ,

Activity = tostring(reason),

SourceTranslatedAddress = tostring(sourceTranslatedAddress)

Clipboard-list PDF files add line breaks to preserve the source text formatting. When copying code from a PDF into the Feed
Output Format, you must remove any line breaks from the text.

Copy the code text and paste it into this tool (or one similar) to remove the line breaks. When cleaned, copy the
code from the tool and paste it into the Feed Output Format.

©2023 Zscaler, Inc. All rights reserved. 31

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

iii. Firewall Logs KQL:

source | project TimeGenerated,

DeviceCustomString1Label = tostring(cs1Label) , DeviceCustomString1 = tostring(cs1) ,

DeviceCustomString2Label = tostring(cs2Label) , DeviceCustomString2 = tostring(cs2) ,

DeviceCustomString3Label = tostring(cs3Label) , DeviceCustomString3 = tostring(cs3) ,

DeviceCustomString4Label = tostring(cs4Label) , DeviceCustomString4 = tostring(cs4) ,

DeviceCustomString5Label = tostring(cs5Label) , DeviceCustomString5 = tostring(cs5) ,

DeviceCustomString6Label = tostring(cs6Label) , DeviceCustomString6 = tostring(cs6) ,

DeviceCustomNumber1Label = tostring(cn1Label) , DeviceCustomNumber1 = toint(cn1) ,

DeviceCustomNumber2Label = tostring(cn2Label) , DeviceCustomNumber2 = toint(cn2) ,

deviceCustomFloatingPoint1Label = tostring(cfp1Label) , DeviceCustomFloatingPoint1 =

toreal(cfp1),

FlexString1Label = tostring(flexString1Label) , FlexString1 = tostring(flexString1),

FlexString2Label = tostring(flexString2Label) , FlexString2 = tostring(flexString2),

DeviceAction = tostring(act) ,

DeviceEventClassID=tostring(act) ,

DestinationIP = tostring(dst) ,

SourceIP = tostring(src) ,

SourcePort = toint(spt) ,

DestinationPort = toint(dpt) ,

DeviceTranslatedAddress = tostring(deviceTranslatedAddress),

SourceTranslatedAddress = tostring(sourceTranslatedAddress),

DestinationTranslatedAddress = tostring(destinationTranslatedAddress),

DestinationTranslatedPort = toint(destinationTranslatedPort),

SourceTranslatedPort = toint(sourceTranslatedPort),

DeviceTranslatedPort = toint(deviceTranslatedPort),

SentBytes = tolong(out),

ReceivedBytes = tolong(inbytes),

Protocol = tostring(proto),

SourceUserName = tostring(suser),

SourceUserPrivileges = tostring(spriv),

©2023 Zscaler, Inc. All rights reserved. 32

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

CommunicationDirection = tostring(deviceDirection),

rulelabel = tostring(reason) ,

DeviceVendor = tostring(DeviceVendor),

DeviceProduct = tostring(DeviceProduct),

Activity = tostring(act),

Reason = tostring(reason)

Clipboard-list PDF files add line breaks to preserve the source text formatting. When copying code from a PDF into the Feed
Output Format, you must remove any line breaks from the text.

Copy the code text and paste it into this tool (or one similar) to remove the line breaks. When cleaned, copy the
code from the tool and paste it into the Feed Output Format.

iv. DNS Logs KQL:

source | project TimeGenerated,

DeviceCustomString1Label = tostring(cs1Label) , DeviceCustomString1 = tostring(cs1) ,

DeviceCustomString2Label = tostring(cs2Label) , DeviceCustomString2 = tostring(cs2) ,

DeviceCustomString3Label = tostring(cs3Label) , DeviceCustomString3 = tostring(cs3) ,

DeviceCustomString4Label = tostring(cs4Label) , DeviceCustomString4 = tostring(cs4) ,

DeviceCustomString5Label = tostring(cs5Label) , DeviceCustomString5 = tostring(cs5) ,

DeviceCustomString6Label = tostring(cs6Label) , DeviceCustomString6 = tostring(cs6) ,

DeviceCustomNumber1Label = tostring(cn1Label) , DeviceCustomNumber1 = toint(cn1) ,

FlexString1Label = tostring(flexString1Label) , FlexString1 = tostring(flexString1),

FlexString2Label = tostring(flexString2Label) , FlexString2 = tostring(flexString2),

SourceUserName = tostring(suser),

DeviceAction = tostring(act) ,

DeviceEventClassID=tostring(act) ,

DestinationIP = tostring(dst) ,

SourceIP = tostring(src) ,

SourceUserPrivileges = tostring(spriv),

DestinationPort = toint(dpt) ,

rulelabel = tostring(rulelabel) ,

DeviceVendor = tostring(DeviceVendor),

DeviceProduct = tostring(DeviceProduct),

©2023 Zscaler, Inc. All rights reserved. 33

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

DeviceName = tostring(dvchost),

Activity = tostring(act),

Reason = tostring(rulelabel),

cat = tostring(cat),

SourceUserID = tostring(suid)

Clipboard-list PDF files add line breaks to preserve the source text formatting. When copying code from a PDF into the Feed
Output Format, you must remove any line breaks from the text.

Copy the code text and paste it into this tool (or one similar) to remove the line breaks. When cleaned, copy the
code from the tool and paste it into the Feed Output Format.

j. Click Run.
k. Click Apply. You are redirected to the Create a custom log wizard.

Figure 38. Run logs

l. Click Next.

©2023 Zscaler, Inc. All rights reserved. 34

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

m. Click Create.

Figure 39. Create custom log wizard

You are redirected to the Tables page in your workspace and a success message appears.

Step 5. Using Azure Cloud Shell, Change the Table’s Output Stream
In this step, you make two REST API calls: GET to fetch your table’s properties and PUT to change the table’s outputStream
so that logs are sent to a Common Event Format (CEF) table instead of a custom log (CL) table. To make the API calls:

1. Go to Monitor.
2. In the left-side navigation, go to Settings > Data Collection Rules.

Figure 40. Data Collection Rules

©2023 Zscaler, Inc. All rights reserved. 35

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

3. Select your DCR (e.g., test-1-DCR).

Figure 41. Monitor DCR rules

4. Click JSON View.

Figure 42. DCR JSON view

The Resource JSON window appears.

5. In the Resource JSON window:
a. Copy the Resource ID of the DCR.
b. Select 2021-09-01 preview from the API version drop-down menu.

Figure 43. Monitor Resource JSON

c. Copy the ImmutableId value and _CL table name and save for later use in adding a Cloud NSS feed in the ZIA
Admin Portal.

Figure 44. Resource JSON ImmutableId and _CL

6. Open Azure Cloud Shell.

Figure 45. Azure Cloud Shell

7. Set the environment to PowerShell.

©2023 Zscaler, Inc. All rights reserved. 36
 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

Figure 46. Azure Cloud PowerShell

8. Paste the Resource ID of your DCR in the Cloud Shell prompt. See the following example.
subscriptions/XX97bd2b-d3ea-4XXX-8f78-81962bea4bXX/resourceGroups/test-1-RG/providers/
Microsoft.Insights/dataCollectionRules/test-1-DCR?api-version=2021-09-01-preview

9. Run the following GET command to fetch table properties.

Invoke-AzRestMethod -Path "Resource ID" -Method GET

Figure 47. DCR Get command

See the following example output.

Figure 48. DCR Get output

10. Assign the output to a variable (e.g., $v1) and run the $v1.Content command.

Figure 49. DCR variable output

11. Copy the entire output and paste it into a text editor. Paste the output as plain text to prevent formatting issues.
12. In the text editor, modify the value of outputStream from your custom log table name to Microsoft-
CommonSecurityLog.
For example, "outputStream": "Custom-table_1_web_CL" is modified to the following: "outputStream":
"Microsoft-CommonSecurityLog".
13. Copy the entire modified output in the text editor.

©2023 Zscaler, Inc. All rights reserved. 37

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

14. In Cloud Shell, assign a second variable (e.g., $v2), then paste the modified output into the prompt. Ensure that you
add single quotes (‘) around the pasted content.

Figure 50. DCR second variable output

15. Run the following PUT command to change the outputStream.

Invoke-AzRestMethod -Path "Resource ID" -Method PUT -payload $v2

Figure 51. DCR Put command

See the following example output.

Figure 52. DCR Put command output

16. Run the same GET command to ensure the outputStream value shows Microsoft-CommonSecurityLog.

Figure 53. DCR Get command verify

See the following example output.

Figure 54. DCR Get output for commonsecuritylog

©2023 Zscaler, Inc. All rights reserved. 38

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

Step 6. In the Azure Portal, Assign Permissions to the DCR

To assign permissions to the DCR in Azure:

1. In Monitor > Data Collection Rules, select the DCR you created (e.g., test-1-DCR).

Figure 55. Monitor DCR

2. In the left-side navigation, select Access control (IAM).

Figure 56. Monitor IAC menu

3. Click Add role assignment.

Figure 57. Add role assignment

The Add role assignment wizard appears.

©2023 Zscaler, Inc. All rights reserved. 39

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

4. In the Add role assignment wizard:

a. Select Monitoring Metrics Publisher. The Select members window is displayed.

Figure 58. Monitoring Metrics Publisher

b. Click Next.
c. Click Select members.

Figure 59. DCR Add role assignment

©2023 Zscaler, Inc. All rights reserved. 40

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

d. In the Select members window, search for and select the Azure AD application you created (e.g., test-1-app).
You might need to type the app name in its entirety if it does not display in the drop-down menu.

Figure 60. Select members

e. Click Close to close the window.

f. Click Review + assign.

Figure 61. Review + assign

You are redirected to the Access control (IAM) page and a success message appears.

©2023 Zscaler, Inc. All rights reserved. 41

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

Configuring ZIA for Cloud NSS-Based Log Export

The following steps demonstrate how to configure ZIA for cloud NSS-based log export.

Step 1. In the ZIA Admin Portal, Add a Cloud NSS Feed

See Adding Cloud NSS Feeds and select the type of feed (e.g., Web Logs) that you want to add. The following fields
require specific inputs:

• SIEM Type: Select Azure Sentinel.

• OAuth 2.0 Authentication: Enabled by default. The toggle is not editable.
• Client ID: Enter the Application (client) ID generated in the Azure Portal.
• Client Secret: Enter the application client secret value generated in the Azure Portal.
• Scope: Enter the following URL: https://monitor.azure.com//.default
• Grant Type: Enter the following string: client_credentials
• Authorization URL: Enter the authorization URL with the Directory (tenant) ID generated in the Azure Portal (e.g.,
https://login.microsoftonline.com/$tenantid/oauth2/v2.0/token). Replace $tenantid in the URL
with your Directory (tenant) ID from your deployment.
• API URL: Enter the API URL using the following format:
$dceEndpoint/dataCollectionRules/$dcrImmutableId/streams/Custom-table_name_CL?api-
version=2021-11-01-preview

Replace the values shown in red with those from your deployment:
https://test-1-dce-XXw5.eastus-1.ingest.monitor.azure.com/dataCollectionRules/dcr-
XXabc28ce0514dXXX55766bdc7328XX/streams/Custom-table_1_web_CL?api-version=2021-11-01-
preview)

• HTTP Headers:
• Key 1: Enter Content-Type
• Value 1: Enter application/json
• Feed Output Type: Select JSON.
• JSON Array Notation: Enable this setting.
• Feed Escape Character: Enter "\,

Clipboard-list PDF files add line breaks to preserve the source text formatting. When copying code from a PDF into the Feed
Output Format, you must remove any line breaks from the text.

Copy the code text and paste it into this tool (or one similar) to remove the line breaks. When cleaned, copy the
code from the tool and paste it into the Feed Output Format.

©2023 Zscaler, Inc. All rights reserved. 42

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

• Feed Output Format: See the following feed output formats by log type.
• For Cloud NSS Feeds for Web Logs, copy and paste the pre-populated Feed Output Format with the following:
\{"sourcetype" : "zscalernss-web", "TimeGenerated":"%d{yy}-%02d{mth}-%02d{dd}
%02d{hh}:%02d{mm}:%02d{ss}", "act":"%s{action}", "reason":"%s{reason}",
"app":"%s{proto}", "dhost":"%s{ehost}", "dst":"%s{sip}", "src":"%s{cip}", "sou
rceTranslatedAddress":"%s{cintip}", "in":"%d{respsize}", "out":"%d{reqsize}",
"request":"%s{eurl}", "requestContext":"%s{ereferer}", "outcome":"%s{respcode}", "requ
estClientApplication":"%s{ua}", "requestMethod":"%s{reqmethod}", "suser":"%s{login}",
"spriv":"%s{location}", "externalId":"%d{recordid}", "fileType":"%s{filetype} ", "de
stinationServiceName":"%s{appname}", "cat":"%s{urlcat}", "deviceDirection":"1",
"cn1":"%d{riskscore}", "cn1Label":"riskscore", "cs1":"%s{dept}", "cs1Label":"dept",
"cs2":"%s{urlcat}", "cs2Label":"urlcat", "cs3":"%s{malwareclass}",
"cs3Label":"malwareclass", "cs4":"%s{malwarecat}", "cs4Label":"malwarecat",
"cs5":"%s{threatname}", "cs5Label":"threatname", "cs6":"%s{bamd5}",
"cs6Label":"md5hash", "rulelabel":"%s{rulelabel}", "ruletype":"%s{ruletype}",
"urlclass":"%s{urlclass}", "DeviceVendor":"Zscaler" , "DeviceProduct":"NSSWeblog" ,"de
vicemodel":"%s{devicemodel}", "flexString1":"%s{devicemodel}", "flexString1Label":"devic
emodel", "flexString2":"%s{urlclass}", "flexString2Label":"urlclass"\}

Figure 62. Add Cloud NSS Feed

©2023 Zscaler, Inc. All rights reserved. 43

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

• For Cloud NSS Feeds for Firewall Logs, copy and paste the pre-populated Feed Output Format with the
following:
\{ "sourcetype" : "zscaler-nss-fw", "TimeGenerated":"%02d{yy}-%02d{mth}-
%02d{dd} %02d{hh}:%02d{mm}:%02d{ss}", "act":"%s{action}", "suser":"%s{login}",
"src":"%s{csip}", "spt":"%d{csport}", "dst":"%s{cdip}", "dpt":"%d{cdport}", "deviceT
ranslatedAddress":"%s{ssip}", "deviceTranslatedPort":"%d{ssport}", "destinationTran
slatedAddress":"%s{sdip}", "destinationTranslatedPort":"%d{sdport}", "sourceTransla
tedAddress":"%s{tsip}", "sourceTranslatedPort":"%d{tsport}", "proto":"%s{ipproto}",
"flexString2Label":"ttype" , "flexString2":"%s{ttype}", "dnat":"%s{dnat}",
"stateful":"%s{stateful}", "spriv":"%s{location}", "reason":"%s{rulelabel}",
"inbytes":"%ld{inbytes}", "out":"%ld{outbytes}", "deviceDirection":"1",
"cs1":"%s{dept}", "cs1Label":"dept" , "cs2":"%s{nwsvc}", "cs2Label":"nwService" ,
"cs3":"%s{nwapp}", "cs3Label":"nwApp" , "cs4":"%s{aggregate}", "cs4Label":"aggregated"
, "cs5":"%s{threatcat}", "cs5Label":"threatcat" , "cs6":"%s{threatname}",
"cs6Label":"threatname" , "cn1":"%d{durationms}", "cn1Label":"durationms" ,
"cn2":"%d{numsessions}", "cn2Label":"numsessions" , "flexString1Label":"destCountry" ,
"flexString1":"%s{destcountry}", "cfp1Label":"avgduration" , "cfp1":"%d{avgduration}",
"DeviceVendor":"Zscaler" , "DeviceProduct":"NSSFWlog"\}

Figure 63. Add Cloud NSS Feed for Firewall

©2023 Zscaler, Inc. All rights reserved. 44

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

• For Cloud NSS Feeds for DNS Logs, copy and paste the pre-populated Feed Output Format with the
following:
\{"sourcetype":"zscaler-nss-fw","TimeGenerated":"%02d{yy}-%02d{mth}-%02d{dd}
%02d{hh}:%02d{mm}:%02d{ss}", "suser":"%s{login}","act":"%s{action}", "rulelabel":
"%s{rulelabel}" ,"cat":"%s{domcat}", "cs1":"%s{dept}","cs1Label":"department",
"cs2":"%s{reqaction}","cs2Label":"reqaction","cs3":"%s{resaction}","cs3Label":
"resaction","cs4":"%s{reqtype}","cs4Label":"dns_reqtype","cs5":"%s{req}","cs5Label":
"dns_req","cs6":"%s{res}","cs6Label":"dns_resp","cn1":"%d{durationms}","cn1Label":
"durationms","flexString1":"%s{reqrulelabel}","flexString1Label":"reqrulelabel","fl
exString2":"%s{resrulelabel}","flexString2Label":"resrulelabel", "cat":"%s{domcat
}","src":"%s{cip}","dst":"%s{sip}", "dpt":"%d{sport}","spriv":"%s{location}","su
id":"%s{deviceowner}", "dvchost":"%s{devicehostname}","DeviceVendor":"Zscaler" ,
"DeviceProduct":"NSSDNSlog"\}

Figure 64. Add Cloud NSS Feed for DNS

Clipboard-list PDF files add line breaks to preserve the source text formatting. When copying code from a PDF into the Feed
Output Format, you must remove any line breaks from the text.

Copy the code text and paste it into this tool (or one similar) to remove the line breaks. When cleaned, copy the
code from the tool and paste it into the Feed Output Format.

©2023 Zscaler, Inc. All rights reserved. 45

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

(Optional) Using PowerShell, Verify Log Data Arrives at the Endpoint

You can manually push log data to the endpoint to verify your deployment and confirm that the Sentinel credentials are
correct. Refer to the PowerShell script in the Microsoft documentation. The following is an example. Replace the values
shown in red with those from the resources you created in the Azure Portal.

##################

### Step 0: set parameters required for the rest of the script

##################

#information needed to authenticate to AAD and obtain a bearer token

$tenantId = "XX-XX-XX-8330-d05f70XX"; #Tenant ID the data collection endpoint resides

in

$appId = "XXX-XX-4da9-bb7d-ba39bXXX"; #Application ID created and granted permissions

$appSecret = "XXXc6XJmEJ5vJBnl2B8v3Vu-a5H8XXX"; #Secret created for the application

#information needed to send data to the DCR endpoint

$dcrImmutableId = "dcr-XX20dfb3018XX"; #the immutableId property of the DCR object

$dceEndpoint = "https://testnss3-dce-XX-1.ingest.monitor.azure.com"; #the endpoint

property of the Data Collection Endpoint object

##################

### Step 1: obtain a bearer token used later to authenticate against the DCE

##################

$scope= [System.Web.HttpUtility]::UrlEncode("https://monitor.azure.com//.default")

$body = "client_id=$appId&scope=$scope&client_secret=$appSecret&grant_type=client_
credentials";

$headers = @{"Content-Type"="application/x-www-form-urlencoded"};

$uri = "https://login.microsoftonline.com/$tenantId/oauth2/v2.0/token"

$bearerToken = (Invoke-RestMethod -Uri $uri -Method "Post" -Body $body -Headers

$headers).access_token

##################

### Step 2: Load up some sample data.

##################

$currentTime = Get-Date ([datetime]::UtcNow) -Format O

$staticData = @"

[{ "sourcetype" : "zscalernss-web", "TimeGenerated":"2023-03-17 15:01:21",

"act":"Blocked", "reason":"Blocked", "app":"HTTPS", "dhost":"www.etsy.com",
"dst":"104.94.233.143", "src":"40.83.138.250", "sourceTranslatedAddress":"10.2.3.4",

©2023 Zscaler, Inc. All rights reserved. 46

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

"in":"50", "out":"10", "request":"www.1etsy.com/dac/common/web-toolkit/

scoped/scoped_responsive_base.20220526203537%2csite-chrome/deprecated/global-
nav.20220526203537%2ccommon/web-toolkit/a11y_colors/overrides.20220526203537.
css", "requestContext":"www.1etsy.com/c/clothing-and-shoes?ref=catnav-10923",
"outcome":"200", "requestClientApplication":"Mozilla/5.0 (Windows NT 6.2; Win64; x64;
rv:16.0.1) Gecko/20121011 Firefox/21.0.1", "requestMethod":"GET", "suser":"testuser2@
bd-dev.com", "spriv":"Road Warrior", "externalId":"8106135709380313090",
"fileType":"GZIP ", "destinationServiceName":"Etsy", "cat":"Professional Services",
"deviceDirection":"1", "cn1":"10", "cn1Label":"riskscore", "cs1":"General
Group", "cs1Label":"dept", "cs2":"Phishing", "cs2Label":"urlcat", "cs3":"None",
"cs3Label":"malwareclass", "cs4":"None", "cs4Label":"malwarecat", "cs5":"Bad_Threat",
"cs5Label":"threatname", "cs6":"None", "cs6Label":"md5hash", "rulelabel":"None",
"ruletype":"None", "urlclass":"Advanced Security Risk", "DeviceVendor":"Zscaler" ,
"DeviceProduct":"NSSWeblog" ,"devicemodel":"Virtual Machine" , "flexString1":"Virtual
Machine", "flexString1Label":"devicemodel", "flexString2":"Advanced Security Risk",
"flexString2Label":"urlclass"},

{ "sourcetype" : "zscalernss-web", "TimeGenerated":"2023-03-17

01:45:22", "act":"Allowed", "reason":"Allowed", "app":"HTTP_PROXY",
"dhost":"c.bing.com", "dst":"204.79.197.200", "src":"40.90.198.229",
"sourceTranslatedAddress":"40.90.198.229", "in":"6500", "out":"110",
"request":"c.bing.com:443", "requestContext":"None", "outcome":"200", "re
questClientApplication":"Windows Microsoft Windows 10 Pro ZTunnel/1.0",
"requestMethod":"CONNECT", "suser":"[email protected]", "spriv":"Road
Warrior", "externalId":"7093275726860451849", "fileType":"None", "destinationSe
rviceName":"SharePoint", "cat":"Web Search", "deviceDirection":"1", "cn1":"0",
"cn1Label":"riskscore", "cs1":"Service Admin", "cs1Label":"dept", "cs2":"Web
Search", "cs2Label":"urlcat", "cs3":"None", "cs3Label":"malwareclass", "cs4":"None",
"cs4Label":"malwarecat", "cs5":"None", "cs5Label":"threatname", "cs6":"None",
"cs6Label":"md5hash", "rulelabel":"None", "ruletype":"None", "urlclass":"Business
Use", "DeviceVendor":"Zscaler" , "DeviceProduct":"NSSWeblog" , "devicemodel":"Lenovo"
, "flexString1":"Lenovo", "flexString1Label":"devicemodel", "flexString2":"Advanced
Security Risk", "flexString2Label":"urlclass" },

{ "sourcetype" : "zscalernss-web", "TimeGenerated":"2023-03-17 02:38:23",

"act":"Blocked", "reason":"Access denied due to bad server certificate", "app":"HTTP_
PROXY", "dhost":"hm.baidu.com", "dst":"103.235.46.191", "src":"52.233.90.167",
"sourceTranslatedAddress":"52.233.90.167", "in":"65", "out":"55", "request":"ps.
eyeota.net/pixel?pid=gdomg51&t=gif&cat=Economy&us_privacy=&random=1654532044229.2",
"requestContext":"None", "outcome":"200", "requestClientApplication":"Windows
Microsoft Windows 10 Pro ZTunnel/1.0", "requestMethod":"CONNECT", "suser":"testuser2@
bd-dev.com", "spriv":"Road Warrior", "externalId":"9346135709564534789",
"fileType":"None ", "destinationServiceName":"General Browsing", "cat":"Web Search",
"deviceDirection":"1", "cn1":"0", "cn1Label":"riskscore", "cs1":"General Group",
"cs1Label":"dept", "cs2":"Adware/Spyware Sites", "cs2Label":"urlcat", "cs3":"None",
"cs3Label":"malwareclass", "cs4":"None", "cs4Label":"malwarecat", "cs5":"None",
"cs5Label":"threatname", "cs6":"None", "cs6Label":"md5hash", "rulelabel":"Inspect_
All", "ruletype":"SSLPol", "urlclass":"Business Use", "DeviceVendor":"Zscaler" ,
"DeviceProduct":"NSSWeblog" ,"devicemodel":"macbookpro", "flexString1":"macbookpro",
"flexString1Label":"devicemodel", "flexString2":"Advanced Security Risk",
"flexString2Label":"urlclass" }]

©2023 Zscaler, Inc. All rights reserved. 47

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

"@;

##################

### Step 3: send the data to Log Analytics via the DCE.

##################

$body = $staticData;

$headers = @{"Authorization"="Bearer $bearerToken";"Content-Type"="application/json"};

$uri = "$dceEndpoint/dataCollectionRules/$dcrImmutableId/streams/Custom-XXnss3_table_
CL?api-version=2021-11-01-preview"

$uploadResponse = Invoke-RestMethod -Uri $uri -Method "Post" -Body $body -Headers

$headers

#Invoke-WebRequest -UseBasicParsing -Uri $uri -Method "Post" -Body $body -Headers

$headers

©2023 Zscaler, Inc. All rights reserved. 48

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

In Microsoft Sentinel, View Log Details

After running your script in PowerShell, you can view log details in Microsoft Sentinel:

1. In Microsoft Sentinel, select your Log Analytics workspace (e.g., test-1-WS).

2. In the left-side navigation, select Logs. Wait until the Queries History populates with logs.

Figure 65. Queries History

3. Click Run.

Figure 66. Microsoft Sentinel Logs Queries History

Query Results display after a few minutes.

Figure 67. Log Query Results

©2023 Zscaler, Inc. All rights reserved. 49

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

4. Return to your Log Analytics workspace and click Workbooks in the left-side navigation.

Figure 68. Workbooks menu

5. On the Templates tab, search for a Zscaler workbook among the following:
a. Zscaler Firewall
b. Zscaler Office 365 Apps
c. Zscaler Threats
d. Zscaler Web Overview
6. Click Save to save the workbook to a location (e.g., East US).

Figure 69. Save Workbook

©2023 Zscaler, Inc. All rights reserved. 50

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

7. Select the My workbooks tab, then click View saved workbook.

Figure 70. View saved workbook

8. View the log data visualizations in the Zscaler workbook.

Figure 71. Data visualizations in Zscaler workbook

©2023 Zscaler, Inc. All rights reserved. 51

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

Configuring ZIA for NSS VM-Based Log Export

The following sections describe how to configure ZIA to work with NSS.

Logging in to ZIA
First, set up the Zscaler side of this service. Log in to Zscaler using your administrator account. If you are unable to log in
using your administrator account, contact Zscaler Support.

Figure 72. ZIA Admin Portal

Configuring NSS

exclamation-triangle Log messages sent between Zscaler NSS and Azure data connector are not encrypted.

Zscaler strongly recommends that you spin up your NSS in the same Vnet as the Azure data connector VM so
that plain text log messages traffic doesn’t leave your Vnet.

If you are deploying NSS in a different network, use an external mechanism (e.g., IPSec tunnel) to encrypt plain
text communication between NSS and the Azure data connector VM.

©2023 Zscaler, Inc. All rights reserved. 52

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

Configuring NSS
AfterIflogging
you areinto ZIA, adda an
deploying newNSS
NSSserver and NSS feed. To navigate to the Nanolog Streaming section of ZIA:
in Azure:
Clipboard-list
Go to Administration
1. Zscaler > Cloud
NSS Azure Resource Configuration
Manager > Nanolog
(ARM) Template wasStreaming
developedService.
to automate setting up an NSS in Azure.
This avoids the need for manually running PowerShell scripts.
2. Follow the instructions in the NSS Deployment Guide help (based on your deployment type) to set up web and
firewall NSS.can take up to one hour to finish.
Deployment

Access the Zscaler NSS ARM Template from the Zscaler GitHub repository.

After deploying the ARM template deployment, check the IP address using "ifconfig -a". Configure another IP in
the same network range. NSS requires two interfaces in same subnet.

Connect to the NSS VM using SSH and execute the following commands as root user. Change the IPs as needed
to fit your environment.

Figure 73. Navigate to NSS

©2023 Zscaler, Inc. All rights reserved. 53

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

Verify NSS Server State

Before proceeding to further steps, ensure that NSS State is Healthy. If NSS is Unhealthy, see the troubleshooting steps
listed in Zscaler Resources. If everything is as expected, proceed to the next section.

Figure 74. Verify NSS server state in the ZIA Admin Portal

Add NSS Feed

An NSS feed specifies what data from the logs that the NSS sends to the SIEM. Each feed can have a different list of fields,
a different format, and different filters. You can add one or more fields for the logs and one field for alerts.

Figure 75. Add NSS feed in the ZIA Admin Portal

©2023 Zscaler, Inc. All rights reserved. 54

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

Configure NSS Feed

To configure the NSS feed, ensure you complete the following required fields:

1. SIEM IP Address: The public IPv4 address of your Microsoft Sentinel data connector.
2. SIEM TCP Port: 514.
3. Feed Output Type: Set to Custom from the drop-down menu.
4. In this version of ZIA (v5.7 or later), the feed format must interoperate with Sentinel. Refer to Edit NSS Feed (Web) for
the details.

Figure 76. Configure NSS feed

Clipboard-list When configuring the log feed to Sentinel, add ",\= to the Feed Escape Character field.

Edit NSS Feed (Web)

Override the prepopulated CEF feed by replacing it with the following block and then click Save.

%s{mon} %02d{dd} %02d{hh}:%02d{mm}:%02d{ss} zscaler-nss CEF:0|Zscaler|NSSWeblog|5.7|%s

{action}|%s{reason}|3| act=%s{action} reason=%s{reason} app=%s{proto} dhost=%s{ehost}
dst=%s{sip} src=%s{cip} sourceTranslatedAddress=%s{cintip} in=%d{respsize}
out=%d{reqsize} request=%s{eurl} requestContext=%s{ereferer} outcome=%s{respcode}
requestClientApplication=%s{ua} requestMethod=%s{reqmethod} suser=%s{login}
spriv=%s{location} externalId=%d{recordid} fileType=%s{filetype} destinationServiceNam
e=%s{appname} cat=%s{urlcat} deviceDirection=1 cn1=%d{riskscore} cn1Label=riskscore
cs1=%s{dept} cs1Label=dept cs2=%s{urlcat} cs2Label=urlcat cs3=%s{malwareclass}
cs3Label=malwareclass cs4=%s{malwarecat} cs4Label=malwarecat cs5=%s{threatname}
cs5Label=threatname cs6Label=%s{bamd5} cs6=md5hash rulelabel=%s{rulelabel}
ruletype=%s{ruletype} urlclass=%s{urlclass} devicemodel=%s{devicemodel}\n

©2023 Zscaler, Inc. All rights reserved. 55

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

Edit NSS Feed (Firewall)

Override the prepopulated CEF feed by replacing it with the following block and then click Save.

%s{mon} %02d{dd} %02d{hh}:%02d{mm}:%02d{ss} zscaler-nss-fw CEF:0|Zscaler|NSSFWl

og|5.7|%s{action}|%s{rulelabel}|3| act=%s{action} suser=%s{login} src=%s{csip}
spt=%d{csport} dst=%s{cdip} dpt=%d{cdport} deviceTranslatedAddress=%s{ssip}
deviceTranslatedPort=%d{ssport} destinationTranslatedAddress=%s{sdip} destinationTrans
latedPort=%d{sdport} sourceTranslatedAddress=%s{tsip} sourceTranslatedPort=%d{tsport}
proto=%s{ipproto} tunnelType=%s{ttype} dnat=%s{dnat} stateful=%s{stateful}
spriv=%s{location} reason=%s{rulelabel} in=%ld{inbytes} out=%ld{outbytes}
deviceDirection=1 cs1=%s{dept} cs1Label=dept cs2=%s{nwsvc} cs2Label=nwService
cs3=%s{nwapp} cs3Label=nwApp cs4=%s{aggregate} cs4Label=aggregated cs5=%s{threatcat}
cs5Label=threatcat cs6=%s{threatname} cs6label=threatname cn1=%d{durationms}
cn1Label=durationms cn2=%d{numsessions} cn2Label=numsessions cs5Label=ipCat
cs5=%s{ipcat} destCountry=%s{destcountry} avgduration=%d{avgduration}\n

Edit NSS Feed (DNS)

Override the prepopulated CEF feed by replacing it with the following block and then click Save.

%s{mon} %02d{dd} %02d{hh}:%02d{mm}:%02d{ss} zscaler-nss-fw CEF:0|Zscaler|NSSDNSlog

|5.7|%s{action}|%s{rulelabel}|3| suser=%s{login} cs1=%s{dept} cs1Label=department
cs2=%s{reqaction} cs2Label=reqaction cs3=%s{resaction} cs3Label=resaction
cs4=%s{reqtype} cs4Label=dns_reqtype cs5=%s{req} cs5Label=dns_req cs6=%s{res}
cs6Label=dns_resp cn1=%d{durationms} cn1Label=durationms flexString1=%s{reqrulelabel}
flexString1Label=reqrulelabel flexString2=%s{resrulelabel} flexString2Label=resrulelabel
cat=%s{domcat} src=%s{cip} dst=%s{sip} dpt=%d{sport} spriv=%s{location}
suid=%s{deviceowner} dvchost=%s{devicehostname}\n

©2023 Zscaler, Inc. All rights reserved. 56

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

Activate your changes

The last step on the Zscaler side is to activate the configuration. All configurations up to this point are candidate
configurations. The activated changes become active in production.

Go to Activation from the left-side navigation, and then click Activate to commit your changes.

Figure 77. Activate your change

©2023 Zscaler, Inc. All rights reserved. 57

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

Configuring Sentinel for NSS VM-Based Log Ingestion

The following steps assume that you have Admin access to the Azure Portal.

Log in to Azure Portal

Normally you would navigate to the Azure portal and sign in using your account. To enable Private Preview of the Zscaler
Data Connector, refer to the redirect to the Azure portal.

Figure 78. Sign in to Azure Portal

©2023 Zscaler, Inc. All rights reserved. 58

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

Deploy the Data Connector Host VM

The first step in Azure is to deploy a Linux VM. This Linux VM is the Zscaler data connector and runs Microsoft’s
Operations Management Suite (OMS) agent. The OMS agent is the software component that sends log messages to
Microsoft Sentinel. There are more software components on this VM that enable this data pipeline. These components
are automatically configured by Azure.

After navigating to the Home screen, click Virtual machines.

Figure 79. This VM is a Syslog server and runs Azure’s data connector

©2023 Zscaler, Inc. All rights reserved. 59

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

Create Virtual Machine

Your Virtual machines screen might have additional information displayed if you have existing virtual machines. Click
Create virtual machine.

Figure 80. Create virtual machine in Microsoft Azure

©2023 Zscaler, Inc. All rights reserved. 60

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

Bind this VM to a Resource Group

A Resource Group (RG) is a way to group a collection of assets in logical containers for automatic provisioning, monitoring,
access control, and more effective management of their costs. One benefit of using RGs is to group related application
resources together, as they share a unified lifecycle from creation, usage, and de-provisioning.

You can select an existing resource group or you can create a new one.

1. To create a new resource group, click Create new, and give it a name. This example uses Ubuntu Server 18.04 LTS.

Figure 81. Initiate VM deployment

2. Fill in the pertinent details, then click Review + create.

3. Follow subsequent prompts to finish VM creation.
4. Proceed to the next section after the deployment is complete.

©2023 Zscaler, Inc. All rights reserved. 61

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

Allowing Inbound Ports

Configure the Network Security Group (NSG) to permit inbound SSH access for management, and to allow inbound
TCP/514 from NSS and the OMS. By default, these ports are not permitted in Azure and you must manually allow inbound
connections to TCP/22 and TCP/514. Lock down this access to only permitted specific source IPs. On the Azure home
page, in the search bar at the top, enter Network Security Groups and then select Network security groups.

Figure 82. Network Security Groups

A new security group is automatically created by Azure with your resource group tied to it. Open the auto-created
network security group.

Figure 83. Network Security Groups, continued

©2023 Zscaler, Inc. All rights reserved. 62

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

Next, select the Inbound security rules option and configure the following rules to allow inbound connections.

• Protocol and Port TCP/514 from your Zscaler NSS IP

• Protocol and Port TCP/22 from your trusted network or management station
Review the following sections to see how to configure each rule separately.

Figure 84. Inbound security rules

©2023 Zscaler, Inc. All rights reserved. 63

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

Add Inbound Security Rule for Syslog

Configure these fields to match your environment. Although the destination port is 514, you can configure the destination
on the ZIA side to other ports. If you set this port to something other than 514 in ZIA, the port number must match here.
After you are done, select Add and proceed to the next section.

For testing purposes, any source IP can connect to this data connector VM on port 514. Post testing, restrict this
Clipboard-list access to the NSS source IP only.

Figure 85. Add inbound security rule for NSS

©2023 Zscaler, Inc. All rights reserved. 64

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

Add Inbound Security Rule for SSH

Configure these fields to match your environment. Ensure that the Source matches your trusted network or management
station from which you want to allow the SSH access.

For testing purposes, any source IP can connect to this data connector VM on port 22. Post testing, restrict this
Clipboard-list access to the trusted management source IP only.

Figure 86. Add inbound security rule for SSH

©2023 Zscaler, Inc. All rights reserved. 65

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

Create and Configure Sentinel Instance

Return to the Home screen, search for sentinel, and select Azure Sentinel (preview).

Figure 87. Return to Microsoft Sentinel

Create Log Analytics Workspace

First, create a workspace for Azure Sentinel. A log analytics workspace is a unique environment for Azure Monitor log data.
Each workspace has its own data repository. Configuration, data sources, and solutions are configured to store their data
in a particular workspace. Click Add, then Create a new workspace.

Figure 88. Create a new workspace

©2023 Zscaler, Inc. All rights reserved. 66

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

Name, Add, and Link a Resource Group to a Workspace

This document presumes the following steps are performed in a new, non-production environment. In this guide, the
resource group created in Bind this VM to a Resource Group is reused. If you are configuring this in an existing production
environment, your steps might be slightly different. Proceed with one of the following two steps:

• Link an existing resource group to the new workspace, or

• Create and then link an entirely new resource group to this new workspace.

Figure 89. Name, add, and link resource group to the workspace

Click OK.

©2023 Zscaler, Inc. All rights reserved. 67

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

Add an Azure Sentinel Workspace

Next, click Add. Wait until the deployment finishes before proceeding to the next section. This takes a few minutes.

Figure 90. Add Azure Sentinel workspace

©2023 Zscaler, Inc. All rights reserved. 68

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

Configure Data Collection

Configure data collection by navigating to News & guides > Collect data > Connect.

Figure 91. Configure Zscaler data collection

©2023 Zscaler, Inc. All rights reserved. 69

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

Search for Zscaler Connector

In the search box, enter Zscaler. Next, select the Zscaler connector, and then click Open connector page.

Figure 92. Search for Zscaler connector

©2023 Zscaler, Inc. All rights reserved. 70

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

Configure Syslog Agent

The Open connector page displays the Configuration instructions. For the first two steps:

1. Select a Linux machine (in any cloud or on-premises) that acts as a proxy between your security solution and
Sentinel. Use the previously set up VM.
2. Install an Azure monitoring agent (CEF connector) on this Linux box.

Figure 93. Steps to configure logging pipeline

©2023 Zscaler, Inc. All rights reserved. 71

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

3. Log in to the VM setup using SSH and run the command highlighted in the following image.

Figure 94. Command to configure logging agent

Figure 95. Validate collector agent installation

©2023 Zscaler, Inc. All rights reserved. 72

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

"Installation completed" and the netstat output show that the Syslog server and Azure collector agent (Ruby scripts) are
running.

If you encounter issues, run the following command.

Figure 96. Troubleshoot collector agent installation

©2023 Zscaler, Inc. All rights reserved. 73

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

Pick a Zscaler Workbook

1. Navigate to Dashboard > Azure Sentinel - Workbooks > Workbooks > My Workbooks and search for zscaler.
2. Select the workbook in which you are interested and click View template.
3. (Optional) Save the workbook to a geographic location and revisit it later.

Figure 97. Select Zscaler workbook

Explore Zscaler Workbook

Workbooks are responsive and you can click around to drill down based on different criteria.

You can filter by selecting options towards the top of the page or by clicking individual entries.

Figure 98. Sample workbook visualization

©2023 Zscaler, Inc. All rights reserved. 74

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

Configuring Sentinel for ZPA

The following steps assume that you have Admin access to the Azure portal.

Log in to Azure Portal

Log in to the Azure portal.

Figure 99. Sign in to Azure Portal

©2023 Zscaler, Inc. All rights reserved. 75

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

Deploy the Data Connector Host VM

The first Microsoft Sentinel step is to deploy a Linux VM. This Linux VM is the Sentinel ZPA data connector (not to be
confused with ZPA App Connector). In the ZPA Admin Portal, you configure ZPA to stream logs to the IP address of the
Linus VM. The VM then forwards received log messages to the Microsoft Sentinel backend.

After navigating to the Home screen, click Virtual machines.

Figure 100. This VM is a Syslog server and runs Azure’s data connector

Create Virtual Machine

Your Virtual machines screen might have additional information displayed if you have existing virtual machines. Click
Create virtual machine.

Figure 101. Create virtual machine

©2023 Zscaler, Inc. All rights reserved. 76

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

Bind this VM to a Resource Group

A Resource Group (RG) is a way to group a collection of assets in logical containers for automatic provisioning, monitoring,
access control, and more effective management of their costs. One benefit of using RGs is to group related application
resources together, as they share a unified lifecycle from creation, usage, and de-provisioning.

You can bind to an existing resource group, or you can create a new one.

1. To create a new resource group, click Create new, and give it a name. This example uses Ubuntu Server 18.04 LTS.

Figure 102. Initiate VM deployment

2. Fill in the pertinent details, then click Review + create.

3. Follow subsequent prompts to finish VM creation.
4. Proceed to the next section after the deployment is complete.

©2023 Zscaler, Inc. All rights reserved. 77

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

Allowing Inbound Ports

Configure the Network Security Group (NSG) to permit inbound SSH access for management, and to allow inbound
TCP/22033 from LSS App Connector. By default, these ports are not open in Azure and you must manually allow the
inbound connections. Lock down this access to only permitted specific source IPs. In the search bar on the Azure home
page, enter Network Security Groups, then select Network security groups.

Figure 103. Network Security Groups

A new security group is automatically created by Azure with your resource group tied to it. Open the auto-created
network security group.

Figure 104. Network Security Groups, continued

©2023 Zscaler, Inc. All rights reserved. 78

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

Next, select the Inbound Security Rules option and configure the following rules to allow inbound connections.

• Protocol and port TCP/22033 from your Zscaler LSS App Connector IP.
• Protocol and port TCP/22 from your trusted network or management station.
Review the following sections to see how to configure each rule separately.

Figure 105. Inbound security rules

©2023 Zscaler, Inc. All rights reserved. 79

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

Add Inbound Security Rule for Syslog

Configure these fields to match your environment. Although the destination port is TCP/22033, you can configure the
destination port on the ZPA side to be other ports. If you set this port to something other than 22033 in ZPA, then the
port number must match here. After you are done, select Add and proceed to the next section.

For testing purposes, any source IP can connect to this ZPA data connector VM on port 22033. Post testing,
Clipboard-list restrict this access to the LSS App Connector source IP only.

Figure 106. Add inbound security rule for LSS

©2023 Zscaler, Inc. All rights reserved. 80

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

Add Inbound Security Rule for SSH

Configure these fields to match your environment. Ensure the Source matches your trusted network or management
station from which you want to allow the SSH access.

For testing purposes, any source IP can connect to this data connector VM on port 22. Post testing,
Clipboard-list restrict this access to the trusted management source IP only.

Figure 107. Add inbound security rule for SSH

©2023 Zscaler, Inc. All rights reserved. 81

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

Create and Configure Sentinel Instance

Return to the Home screen, search for sentinel and select Azure Sentinel (preview).

Figure 108. Return to Azure Sentinel

Create Log Analytics Workspace

First, create a workspace for Azure Sentinel. A log analytics workspace is a unique environment for Azure Monitor log data.
Each workspace has its own data repository. Configuration, data sources, and solutions are configured to store their data
in a particular workspace. Click Add, then Create a new workspace.

Figure 109. Create a new workspace

©2023 Zscaler, Inc. All rights reserved. 82

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

Name, Add, and Link a Resource Group to a Workspace

This document presumes the following steps are performed in a new, non-production environment. In this guide, the
resource group created in Bind this VM to a Resource Group is reused. If you are configuring this in an existing production
environment, your steps might be slightly different. Proceed with one of the following two steps:

• Link an existing resource group to the new workspace, or

• Create and then link an entirely new resource group to this new workspace.

Figure 110. Name, add, and link resource group to the workspace

Click OK.

©2023 Zscaler, Inc. All rights reserved. 83

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

Add Microsoft Sentinel Workspace

After selecting the newly created workspace, click Add. Wait until the deployment finishes before proceeding to the next
section. This takes a few minutes.

Figure 111. Add Microsoft Sentinel workspace

©2023 Zscaler, Inc. All rights reserved. 84

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

Configure Data Collection

Configure data collection by navigating to News & guides > Collect data > Connect.

Figure 112. Configure Zscaler data collection

Search for Zscaler Private Access Connector

In the search bar, enter Zscaler Private Access. Next, select the Zscaler Private Access (Preview), and then click
Open connector page.

Figure 113. Search for ZPA data connector

©2023 Zscaler, Inc. All rights reserved. 85

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

Choose Where to Install the Linux Agent

Click Open connector page to display the Installation instructions. For the first two steps:

1. Install and onboard the agent for Linux.

2. Configure which logs to collect.

Figure 114. Steps to configure ZPA data connector

©2023 Zscaler, Inc. All rights reserved. 86

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

Install and Onboard the Agent on an Azure Linux Virtual Machine

Expand the Install agent on Azure Linux Virtual Machine section and then click Install agent for Azure Linux Virtual
machines. This opens the Virtual machines window.

Figure 115. Azure Virtual machines window

Select the machine on which to install the agent and then click Connect. This would be the Ubuntu VM that you created
in previous few steps.

Figure 116. Connect to a virtual machine

When connected, the Status changes to This workspace.

©2023 Zscaler, Inc. All rights reserved. 87

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

Configure Which Logs to Collect

The following steps describe how to get ZPA logs into Microsoft Sentinel. To learn more, refer to the Azure Monitor
Documentation. ZPA logs are delivered via Zscaler’s Log Streaming Service (LSS). To learn more, see About the Log
Streaming Service.

1. Configure log receivers.

2. While configuring a log receiver in ZPA Admin Portal, choose JSON (from the drop-down menu) as the Log
Template. Configure the ZPA platform to send JSON-formatted ZPA logs to the data connector VM’s IP address on
(by default) port 22033.
3. (Optional) If the LSS App Connector and the data connector VM are not both in the same Azure VNet, then enable
TLS encryption between ZPA and the data connector VM. For Zscaler, enable TLS encryption in the ZPA Admin
Portal. On the data connector VM, install a valid (non-self-signed) SSL cert assigned to this VM IP/domain from a
public CA. Installation/configuration of the SSL cert on the data connector Linux VM is outside of the scope of this
document.
4. SSH to the data connector VM where you have installed Azure Log Analytics agent.
5. Download config file zpa.conf to this data connector VM:
wget -v https://aka.ms/sentinel-zscalerprivateaccess-conf -O zpa.conf

6. Copy zpa.conf to the /etc/opt/microsoft/omsagent/workspace_id/conf/omsagent.d/ folder.

cp zpa.conf /etc/opt/microsoft/omsagent/workspace_id/conf/omsagent.d/

7. Edit the zpa.conf as follows:

• Specify the port you have set your Zscaler log receivers to forward logs to (line 4). The zpa.conf file uses the port
22033 by default. Ensure this port is not used by any other source on your server.
• If you want to change the default port for zpa.conf, make sure to set it so that it doesn’t conflict with default
Azure Monitoring Agent (AMA) agent ports (for example, CEF uses TCP port 25226 or 25224).
• Replace workspace_id with the correct Workspace ID value from your Azure tenant (lines 14, 15, 16, 19).
8. Save your changes and restart the Azure Log Analytics agent for the Linux service using the following command:
sudo /opt/microsoft/omsagent/bin/service_control restart

9. Generate the ZPA logs. They are displayed after a few minutes under the respective Microsoft Sentinel instance.

©2023 Zscaler, Inc. All rights reserved. 88

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

Microsoft Sentinel Playbooks Overview

SOC analysts are regularly inundated with security alerts and incidents. This results in situations where many alerts are
ignored and many incidents aren’t investigated, leaving the organization vulnerable to attacks that go unnoticed.

Many of these alerts and incidents conform to recurring patterns that you can address by specific and defined sets of
remediation actions. Analysts are also tasked with basic remediation and investigation of the incidents they do manage to
address. You can automate many of these activities. Automating tasks allows SOCs more time for productivity, efficiency,
and investigative activity.

This playbook is a collection of remediation actions that you run from Microsoft Sentinel to help automate and
orchestrate your threat response. It can be run in two ways:

• Manually on-demand, on a particular entity or alert.

• Automatically in response to specific alerts or incidents, when triggered by an automation rule.
For example, if an account and machine are compromised, a playbook can isolate the machine from the network and
block the account by the time the SOC team is notified of the incident.

Microsoft Sentinel Playbooks Resources

The following table contains links to Microsoft Sentinel Playbook support resources.

• For articles with use cases to get started using Microsoft Sentinel, see Microsoft Sentinel Documentation.
• For Support portal for Microsoft Sentinel Playbooks, see Security, Orchestration, Automation, and Response (SOAR).
Document Prerequisites

To use this document, the following prerequisites are required:

ZIA:

• An active instance of ZIA 6.2 (or later).

• Administrator login credentials to ZIA.
• Nanolog streaming from ZIA into Microsoft Sentinel.
• OAuth 2.0 Authentication have been met.
Microsoft Sentinel:

• An Azure Active Directory license and tenant, or an individual account with a valid payment method, are required to
access Azure and deploy resources.
• After you have a subscription, you’ll need the relevant permissions to begin using your subscription.
• A Log Analytics workspace is required to house all of the data that Microsoft Sentinel investigates and uses for its
detections, analytics, and other features.
• Zscaler recommends that when you set up your Microsoft Sentinel workspace, create a resource group that’s
dedicated to Microsoft Sentinel and the resources that Microsoft Sentinel uses, including the Log Analytics workspace,
any playbooks, workbooks, and so on.

©2023 Zscaler, Inc. All rights reserved. 89

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

ZIA API Architecture Overview

Zscaler has two core products: ZIA and ZPA. This section only addresses ZIA.

Zscaler provides secured access to Cloud Service API and Sandbox Submission API using different authentication
schemes:

API Supported Authentication Methods

Cloud Service API OAuth 2.0 (recommended)
Combination of Basic Authentication and API Key
Sandbox Submission API Combination of Basic Authentication and API Token

The instructions in this document and the Microsoft Sentinel Playbooks have been developed to leverage the OAuth 2.0
model for authentication to the Cloud Service API.

OAuth 2.0 Authentication

OAuth 2.0 allows third-party applications to obtain controlled access to protected resources using access tokens. Zscaler
uses the Client Credentials grant type, in which the clients exchange their credentials for an access token.

In this model, client applications make API calls to the cloud service API using an access token obtained from the
authorization server in exchange for their credentials. Therefore, the clients access the cloud service API resources on their
behalf without requiring any user interaction.

Figure 117. Obtaining an access token

The following steps describe the process:

1. A client requests an access token from the authorization server. A client application registered with the authorization
server sends an authorization request with its credentials (i.e., client ID and client secret) to the authorization server.
In addition to the client credentials, the authorization request must specify the required scope and the grant type.
2. The authorization server authenticates the client and provides an access token. The authorization server validates
the client’s credentials and provides the client with a signed JSON Web Token (JWT) access token upon successful
authorization. The response from the authorization server contains the access token, token type (bearer token), and
the token expiry time.

©2023 Zscaler, Inc. All rights reserved. 90

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

3. The client sends the access token to the resource server. The client sends an API request to the resource server (i.e.,
cloud service API) with the signed JWT access token in the request authorization header.
4. The resource server grants access to protected resources. The following series of events take place before the
resource server (i.e., cloud service API) can accept the API request:
a. The Zscaler service extracts the JWT access token from the API request header and decodes the token to fetch
information such as the key ID, algorithm, scope, client ID, audience, expiry, and other configured values.
b. The Zscaler service cryptographically verifies the signature of the JWT token using the authorization server’s
public key.
c. If the JWT signature verification is successful, the Zscaler service validates the JWT’s scope claim, which is in
<Zscaler Cloud Name>::<Org ID>::<API Role> format. The <API Role> value in the scope is used to authorize the
API request. This value must match with one of the API Roles configured in the ZIA Admin Portal. If no match is
found, the API request is rejected.
d. Finally, the Zscaler service grants the client application access to the requested API resources.

OAuth 2.0 Prerequisites

Your organization must meet the following prerequisites before you can access the API:

• You must have an API subscription. If you do not have a subscription, submit a Zscaler Support ticket.
• You must have the API Roles configured in the ZIA Admin Portal.
• You must have your client applications registered on your authorization server (i.e., PingFederate, Okta, or Azure AD)
with the required scope and configured appropriately. This document walks you through the required setup using
Entra ID (formerly known as Azure AD).
• You must have your OAuth 2.0 authorization server added to the ZIA Admin Portal.

Benefits of OAuth 2.0 authentication

• Better Security: OAuth 2.0 secures your APIs with dynamic credentials, which are time-bound and generated on
demand for a client.
• Limits Exposure of Credentials: Unlike the authentication model that uses API keys and ZIA admin credentials and
might involve user management outside the organization’s identity provider, OAuth 2.0 does not require ZIA admin
credentials for authentication.
• Granular Access Control: The Client Credentials OAuth flow employs API Roles to define permissions required to
access specific categories of cloud service API. Unlike admin roles, API roles are not assigned to ZIA admin users.
Instead, API roles are associated with the client applications that are accessing the API. OAuth 2.0 provides added
security to API access by isolating API permissions from admin users with access to the ZIA Admin Portal.
• Reduced Maintenance: OAuth 2.0 does not require obfuscation of credentials, unlike API keys which need to be
obfuscated on the client with additional programming for enhanced security.

©2023 Zscaler, Inc. All rights reserved. 91

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

Configuring a ZIA API Role

The following sections demonstrate how to configure a ZIA API role.

Logging in to ZIA
First, set up the Zscaler side of this service. Log in to the ZIA Admin Portal. If you are unable to log in using your
Administrator Account, contact Support.

Figure 118. ZIA Admin Portal

Create an API Role

To create an API role:

1. Go to Administration > Role Management.

Figure 119. Role Management

©2023 Zscaler, Inc. All rights reserved. 92

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

2. Click Add API Role.

Figure 120. Add API Role

3. Add an API role named Sentinel-Playbooks and enable the configuration shown in the following figure.
4. Click Save.
5. Activate the changes.

Figure 121. Configure API Role

©2023 Zscaler, Inc. All rights reserved. 93

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

Configuring Microsoft Entra ID for OAuth 2.0 Authentication

This guide uses Microsoft Entra ID as the IdP for OAuth 2.0. For other IdP’s, including Okta and PingFederate, see Adding
Identity Providers.

For each API role configured in the ZIA Admin Portal, you must complete the steps in the following sections to set up
OAuth 2.0 authorization using Entra ID.

You must create two app registrations in the Microsoft Entra ID:

Clipboard-list 1. The ZIA API Client Application.

2. The ZIA API Web Service Application.

Register the ZIA API Client Application

To register the ZIA API Client Application:

1. Sign in to the Microsoft Azure portal.

2. Go to Microsoft Entra ID under Azure Services.
3. Click App Registrations on the left-side navigation.
4. Click New Registration.

Figure 122. App registrations

©2023 Zscaler, Inc. All rights reserved. 94

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

5. In the Register an application window:

a. Enter a Name for the application that is representative of the ZIA API Role used (e.g., ZIA API Microsoft Sentinel
Playbooks).
b. Set the Supported account types option to Accounts in this organizational directory only (Zscaler Lab only -
Single tenant).

Figure 123. Register an application

6. Click Register. The application is registered, and the application’s Overview page is displayed.
7. Copy the Application (client) ID value from the Overview page and save it for later use.

Figure 124. Application Overview page

©2023 Zscaler, Inc. All rights reserved. 95

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

8. Go to Owners.
9. Click Add owners and add yourself as an owner.

Figure 125. Owners

Configure Client Credentials

To configure the credentials for your ZIA API Client Application:

1. Click Certificates & secrets on the left-side navigation of the app.

2. Click New client secret on the Client secrets tab

Figure 126. Certificates & secrets

©2023 Zscaler, Inc. All rights reserved. 96

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

3. In the Add a client secret pane:

a. Description: Provide information about the client’s secret.
b. Expires: Select the appropriate expiration time from the drop-down menu.

Figure 127. Add client secret

c. Click Add. The client secret value is generated and displayed.

Figure 128. Client secret value

d. Copy the secret value and save it for later use.

©2023 Zscaler, Inc. All rights reserved. 97

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

Configure the ZIA API Web Service Application

This section describes how to register the ZIA API Web Service Application in Microsoft Entra ID and configure the app to
expose a Web API that is accessible by the ZIA API client application.

1. To complete the application registration process:

a. Go to Microsoft Entra ID under Azure Services.
b. Click App registrations on the left-side navigation.
c. Click New registration. The Register an application window opens.

Figure 129. App registrations

©2023 Zscaler, Inc. All rights reserved. 98

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

2. In the Register an application window, complete the following:

a. Name: Enter a name for the ZIA API Web Service Application (e.g., ZIA API Web Service).
b. Supported account types: Ensure that this option is set to the Accounts in this organizational directory only
(Zscaler Lab only - Single tenant) value.

Figure 130. Register an application

3. Click Register. The application is registered and displayed.

4. To configure the ZIA API Web Service Application to expose a Web API:
a. Click Expose an API on the left-side navigation of the app in your ZIA API web service.
b. Click Add next to the Application ID URI, and then click Save with the default value that is provided. Copy the
Application ID URI and save it for later use.

Figure 131. Expose an API

©2023 Zscaler, Inc. All rights reserved. 99

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

c. Click Add a scope under Scopes defined by this API. The Add a Scope section appears.

Figure 132. Add a scope

©2023 Zscaler, Inc. All rights reserved. 100

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

5. In the Add a Scope section:

a. Scope name: Enter a relevant scope name (e.g., ZIA API Client <ZIA API Role>).
b. Who can consent: Choose which users can consent to this scope based on your business requirements and
organization policies.
c. Admin consent display name: Enter a consent name that is displayed on the consent screen when admins
consent to this scope.
d. Admin consent description: Enter a detailed description that must be displayed when tenant admins expand a
scope on the consent screen.
e. User consent display name: Enter a consent name that must be displayed on the consent screen when users
consent to this scope.
f. User consent description: Enter a detailed description that must be displayed when users expand a scope on
the consent screen.
g. State: Ensure that the scope is enabled.
h. Click Add scope.

Figure 133. Configure scope

©2023 Zscaler, Inc. All rights reserved. 101

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

6. To authorize the client application, click Add a client application under Authorized client applications.

Figure 134. Add a client application

7. In the Client ID field, enter the Application (client) ID from the ZIA API client application and select the required
scope under Authorized scopes.
8. Click Add application.

Figure 135. Authorized scopes

©2023 Zscaler, Inc. All rights reserved. 102

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

9. Click App roles on the left-side navigation and then click Create app role.

Figure 136. Create app role

10. In the Create app role pane:

a. Display name: Enter a display name for the app role.
b. Value: Enter a value in the format supported by the Zscaler service, <Zscaler Cloud Name>::<Org
ID>::<API Role>, where:
• <Zscaler Cloud Name> represents the name of the cloud on which your organization is provisioned.
• <Org ID> is an identifier assigned to your organization by Zscaler. You can obtain this value from the
Company Profile page within the ZIA Admin Portal.
• <API Role> represents the API Role configured on the Role Management page within the ZIA Admin Portal.
For example, zscalera.net::272378::sampleRole.
c. Description: Enter a description of the app role.
d. Do you want to enable this app role: Select this checkbox.
e. Click Apply.

Figure 137. Configure new app role

©2023 Zscaler, Inc. All rights reserved. 103

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

After the app role is created, go to the Manifest page from the left-side navigation and ensure that the app role you
configured appears in the appRoles field within the JSON fields.

11. Click Owners, select Add owners, and add yourself as an owner.

Figure 138. Add owners

Configure the ZIA API Client Application to access the ZIA API Web Service Application
To configure the ZIA API Client Application permissions to use the ZIA API Web Service Application:

1. Go to Microsoft Entra ID under Azure services.

2. Click App Registrations on the left-side navigation and then click the ZIA API Client Application. The Overview page
of the app is displayed.
3. Click API permissions on the left-side navigation and then click Add a permission under Configured permissions.
The Request API permissions pane opens.

Figure 139. Request API permissions

4. In the Request API permissions pane:

a. Go to the My APIs tab and then click the Web Service API App (Application B).
b. Choose the Application permissions as the type of permission required by the client application.

©2023 Zscaler, Inc. All rights reserved. 104

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

c. Under Select permissions, select the API Role that was created in Configure the ZIA API Web Service
Application).

Figure 140. Configure API permissions

d. Click Application permissions.

e. If you are testing the configurations, enable the Grant admin consent for Zscaler Lab option under the
Configured permissions section and click Yes when prompted.

Figure 141. Configured permissions

©2023 Zscaler, Inc. All rights reserved. 105

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

Collect Information for Zscaler OAuth 2.0 Server Configuration

To collect information from Microsoft Entra ID used to configure the OAuth 2.0 authorization server in the ZIA Admin
Portal:

1. Go to Microsoft Entra ID under Azure services.

2. Click App Registrations on the left-side navigation and then click the ZIA API Web Service Application configured in
Configure the ZIA API Web Service Application.
3. Click the Endpoints tab on the Overview page. The Endpoints pane opens.

Figure 142. Endpoints

4. In the Endpoints pane:

a. Copy the OAuth 2.0 token endpoint (v2) URL. The typical format is https://login.microsoftonline.
com/<Application ID>/oauth2/v2.0/token
b. Copy the URL displayed in the OpenID Connect metadata document field and open the link in a new browser
window. Locate the jwks_uri parameter in the metadata displayed and copy its value. The typical format is
https://login.microsoftonline.com/<Application ID>/discovery/v2.0/keys

Figure 143. Endpoints URL

These values are required for configuring the OAuth 2.0 authorization server in the ZIA Admin Portal, as explained in the

©2023 Zscaler, Inc. All rights reserved. 106

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

subsequent section.

Configuring the OAuth2.0 Authorization Server

After completing the necessary configurations in Microsoft Entra ID, you can validate the authorization server
configuration and retrieve an access token.

1. Log in to the ZIA Admin Portal.

2. Go to Administration > Cloud Service API Security.
3. Click the OAuth 2.0 Authorization Servers tab and then click Add Authorization Server. The Add Authorization
Server window opens.
4. In the Add Authorization Server window, fill out the following information, which is necessary to validate your
authorization server configuration:
a. Name: Enter a name for your authorization server configuration (e.g., Entra ID). The name can only contain
alphanumeric characters without spaces and cannot exceed 64 characters.
b. OAuth 2.0 JWKS Location: Enter the JSON Web Key Set (JWKS) endpoint value obtained through the jwks_uri
parameter in Collect Information for Zscaler OAuth 2.0 Server Configuration). The JWKS endpoint returns the
public key set of the authorization server that is used by Zscaler to cryptographically verify the authenticity of
the JWT in API requests.

Figure 144. Add Authorization Server

©2023 Zscaler, Inc. All rights reserved. 107

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

Authenticating an OAuth 2.0 Session in Postman

Zscaler supports the Windows, macOS, and Linux versions of the Postman REST API app. To learn more about the app
and its features, refer to the Postman documentation.

Installing and Configuring Postman for Windows, macOS, or Linux

To install and configure Postman:

1. Go to the Postman website and download the app for your OS (i.e., Windows, macOS, or Linux).
2. Install the app.
3. After installation, open the app and log in using your account.
4. Download the latest version of the cloud service API collection file from the Reference Guide. Click Try in Postman to
download the collection.
5. From the main window in Postman, click Import.

Figure 145. Install Postman

6. In the Import window that appears, select your Postman collection file, or drag the file to the selection area.

Figure 146. Postman file

After the file is imported, a new folder with the name used within the Postman collection file (e.g., cloud service API)
is displayed within Collections.

©2023 Zscaler, Inc. All rights reserved. 108

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

7. Ensure that No Environment is selected in the environment drop-down menu on the top right, and then click the
Environment quick look icon.
8. Click Add.

Figure 147. Add environment

9. On the New Environment tab that appears, complete the following steps:
a. Enter a descriptive name for the environment (e.g., ZIA – zscalertwo.net).
b. Create a new variable the base URL.
• Under Variable, enter url.
• For Type, leave as default.
• For Initial Value, enter the URL found in your ZIA Dashboard, under Administration > Cloud Service API
Security.

Figure 148. Cloud Service API Security

©2023 Zscaler, Inc. All rights reserved. 109

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

c. Create a new variable for the OAuth 2.0 Token Endpoint:

• Under Variable, enter tokenUrl.
• For Type, leave as default.
• For Initial Value, enter the OAuth 2.0 token endpoint (v2) URL that you copied from the Collect Information
for Zscaler OAuth 2.0 Server Configuration section.
d. Create a new variable for the ZIA API Client Application client ID:
• Under Variable, enter clientId.
• For Type, leave as default.
• For Initial Value, enter the Application (client) ID for your ZIA API Client Application that you copied in the
Register the ZIA API Client Application section.
e. Create a new variable for the ZIA API Client Application client secret:
• Under Variable, enter clientSecret.
• For Type, leave as default.
• For Initial Value, enter the client secret value for your ZIA API Client Application that you copied in the
Configure Client Credentials section.
f. Create a new variable for the ZIA API Client Application scope:
• Under Variable, enter scope.
• For Type, leave as default.
• For Initial Value, enter the Application ID URI from your ZIA API Web Service Application, appended with
./default. For example, api://c0636925-82fa-49e1-be49-72afb0a9fd59/.default

Figure 149. Create variables

g. Click Save and close the tab.

h. Select the environment you configured (e.g., ZIA – zscalertwo.net) from the environment drop-down
menu on the top right. To learn more, refer to the Postman documentation.

©2023 Zscaler, Inc. All rights reserved. 110

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

10. Go to Collections > Cloud service API > URL Categories > GET URL Categories – Get all. Under Authorization,
select OAuth 2.0 from the drop-down menu.

Figure 150. Get URL Categories – Get all

©2023 Zscaler, Inc. All rights reserved. 111

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

11. Ensure the environment you have created is selected in the top right. Under Configure New Token, complete the
following:
a. For Access Token URL, enter {{tokenURL}}
b. For Client ID, enter {{clientId}}
c. For Client Secret, enter {{clientSecret}}
d. For Score, enter {{scope}}

Figure 151. Configure new token

12. Click Get New Access Token, and then select Use Token. This is your access token, which must be sent in the API
calls made to the ZIA API service. You can present the access token in the request Authorization header using the
bearer authentication scheme along with the token expiration time.

Figure 152. Get new access token

13. Click Send and receive a response back with a list of all URL categories configured in your tenant.

©2023 Zscaler, Inc. All rights reserved. 112

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

Deployment of Zscaler Playbooks for Microsoft Sentinel

Zscaler created several tested and ready-to-use Microsoft Sentinel Playbook templates that you can customize to meet a
variety of needs.

These include:

• Zscaler-Oauth2-Authentication: This provides the authentication module which allows a Playbook to authentication
to the ZIA API service using OAuth 2.0.
• Zscaler-Oauth2-DenylistURL: Add URLs to the ATP Blocked Malicious URLs list.
• Zscaler-Oauth2-BlockIP: Block an IP by adding to a URL category.
• Zscaler-Oauth2-BlockURL: Block a URL by adding to a URL category.
• Zscaler-Oauth2-LookupIP: Lookup the categories related to an IP.
• Zscaler-Oauth2-LookupSandboxReport: Lookup a Sandbox Report using a MD5 Hash.
• Zscaler-Oauth2-LookupURL: Lookup the categories related to a URL.
• Zscaler-Oauth2-UndenylistURL: Remove URLs from the ATP Blocked Malicious URLs list.
• Zscaler-Oauth2-UnblockIP: Remove an IP from a URL category.
• Zscaler-Oauth2-UnblockURL: Remove a URL from a URL category.
• Zscaler-Oauth2-AllowlistURL: Add URL to the ATP allowlist.
For more information about playbook automation responses, refer to the Microsoft Sentinel Playbook documentation.

The rest of this guide demonstrates the process of deploying the Playbook templates into Microsoft Sentinel.

Giving Permission to Microsoft Sentinel to Run Playbooks

Microsoft Sentinel needs permission to run playbooks. This is done on the resource group that contains the permissions.
To configure permissions, complete the following:

1. Sign in to the Microsoft Azure portal.

2. Go to Microsoft Sentinel and select your Log Analytics workspace.

Figure 153. Log Analytics workspace

©2023 Zscaler, Inc. All rights reserved. 113

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

3. Select Settings > API permissions > Configured permissions > Grant admin consent for Zscaler Lab and select the
zscalertwo.net API.

Figure 154. Configure permissions

4. Select the resource group that contains your playbooks and select Apply.

Figure 155. Manage permissions

©2023 Zscaler, Inc. All rights reserved. 114

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

Configuring an Azure Key Vault

The Zscaler-Oauth2-Authentication Playbook leverages the Azure Key Vault to store the Client Secret needed to
authenticate to the ZIA API OAuth 2.0 Web Service. To configure the Azure Key Vault, complete the following:

1. Sign in to the Microsoft Azure portal.

2. Go to Key vaults under Azure Services.
3. Click Create.
4. Complete the following:
a. Subscription: Select your subscription. Ensure this is the same subscription your Microsoft Sentinel Log
Analytics workspace was deployed to and the workspace to which you want to deploy your playbooks.
b. Resource group: Either create a new resource group or select an existing resource group (e.g., sentinel-
playbooks-rg).
c. Key vault name: Give your key vault a name (e.g., Zscaler-Oauth2-Secrets).
d. Region: Select a region to deploy the resource to.
e. Pricing Tier: Select Standard.
f. Click Review + create.

Figure 156. Azure Services key vault

©2023 Zscaler, Inc. All rights reserved. 115

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

5. Select the key vault you just created, and select Access control (IAM).

Figure 157. Access control (IAM)

6. Add your account to the Key Vaults Secrets Officer role.

Figure 158. Key Vaults Secrets Officer role

©2023 Zscaler, Inc. All rights reserved. 116

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

7. Click Review + assign.

Figure 159. Review + assign

8. Select Secrets, and then Generate/Import.

Figure 160. Import file

©2023 Zscaler, Inc. All rights reserved. 117

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

9. Complete the following under Create a secret:

a. Upload options: Select Manual.
b. Name: Enter client-secret.
c. Secret value: Enter the secret value from your ZIA API Client Application.
d. Enabled: Click Yes.

Figure 161. Configure secret

e. Click Create.

©2023 Zscaler, Inc. All rights reserved. 118

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

Deploying the Zscaler-Oauth2-Authenticaton Playbook

To install and configure this playbook to use the Azure Key Vault complete the following:

1. Download the Zscaler-Oauth2-Authentication playbook from the Zscaler GitHub repo for Microsoft Sentinel
Playbooks.
2. Go to the Zscaler-Oauth2-Authentication folder, review the README.md file, and click Deploy to Azure.

Figure 162. Deploy to Azure

3. Select the subscription, resource group, and region to which the template is deployed.
4. Click Review + create, then Create.

Figure 163. Custom deployment

5. Go to Azure Services > Logic apps. The imported logic app appears on your list of logic apps.

Figure 164. Logic apps

©2023 Zscaler, Inc. All rights reserved. 119

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

6. Select the Zscaler-Oauth2-Authentication playbook and select Identity. Verify that the system-assigned identity is
on (turn it on if it isn’t).

Figure 165. Enable identity

7. Go to Azure Services > Key Vault and select the Key vault you created in Configuring an Azure Key Vault.

Figure 166. Key vaults

©2023 Zscaler, Inc. All rights reserved. 120

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

8. Select Access control (IAM) and click Add role assignment.

Figure 167. Add role assignment

9. Select the Key Vault Secrets Officer and click Next.

Figure 168. Key Vault Secrets Officer

©2023 Zscaler, Inc. All rights reserved. 121

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

10. Under Members, for Assign access to, select Managed Identity.
11. Under Select Managed Identities, select Logic app (1) from the drop-down menu, and enter the Zscaler-Oauth2-
Authentication.

Figure 169. Select Manage Identities

12. Click Select, then Review + assign.

13. Go to Azure Services > Logic apps and select the Zscaler-Oauth2-Authentication logic app.
14. Under Development Tools, select Logic app designer.

Figure 170. Logic app designer

©2023 Zscaler, Inc. All rights reserved. 122

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

15. Select the Connections step and click Add new.

Figure 171. Add new

16. Complete the following under Azure Key Vault:

a. Connection name: Enter Connection to Azure Key Vault.
b. Authentication type: Select Managed Identity from the drop-down menu.
c. Vault Name: Enter Zscaler-Oauth2-Secrets (or the name of the Key Vault you created).
17. Click Create, then Save.

Figure 172. Azure Key Vault

©2023 Zscaler, Inc. All rights reserved. 123

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

18. Select the HTTP step, and in the Body replace the client_id with your client_id from ZIA API Client Application and
the scope with the scope with the Application ID URI from your ZIA API Web Service Application, appended with
./default.
For example: api://c0636925-82fa-49e1-be49-72afb0a9fd59/.default

Figure 173. HTTP

19. Test the Logic App by going to Run Trigger and clicking Run. When successful, you see an Outputs step under Parse
JSON with an access_token header.

Figure 174. Run Trigger

©2023 Zscaler, Inc. All rights reserved. 124

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

Deploying the Zscaler-Oauth2-BlockIP Playbook

To install and configure this playbook:

1. Download the Zscaler-Oauth2-BlockIP playbook from the Zscaler GitHub repo for Microsoft Sentinel Playbooks.
2. Go to the Zscaler-Oauth2-BlockIP folder, review the README.md file, and click Deploy to Azure.
3. Select your subscription, resource group, and region you want to deploy the template to.
4. Click Review + create, then click Create.

Figure 175. Custom deployment

5. Go to Azure Services > Logic apps and your imported logic app appears on your list of logic apps.

Figure 176. Logic apps

©2023 Zscaler, Inc. All rights reserved. 125

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

6. To authorize the connection, select the Zscaler-Oauth2-BlockIP logic app, then go to Logic app designer and select
the Entities – Get IPs step. In that step, click Change connection.

Figure 177. Entities – Get IPs

7. Select Add new > Connect with managed identity.

Figure 178. Microsoft Sentinel

8. For Connection name, input a connection name, such as Zscaler-Oauth2-BlockIP.

9. Click Create, then click Save.

Figure 179. Define URL Category

The playbook has been configured to add an IP to the Other Miscellaneous category. To change this, modify the
Microsoft Logic app designer step Define URL Category. To change the ZIA base URL for this playbook, you can modify
the Microsoft Logic app designer step Define Base URL.

©2023 Zscaler, Inc. All rights reserved. 126

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

Deploying the Zscaler-Oauth2-BlacklistURL Playbook

To install and configure this playbook, complete the following:

1. Download the Zscaler-Oauth2-BlacklistURL playbook, from the Zscaler GitHub repo for Microsoft Sentinel
Playbooks.
2. Navigate to the Zscaler-Oauth2-BlacklistURL folder, review the README.md file, and click Deploy to Azure.

Figure 180. Deploy to Azure

3. Select your subscription, resource group, and region to which you want to deploy the template.
4. Click Review + create, then click Create.

Figure 181. Custom Deployment

5. Go to Azure Services > Logic apps and your imported logic app appears on your list of logic apps.

Figure 182. Logic apps

©2023 Zscaler, Inc. All rights reserved. 127

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

6. To authorize the connection, select the Zscaler-Oauth2-BlacklistURL logic app, then go to Logic app designer and
select the Entities – Get URLs step. In that step, click Change Connection.

Figure 183. New URL List

7. Select Add new > Connect with managed identity.

Figure 184. Define URL Category

8. For Connection name, enter a connection name, such as Zscaler-Oauth2-BlacklistURL.

9. Click Create, then click Save.

Figure 185. Connection name

To change the ZIA base URL for this playbook, you can modify the Logic app designer step Define Base URL.
©2023 Zscaler, Inc. All rights reserved. 128
 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

Deploying the Zscaler-Oauth2-BlockURL Playbook

To install and configure this playbook, complete the following:

1. Download the Zscaler-Oauth2-BlockURL playbook from the Zscaler GitHub repo for Microsoft Sentinel Playbooks.
2. Go to the Zscaler-Oauth2-BlockURL folder, review the README.md file, and click Deploy to Azure.

Figure 186. Deploy to Azure

3. Select the subscription, resource group, and region to which you want to deploy the template.
4. Click Review + create, then Create.

Figure 187. Custom deployment

5. Navigate to Azure Services > Logic apps and your imported logic app appears on the list of logic apps.

Figure 188. Logic apps

©2023 Zscaler, Inc. All rights reserved. 129

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

6. To authorize the connection, select the Zscaler-Oauth2-BlockURL logic app, then go to Logic app designer and
select the Entities – Get URLs step. In that step, click Change connection.

Figure 189. Change connection

7. Select Add new > Connect with managed identity.

Figure 190. Add new identity

8. For Connection name, enter a connection name, such as Zscaler-Oauth2-BlockURL.

Figure 191. Connection name

9. Click Create, then click Save.

To change the ZIA base URL for this playbook, you can modify the Logic app designer step Define Base URL. To change
the URL category for this playbook, you can modify the Logic app designer step Define URL category.

©2023 Zscaler, Inc. All rights reserved. 130

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

Deploying the Zscaler-Oauth2-LookupIP Playbook

To install and configure this playbook:

1. Download the Zscaler-Oauth2-LookupIP playbook from the Zscaler GitHub repo for Microsoft Sentinel Playbooks.
2. Go to the Zscaler-Oauth2-LookupIP folder, review the README.md file, and click Deploy to Azure.

Figure 192. Deploy to Azure

3. Select the subscription, resource group, and region to which you want to deploy the template.
4. Click Review + create, then Create.

Figure 193. Custom deployment

5. Go to Azure Services > Logic apps and your imported logic app appears on your list of logic apps.

Figure 194. Logic apps

©2023 Zscaler, Inc. All rights reserved. 131

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

6. To authorize the connection, select the Zscaler-Oauth2-LookupIP logic app, then go to Logic app designer and
select the Entities – Get IPs step. In that step, click Change connection.

Figure 195. Change connection

7. Select Add new > Connect with managed identity.

Figure 196. Connect with managed identity

8. For Connection name, input a connection name, such as Zscaler-Oauth2-LookupIP.

Figure 197. Connection name

9. Click Create, then click Save.

To change the ZIA base URL for this playbook, you can modify the Logic app designer step Initialize variable - Define
Base URL.

©2023 Zscaler, Inc. All rights reserved. 132

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

Deploying the Zscaler-Oauth2-LookupSandboxReport Playbook

To install and configure this playbook, complete the following:

1. Create a new Integration account:

a. Go to Azure Services > Integration accounts.
b. Click Create.
c. Complete the following:
• Resource group: Select the resource group that contains your playbooks.
• Integration account name: Enter Zscaler-Logicapp.
• Pricing Tier: Select Basic from the drop-down menu.
d. Click Review + create, then Create.

Figure 198. Create an integration account

2. Download the Zscaler-Oauth2-LookupSandboxReport playbook from the Zscaler GitHub repo for Microsoft
Sentinel Playbooks.
3. Go to the Zscaler-Oauth2-LookupSandboxReport folder, review the README.md file, and click Deploy to Azure.

Figure 199. Deploy to Azure

©2023 Zscaler, Inc. All rights reserved. 133

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

4. Select your subscription, resource group, and region to which you want to deploy the template.
5. Click Review + create, then Create.

Figure 200. Custom deployment

6. Go to Azure Services > Logic apps and your imported logic app appears on your list of logic apps.

Figure 201. Logic apps

7. To authorize the connection, select the Zscaler-Oauth2-LookupSandboxReport logic app, then go to Logic app
designer and select the Microsoft Sentinel incident step. In that step, click Change connection.

Figure 202. Change connection

©2023 Zscaler, Inc. All rights reserved. 134

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

8. Select Add new > Connect with managed identity.

Figure 203. Connect with managed identity

9. For Connection name, input a connection name, such as Zscaler-Oauth2-LookupSandboxReport.

Figure 204. Connection name

10. Click Create, then click Save.

11. To authorize the second connection, select the Zscaler-Oauth2-LookupSandboxReport logic app, then go to Logic
app designer and select the Entities – Get FileHashes step. In that step, click Change connection.

Figure 205. Change connection

©2023 Zscaler, Inc. All rights reserved. 135

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

12. Select Add new > Connect with managed identity.

Figure 206. Connect with managed identity

13. For Connection name, input a connection name, such as Zscaler-Oauth2-LookupSandboxReport.

Figure 207. Connection name

14. Click Create, then click Save.

To change the ZIA base URL for this playbook, you can modify the Microsoft Logic app designer step Initialize variable -
Define Base URL.

Deploying the Zscaler-Oauth2-LookupURL Playbook

To install and configure this playbook, complete the following:

1. Download the Zscaler-Oauth2-LookupURL playbook from the Zscaler GitHub repo for Microsoft Sentinel Playbooks.
2. Navigate to the Zscaler-Oauth2-LookupURL folder, review the README.md file, and click the Deploy to Azure.

Figure 208. Deploy to Azure

©2023 Zscaler, Inc. All rights reserved. 136

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

3. Select your subscription, resource group, and region to which you want to deploy the template.
4. Click Review + create, then Create.

Figure 209. Custom deployment

5. Go to Azure Services > Logic apps and your imported logic app appears on your list of logic apps.

Figure 210. Logic apps

6. To authorize the connection, select the Zscaler-Oauth2-LookupURL logic app, then go to Logic app designer and
select the Entities – Get URLs step.
7. Click Change connection.

Figure 211. Change connection

©2023 Zscaler, Inc. All rights reserved. 137

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

8. Select Add new > Connect with managed identity.

Figure 212. Connect with manage identity

9. For Connection name, input a connection name, such as Zscaler-Oauth2-LookupURL.

10. Click Create, then click Save.

Figure 213. Connection name

To change the ZIA base URL for this playbook, you can modify the Microsoft Logic app designer step Initialize variable -
Define Base URL.

Deploying the Zscaler-Oauth2-UnblacklistURL Playbook

To install and configure this playbook, complete the following:

1. Download the Zscaler-Oauth2-UnblacklistURL playbook from the Zscaler GitHub repo for Microsoft Sentinel
Playbooks.
2. Go to the Zscaler-Oauth2-UnblacklistURL folder, review the README.md file, and click Deploy to Azure.

Figure 214. Deploy to Azure

©2023 Zscaler, Inc. All rights reserved. 138

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

3. Select your subscription, resource group, and region to which you want to deploy the template.
4. Click Review + create, then Create.

Figure 215. Custom deployment

5. Go to Azure Services > Logic apps and your imported logic app appears on your list of logic apps.

Figure 216. Logic apps

6. To authorize the connection, select the Zscaler-Oauth2-UnblacklistURL logic app, then go to Logic app designer and
select the Entities – Get URLs step. In that step, click Change connection.

Figure 217. Change connection

©2023 Zscaler, Inc. All rights reserved. 139

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

7. Select Add new > Connect with managed identity.

Figure 218. Connect with manage identity

8. For Connection name, enter a connection name, such as Zscaler-Oauth2-UnblacklistURL.

Figure 219. Connection name

9. Click Create, then click Save.

To change the ZIA base URL for this playbook, you can modify the Microsoft Logic app designer step Define Base URL.

©2023 Zscaler, Inc. All rights reserved. 140

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

Deploying the Zscaler-Oauth2-UnblockIP Playbook

To install and configure this playbook, complete the following:

1. Download the Zscaler-Oauth2-UnblockIP playbook from the Zscaler GitHub repo for Microsoft Sentinel Playbooks.
2. Go to the Zscaler-Oauth2-UnblockIP folder, review the README.md file, and click Deploy to Azure.

Figure 220. Deploy to Azure

3. Select your subscription, resource group, and region to which you want to deploy the template.
4. Click Review + create, then Create.

Figure 221. Custom deployment

5. Go to Azure Services > Logic apps and your imported logic app appears on your list of logic apps.

Figure 222. Logic apps

©2023 Zscaler, Inc. All rights reserved. 141

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

6. To authorize the connection, select the Zscaler-Oauth2-UnblockIP logic app, then go to Logic app designer and
select the Entities – Get IPs step.
7. Click Change connection.

Figure 223. Change connection

8. Select Add new > Connect with managed identity.

Figure 224. Connect with managed identity

9. For Connection name, input a connection name, such as Zscaler-Oauth2-UnblockIP.

10. Click Create, then click Save.

Figure 225. Connection name

©2023 Zscaler, Inc. All rights reserved. 142

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

The playbook has been configured to remove an IP in the Other Miscellaneous category. To change it, modify the
Microsoft Logic app designer step Define URL Category. To change the ZIA base URL for this playbook, you can modify
the Microsoft Logic app designer step Define Base URL.

Deploying the Zscaler-Oauth2-UnblockURL Playbook

To install and configure this playbook:

1. Download the Zscaler-Oauth2-UnblockURL playbook from the Zscaler GitHub repo for Microsoft Sentinel
Playbooks.
2. Navigate to the Zscaler-Oauth2-UnblockURL folder, review the README.md file, and click Deploy to Azure.

Figure 226. Deploy to Azure

3. Select your subscription, resource group, and region to which you want to deploy the template.
4. Click Review + create, then Create.

Figure 227. Custom deployment

5. Go to Azure Services > Logic apps and the imported logic app appears on your list of logic apps.

Figure 228. Logic apps

©2023 Zscaler, Inc. All rights reserved. 143

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

6. To authorize the connection, select the Zscaler-Oauth2-UnblockURL logic app, then go to Logic app designer and
select the Entities – Get URLs step.
7. Click Change connection.

Figure 229. Change connection

8. Select Add new > Connect with managed identity.

Figure 230. Connect with managed identity

9. For Connection name, input a connection name, such as Zscaler-Oauth2-UnblockURL.

10. Click Create, then click Save.

Figure 231. Connection name

©2023 Zscaler, Inc. All rights reserved. 144

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

To change the ZIA base URL for this playbook, you can modify the Microsoft Logic app designer step Define Base URL. To
change the URL category for this playbook, you can modify the Microsoft Logic app designer step Define URL category.

Deploying the Zscaler-Oauth2-WhitelistURL Playbook

To install and configure this playbook, complete the following:

1. Download the Zscaler-Oauth2-WhitelistURL playbook from the Zscaler GitHub repo for Microsoft Sentinel
Playbooks.
2. Go to the Zscaler-Oauth2-WhitelistURL folder, review the README.md file, and click Deploy to Azure.

Figure 232. Deploy to Azure

3. Select your subscription, resource group, and region to which you want to deploy the template.
4. Click Review + create, then Create.

Figure 233. Custom deployment

5. Navigate to Azure Services > Logic apps and your imported logic app appears on your list of logic apps.

Figure 234. Logic apps

©2023 Zscaler, Inc. All rights reserved. 145

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

6. To authorize the connection, select the Zscaler-Oauth2-WhitelistURL logic app, then go to Logic app designer and
select the Entities – Get URLs step.
7. Click Change connection.

Figure 235. Change connection

8. Select Add new > Connect with managed identity.

Figure 236. Connect with managed identity

9. For Connection name, input a connection name, such as Zscaler-Oauth2-WhitelistURL.

10. Click Create, then click Save.

Figure 237. Connection name

To change the ZIA base URL for this playbook, you can modify the Microsoft Logic app designer step Define Base URL.

©2023 Zscaler, Inc. All rights reserved. 146

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

Appendix A: Requesting Zscaler Support

You might sometimes need Zscaler Support for provisioning certain services, or to help troubleshoot configuration and
service issues. Zscaler Support is available 24/7/365.

To contact Zscaler Support, go to Administration > Settings > and then click Company Profile.

Figure 238. Collecting details to open support case with Zscaler TAC

Save Company ID
Copy the Company ID if you are using ZIA Admin Portal. Copy the tenant ID if you are using ZPA Admin Portal.

Figure 239. ZIA Company ID

©2023 Zscaler, Inc. All rights reserved. 147

 ZSCALER AND MICROSOFT SENTINEL DEPLOYMENT GUIDE

Enter Support Section

Now that you have your ID, you can open a support ticket. For ZIA, go to Dashboard > Support > Submit a Ticket. For
ZPA, go to Dashboard > Tools > Submit a Ticket.

Figure 240. Submit a ticket

©2023 Zscaler, Inc. All rights reserved. 148