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.
1. 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.
2. 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.
3. 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 Step 1.
- In the sidebar of the selected workspace, go to Settings > Tables.
- Click Create on the top bar and select 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 Step 2.
- 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.
4. 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, select 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, select the first option: 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.
5. 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, select Data collection rules.
- Click the Data collection rule you created in Step 3.
- 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 Step 4.
- 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.
6. 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 select the Microsoft Entra ID service.
-
In the sidebar, go to Manage > App registrations and select the application you created in Step 4.
-
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.
-
Select the Data collection rule you created in Step 3.
-
In the Overview tab, copy the Immutable Id value.
-
In the sidebar, go to Configuration > Data sources.
-
Copy the Data source name, which should start with Custom_ and end with _CL.
This is the DCR stream name.
-
In the top search bar, navigate to Data collection endpoints.
-
Select the Data collection endpoint you created in Step 2.
-
In the Overview tab, copy the Logs Ingestion URI.
You now have all the required data to create an event destination with ngrok.
7. 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 Traffic Observability > Events Stream.
- Create a new Log Export using the plus sign in the top left, or open an existing one.
- After adding one or more sources, select the Destinations tab and click Add Destination.
- Select 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, etc.), 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}"
}
}
}'
- 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
