Integrate with the Azure Logs Ingestion API

This guide explains how to send ngrok events, including network traffic logs, to Azure via the Logs Ingestion API. This is useful if you want to keep an audit log of configuration changes in your ngrok account, record all traffic to your endpoints for active monitoring and troubleshooting, or use it as a SIEM for security inspections. By integrating ngrok with Azure, you can:

Quickly identify application issues in real time using ngrok request events and Azure logs processing.
Historically audit changes occurring in an account.
Profile usage of your service using logs queries and real-time data analytics.
Identify security issues using ngrok events.

Create a Log Analytics workspace

These steps were adapted from the Microsoft documentation for creating a Log Analytics workspace.

In a browser, sign in to the Azure portal.
In the search bar, type Log Analytics Workspaces.
Click the Services entry (not the Marketplace entry).
Click Create on the top bar of the Log Analytics Workspace page.
Follow the wizard to create your Log Analytics Workspace, filling in the region, name, and resource group, then click Review + Create. These values can be anything you like and do not affect ngrok’s ability to send logs to your Azure account.
Click Create at the bottom of the review step to provision the Log Analytics Workspace.

You now have a Log Analytics Workspace, which will be the home for your data collection endpoint, tables, and rules.

Create a data collection endpoint

These steps were adapted from the Microsoft documentation for creating a data collection endpoint.

In the search bar, type Data Collection Endpoints.
Click the Services entry.
Click Create on the top bar of the Data Collection Endpoints page.
Follow the wizard to create your Data Collection Endpoint, filling in the region, name, and resource group, then click Review + Create. These fields can be anything you like and do not affect ngrok’s ability to send logs to your Azure account.
Click Create at the bottom of the review step to provision the Data Collection Endpoint.

You now have a Data Collection Endpoint, which is the network-accessible service that ngrok uses to send events to Azure.

Create a DCR-based custom table in the workspace

These steps were adapted from the Microsoft documentation for creating a new table in a Log Analytics workspace.

Navigate to the Log Analytics Workspaces list again.
Click the workspace you created in the Create a Log Analytics workspace step.
In the sidebar of the selected workspace, go to Settings > Tables.
Click Create on the top bar and click New custom log (DCR-based).
Populate the table name with a name of your choice and the DCE field with the existing DCE you created in the Create a data collection endpoint step.
Under the Data collection rule field, click Create a new data collection rule, which opens a drawer. Fill out the resource group and name, then click Done in the drawer.
Click Next in the table creation wizard.
Upload the following JSON file using the wizard. After uploading, you will see a warning header “TimeGenerated field is not found in the sample provided”; this is expected.

{
	"event_id": "ev_2iKcXvmLJoZojWzrCuLbstBCle0",
	"event_type": "test",
	"event_timestamp": "2024-06-24T15:25:52Z",
	"object": {}
}

Not to worry!You will see a warning header “TimeGenerated field is not found in the sample provided”; this is expected. You can fix this using the Transformation Editor.

Click the Transformation editor button on the top bar of the wizard to open a drawer.
Paste in the following transformation and click Run.

source
| extend TimeGenerated = event_timestamp

Click Apply, then Next, then Create.

You now have a Data Collection Rule configured for ngrok events, along with a table where the data will be stored.

Create a Microsoft Entra Application

These steps were adapted from the Microsoft documentation for creating a Microsoft Entra Application.

In the search bar, type Microsoft Entra ID.
Under Services, click Microsoft Entra ID (not the Marketplace item).
In the sidebar, go to Manage > App registrations.
Click New registration.
Name the application ngrok-events or something similar to clarify its use; this entity is what ngrok uses to authenticate with your data collection endpoint.
For account type, choose Accounts in this organizational directory only.
Click Register.

You have now created a Microsoft Entra ID App Registration, which is a service principal that grants roles and access to services like ngrok.

Assign IAM permissions to the Application for the DCR

These steps were adapted from the Microsoft documentation for assigning permissions to the DCR.

In the search bar, type Data collection rules.
Under Services, click Data collection rules.
Click the Data collection rule you created in the Create a DCR-based custom table in the workspace step.
In the sidebar, click Access control (IAM).
Click Add on the top bar.
Click Add role assignment.
Under Job function roles, search for Monitoring.
Click Monitoring Metrics Publisher.
Click Next to go to Members.
Click Select members.
Search for the app registration you created in the Create a Microsoft Entra Application step.
Click the service principal and click Select.
Click Review + assign, then Review + assign again to confirm the role assignment.

You have now granted the ngrok application access to ingest logs into the DCR, which is the final step before creating an Event Destination.

Gather necessary data for event destination

