For the complete documentation index, see llms.txt. This page is also available as Markdown.

Connecting Azure Log Analytics Workspace

Connect an Azure Log Analytics workspace to RealmJoin Portal with the RealmJoin PowerShell module to store audit, operational and runbook logs in your own tenant.

Overview

RealmJoin Portal can use a Log Analytics workspace in your own Azure subscription to store

  • its audit log — every action performed in the Portal, see Audit Log

  • its operational logs

  • runbook logs, archived beyond the maximum retention of Azure Automation (currently 30 days)

The workspace is set up with the RealmJoin PowerShell module. The Portal generates a ready-to-copy command for you — there is nothing to fill in by hand.

Is Log Analytics already configured for your tenant and using the deprecated Data Collector API? Then follow Migrating to the Log Ingestion API instead — it reuses your existing workspace and keeps your existing logs.

Components

RealmJoin writes its logs through the Azure Monitor Logs Ingestion API, based on Data Collection Rules (DCRs) and Microsoft Entra ID authentication. Running the setup command creates:

  • The RealmJoin Azure Resources service principal in your Entra ID tenant (if it does not exist yet)

  • A Log Analytics workspace in the resource group you choose — or your existing workspace, if you name one

  • Three custom tables in that workspace: RJAuditLogs_CL, RJOperationalLogs_CL, RJRunbookLogs_CL

  • One Data Collection Rule per table (dcr-rj-aud-logs-*, dcr-rj-op-logs-*, dcr-rj-rb-logs-*), each with its own direct ingestion endpoint

  • Exactly two kinds of role assignment for RealmJoin, and nothing beyond them:

    • Log Analytics Reader on the workspace, so the Portal can query your logs

    • Monitoring Metrics Publisher on each of the three Data Collection Rules, so RealmJoin can write to them

RealmJoin receives no other permission in your subscription. No app registration, no client secret and no workspace shared key are involved. The deployment is idempotent — re-running the same command is safe and only applies what is missing.

Prerequisites

In the RealmJoin Portal

  • A role that grants access to the Settings area (CanReadSettingsDetails, see Available Permissions). The settings page generates the setup command including a short-lived onboarding token.

In Azure

  • An Azure subscription and an existing resource group to deploy into — the module does not create the resource group

  • Optionally an existing Log Analytics workspace. If you do not name one, a workspace is created for you in the region of the resource group.

On the machine running PowerShell

  • PowerShell 5.1 or later (Windows PowerShell or PowerShell 7)

  • Access to the PowerShell Gallery to install the RealmJoin module

  • The Az.Accounts, Az.Resources and Az.Automation modules — the RealmJoin module installs them in the pinned versions automatically, for the current user

Permissions of the account you sign in with

  • Microsoft Entra ID: permission to create service principals, for example Application Administrator, Cloud Application Administrator or Global Administrator. Only needed the first time, when the RealmJoin Azure Resources service principal does not exist yet.

  • Azure subscription: permission to deploy into the resource group and to create role assignments on it — for example Owner, or Contributor combined with User Access Administrator / Role Based Access Control Administrator.

  • Sign-in happens through Connect-AzAccount, which uses the Azure PowerShell first-party application. Tenants that restrict user consent may need to grant admin consent to that application first.

Setup

1

Prepare the resource group

In the Azure Portal, create or pick the resource group that should hold the workspace. Note its name, and the ID of the subscription it lives in.

If you want to use an existing Log Analytics workspace, note its name as well.

2

Copy the command from the RealmJoin Portal

In the RealmJoin Portal, navigate to Settings → Log Analytics (https://portal.realmjoin.com/settings/log-analytics-configuration).

The page states that Log Analytics is managed via the RealmJoin PowerShell module and shows a command block. Use the Copy button to copy it.

The first lines install or update the RealmJoin module and import it. Set-RJLogAnalyticsWorkspace performs the deployment and registers the result with RealmJoin using the -Token.

About 6>&1: these commands report their progress on PowerShell's Information stream. The 6>&1 redirection displays that output in the console — without it you will not see any progress messages.

3

Add the target parameters

Set-RJLogAnalyticsWorkspace needs to know where to deploy. Complete the last line before running it:

  • -ResourceGroupName is required. If you leave it out, PowerShell prompts you for it.

  • -SubscriptionId is optional — without it, the subscription of your current Azure context is used, and you are asked to choose if several are available.

  • -WorkspaceName is optional. Pass it to define the name of a new workspace or to use an existing workspace; otherwise a new one is created with a generated name.

4

Run the command

Paste the block into a new PowerShell session and run it. The token is valid for roughly an hour — if it has expired, reload the settings page and copy the command again.

You will be prompted to sign in with Connect-AzAccount. If your account has access to several tenants or subscriptions, the module asks you to choose.

The deployment then reports every resource as it is created: the service principal, the workspace, the custom tables, the Data Collection Rules and the role assignments. A single run usually takes a few minutes.

Want to see what would happen first? Append -WhatIf for an Azure Resource Manager What-If preview. Note that signing in and installing the Az modules still happens, because the preview needs both.

Signing out afterwards: the Azure sign-in stays active after the command has finished. Once you are done, run Disconnect-AzAccount to sign out of the existing session.

5

Verify in the Portal

Return to Settings → Log Analytics and select Refresh.

The page now shows subscription, resource group, workspace name, customer workspace ID and tenant ID as read-only fields — these settings are maintained by the PowerShell module from now on. Under Advanced you can review the endpoints, rule names and stream names of the three Data Collection Rules.

Select Check for configuration problems to verify that all required Azure permissions are in place on the workspace and on each Data Collection Rule.

Afterwards, open the Audit Log or the Runbook Logs and confirm that entries appear. Azure needs a few minutes to make newly created custom tables available.

Data retention

Keeping the schema up to date

If RealmJoin extends the log schema in a future release, the settings page shows a notice that the deployed Log Analytics schema is out of date, along with the command to update it. That is the same Set-RJLogAnalyticsWorkspace command — run it again and the tables and rules are updated in place.

Legacy setup (Data Collector API)

Show the legacy setup

On this path, RealmJoin authenticated with a customer-owned Entra ID app registration and the workspace's shared key, and wrote into the tables AuditLogs_CL, OperationalLogs_CL and RunbookLogs_CL.

Part 1 — Authentication using an Azure app registration

  1. In the Azure Portal, navigate to Microsoft Entra ID > Manage > App Registrations.

  2. Select the All Applications tab.

  3. Either re-use the "RealmJoin Runbooks Management" app registration created when onboarding runbooks, or select "New Registration" and register a new application.

  4. On the application, navigate to Manage > Certificates & Secrets, select the "Client Secrets" tab and create a new client secret. Set description and expiration according to your internal naming and security policies.

  5. Securely note down the secret value — navigating away from the page causes Azure to obfuscate it, and a new secret has to be created.

Part 2 — Creating a Log Analytics workspace

  1. In the Azure Portal, navigate to Log Analytics Workspace and select Create.

  2. Provide a resource group, name and region as required.

  3. On the "Overview" tab, note the resource group name, workspace name and workspace ID.

Part 3 — Azure permissions

  1. Navigate to the subscription your Log Analytics workspace resides in.

  2. Select Access Control (IAM) and add a role assignment.

  3. Grant your app registration Monitoring Contributor on the workspace used for RealmJoin logs.

  4. Review and save the role assignment.

Part 4 — Connecting RealmJoin and the workspace

In the RealmJoin Portal, navigate to Settings > Log Analytics and fill in the fields:

  • TenantId — your Entra ID tenant ID, from the Entra ID Overview page

  • ClientId and ClientSecret — the app registration from Part 1

  • Subscription ID, Resource Group and Workspace Name — of the workspace from Part 2

  • Customer Workspace Id — the workspace ID of the workspace storing RealmJoin audit and runbook log data

  • Customer Workspace Key — the workspace's "Primary Key", which allows RealmJoin to write data. It can be retrieved with the Azure CLI (az monitor log-analytics workspace get-shared-keys --resource-group MyResourceGroup --workspace-name MyWorkspace) or with PowerShell (Get-AzOperationalInsightsWorkspaceSharedKey -ResourceGroupName "MyResourceGroup" -Name "MyWorkspace").

Press Save after filling out all fields. The system gives you feedback if everything worked.

Last updated

Was this helpful?