To create an event destination in the ngrok dashboard, gather the following from what you created in Azure:

Tenant ID
Application’s Client ID
Application’s Client Secret
DCR immutable ID
DCR stream name
DCE log ingestion URI
To get the first three fields, go back to Microsoft Entra ID. In the top search bar, search for Entra and click Microsoft Entra ID.
In the sidebar, go to Manage > App registrations and click the application you created in the Create a Microsoft Entra Application step.
On the Overview page, copy Application (client) ID and Directory (tenant) ID.
In the sidebar, go to Manage > Certificates & secrets.
Click New client secret.
Fill in the description and expiry date, then click Add.
Copy the secret value provided by Azure. This value is only shown once; it will not be available after you navigate away.
To get the DCR immutable ID and stream name, navigate to Data collection rules using the top search bar.
Click the Data collection rule you created in the Create a DCR-based custom table in the workspace step.
In the Overview tab, copy the Immutable Id value.
In the sidebar, go to Configuration > Data sources.
Copy the Data source name, which starts with “Custom-” (for example, Custom-NgrokEvents_CL). This is the DCR stream name. Use this value exactly as shown in Azure; passing a different format (such as the table name) results in a 400 InvalidStream error from the Logs Ingestion API.
In the top search bar, navigate to Data collection endpoints.
Click the Data collection endpoint you created in the Create a data collection endpoint step.
In the Overview tab, copy the Logs Ingestion URI.

You now have all the required data to create an event destination with ngrok.

Create the new event destination in ngrok

At this point, you can create the event destination through the ngrok dashboard or via the ngrok API.

Creating through the ngrok dashboard

Sign in to the ngrok dashboard and go to Log Exporting.
Click + New Log Export.
In the Sources tab, click Add Source to choose which events to send to Azure.

To capture traffic events only from specific endpoints or tunnels, add a CEL filter expression when configuring the source. For example, to filter by hostname: ev.conn.server_name == "your-tunnel.ngrok.app". See Log Sources filters for more examples and filter syntax.

In the Destinations tab, click Add Destination.
Click Azure Logs Ingestion API.
Fill in the fields using the values you collected in Step 6.
Click Send Test Event and look for an example event in your Azure account. It may take a minute to appear due to propagation delays.
Click Done and save the new Log Export.

Creating via the ngrok API

Create an API key with ngrok (for example via the ngrok dashboard).
Using your REST API tool of choice (cURL, Postman, and so on), run the following API calls.
To create the Azure Logs Ingestion event destination, run:

curl --location 'https://api.ngrok.com/event_destinations' \
--header 'Accept: application/json' \
--header 'Ngrok-Version: 2' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {API_KEY}' \
--data '{
    "format": "json",
    "target": {
        "azure_logs_ingestion": {
            "tenant_id":     "{TENANT_ID}",
		      "client_id":     "{CLIENT_ID}",
		      "client_secret": "{CLIENT_SECRET}",

		      "logs_ingestion_uri":          "{DCE_LOGS_INGESTION_URI}",
		      "data_collection_rule_id":     "{DCR_RULE_ID}",
		      "data_collection_stream_name": "{DCR_STREAM_NAME}"
         }
    }
}'

Copy the returned event destination ID from the response.

To create a log export (event subscription) using the event destination you created, run:

curl \
-X POST \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{
   "description":"ip policy creations",
   "destination_ids":["{EVENT_DESTINATION_ID}"],
   "sources":[
      {"type":"ip_policy_created.v0"},
      {"type":"{MORE_EVENT_TYPES}"}
   ]
}' \
https://api.ngrok.com/event_subscriptions

After you get a 200 response, your event destination is configured and subscribed to the set of event types you specified.

General Guides

CLI Credentials

Dashboard SSO

Databases

Endpoints SSO

Event Destinations

Frameworks

JWT Validation

Kubernetes Ingress

OAuth

Protocols

Webhooks

Web Servers

Integrate with the Azure Logs Ingestion API

Create a Log Analytics workspace

Create a data collection endpoint

Create a DCR-based custom table in the workspace

Create a Microsoft Entra Application

Assign IAM permissions to the Application for the DCR

Gather necessary data for event destination

Create the new event destination in ngrok

Creating through the ngrok dashboard

Creating via the ngrok API

Create a Log Analytics workspace

Create a data collection endpoint

Create a DCR-based custom table in the workspace

Create a Microsoft Entra Application

Assign IAM permissions to the Application for the DCR

Gather necessary data for event destination

Create the new event destination in ngrok

​Creating through the ngrok dashboard

​Creating via the ngrok API

Creating through the ngrok dashboard

Creating via the ngrok API