Connect your Azure subscription to OpsCompanion using Azure Lighthouse delegation (recommended)

Azure Lighthouse Setup Guide

Azure Lighthouse is the recommended method for connecting your Azure subscription to OpsCompanion. It provides transparent, secure, read-only access without creating service principals in your tenant.

Overview

Azure Lighthouse uses delegated resource management to grant OpsCompanion read-only access to your subscription. Instead of creating credentials in your tenant, you deploy an ARM template that delegates access to OpsCompanion's service principal.

Key Benefits

No credential management: No secrets to store or rotate in your tenant
Transparent permissions: ARM template clearly shows exact permissions granted
Instant revocation: Remove delegation anytime in Azure Portal
Full audit trail: All OpsCompanion actions logged in your Activity Log
One-click deployment: Deploy via Azure Portal in under 2 minutes

How It Works

Your Subscription
    └─ Lighthouse Delegation
        └─ Grants access to: OpsCompanion Service Principal
            └─ Role: Reader (read-only)
                └─ OpsCompanion can:
                    ✓ View resources (VMs, storage, databases, etc.)
                    ✓ Access monitoring metrics and logs
                    ✓ Query activity logs
                    ✗ Modify or delete resources
                    ✗ Access secrets or keys

Prerequisites

Before you begin, ensure you have:

1. Azure Subscription Access

You need one of these roles in your Azure subscription:

Owner - Full access (recommended)
User Access Administrator + Reader - Can assign roles

Check your role:

az role assignment list --assignee $(az account show --query user.name -o tsv) --output table

2. Your Azure Subscription ID

# Get your current subscription ID
az account show --query id --output tsv

# Or list all subscriptions
az account list --query "[].{Name:name, SubscriptionId:id}" --output table

Example: bc5ff704-4017-454a-bf43-53bd74f6c04f

Installation Steps

Step 1: Deploy the Lighthouse Delegation Template

You have two options for deploying the template:

Option A: Deploy via Azure Portal (Recommended)

Navigate to OpsCompanion Dashboard
Go to Integrations → Microsoft Azure
Click "Deploy to Azure Portal"
A new tab opens with Azure Portal
Select your Subscription from the dropdown
Select a Region (e.g., eastus)
Click "Review + Create"
Review the template details:
- Service Provider: OpsCompanion
- Permissions: Reader (read-only)
- Principal: OpsCompanion Service Principal
Click "Create"

Deployment time: 30-60 seconds

Option B: Deploy via Azure CLI

# Download the template
curl -o lighthouse-delegation.json \
  https://opscompanion-templates.s3.us-east-2.amazonaws.com/azure/opscompanion-lighthouse-delegation.json

# Deploy to your subscription
az deployment sub create \
  --location eastus \
  --template-file lighthouse-delegation.json

# Wait for deployment to complete

Step 2: Complete Setup in OpsCompanion

Return to the OpsCompanion tab (or open OpsCompanion Dashboard)
In the Azure integration setup:
- Scroll down to "Step 2: Enter your subscription ID"
- Paste your Azure subscription ID
- Click "Complete Setup"
OpsCompanion will:
- Validate the subscription ID format
- Store the subscription ID
- Redirect you to the workspace
Success! You can now query your Azure resources via chat.

What Gets Created

The Lighthouse delegation creates two Azure resources:

1. Registration Definition

{
  "type": "Microsoft.ManagedServices/registrationDefinitions",
  "properties": {
    "registrationDefinitionName": "OpsCompanion Infrastructure Monitoring",
    "description": "Read-only access for infrastructure monitoring and observability",
    "managedByTenantId": "5c625a63-32ed-4dea-b26a-d86d96bdbe39",
    "authorizations": [{
      "principalId": "4d5d1cda-40da-42b2-bbe7-19c1d753c9a8",
      "roleDefinitionId": "acdd72a7-3385-48ef-bd42-f606fba81ae7",
      "principalIdDisplayName": "OpsCompanion Service Principal"
    }]
  }
}

What this means:

managedByTenantId: OpsCompanion's Azure tenant
principalId: OpsCompanion's service principal
roleDefinitionId: Built-in "Reader" role (read-only)

2. Registration Assignment

Activates the delegation defined above. This is what actually grants OpsCompanion access to your subscription.

Verification

Verify Delegation is Active

Via Azure Portal:

Navigate to Subscriptions → Select your subscription
Go to Access Control (IAM) → Role Assignments
Look for: OpsCompanion Service Principal with Reader role

Via Azure CLI:

# List all delegations for your subscription
az managedservices assignment list --output table

# Expected output should include:
# Name: OpsCompanion Infrastructure Monitoring
# State: Active

Test Access

In OpsCompanion chat, ask: "Show me my Azure VMs"
OpsCompanion should return a list of your virtual machines
Try other queries:
- "What storage accounts do I have?"
- "Show me my SQL databases"
- "List all my resource groups"

If queries work, delegation is functioning correctly!

What OpsCompanion Can Access

With the Reader role, OpsCompanion can view:

Compute

Virtual machines and their configuration
VM scale sets
Azure Kubernetes Service (AKS) clusters
App Services and Function Apps

Storage

Storage accounts (metadata only, not file contents)
Disk configurations

Databases

SQL databases and servers
Cosmos DB accounts
Azure Database for PostgreSQL/MySQL

Networking

Virtual networks and subnets
Network security groups
Load balancers
Application gateways

Monitoring

Azure Monitor metrics
Log Analytics workspaces
Application Insights telemetry
Activity logs

Other Resources

Resource groups
Tags and metadata
Cost and billing data

What OpsCompanion Cannot Access

The Reader role explicitly cannot:

Modify resources: Cannot create, update, or delete anything
Access secrets: Cannot read Key Vault secrets, storage keys, connection strings, or passwords
Execute actions: Cannot start/stop VMs, regenerate keys, or trigger operations
Change permissions: Cannot modify RBAC assignments or policies
Access data: Cannot read file contents from storage accounts or data from databases
Modify billing: Cannot change payment methods or billing settings

Example operations blocked:

✓ Read VM configuration
✗ Start/stop VM
✓ View storage account metadata
✗ List storage account keys
✓ View Key Vault properties
✗ Read secret values
✓ View SQL server configuration
✗ Query database data

Security Considerations

Read-Only Access

The integration is designed with the principle of least privilege:

Reader role only: Minimum permissions needed for monitoring
No write access: Cannot modify your infrastructure
No secret access: Cannot read sensitive data
Subscription-scoped: Access limited to the specific subscription you delegated

Audit and Compliance

Activity Logging:

All OpsCompanion actions are logged in your Azure Activity Log. View them:

# View OpsCompanion activity in the last 7 days
az monitor activity-log list \
  --caller 4d5d1cda-40da-42b2-bbe7-19c1d753c9a8 \
  --start-time $(date -u -d '7 days ago' '+%Y-%m-%dT%H:%M:%SZ') \
  --query "[].{Time:eventTimestamp, Operation:operationName.localizedValue, Resource:resourceId}" \
  --output table

Compliance:

✓ SOC 2 compliant (audit trail)
✓ ISO 27001 compliant (access control)
✓ GDPR compliant (no data storage, read-only)
✓ HIPAA eligible (when Azure subscription is HIPAA-compliant)

Data Privacy

OpsCompanion's approach to data:

What is stored:

Your subscription ID (public identifier, not sensitive)
Resource metadata (names, types, regions)

What is NOT stored:

Credentials or secrets
File contents from storage
Database data
Key Vault values
Personal data from your applications

Tenant Isolation

How isolation works:

OpsCompanion operates from its own Azure tenant (separate from yours)
No service principal created in your tenant
No credentials stored in your tenant
Cross-tenant delegation uses Azure's built-in Lighthouse mechanism

Your control:

You own the delegation (it's in your subscription)
You can revoke access anytime
You can audit all actions
You can see exactly what permissions are granted

Troubleshooting

Issue: "No resources showing" in OpsCompanion

Possible causes:

Lighthouse delegation not deployed yet
Wrong subscription ID entered
Delegation still propagating (can take 1-2 minutes)

Solution:

# Verify delegation exists
az managedservices assignment list --output table

# If no delegation found, redeploy the template
az deployment sub create \
  --location eastus \
  --template-file lighthouse-delegation.json

# If delegation exists, verify subscription ID in OpsCompanion matches:
az account show --query id --output tsv

Issue: "Access Denied" errors

Possible causes:

Delegation was removed
Azure RBAC propagation delay

Solution:

# Check if delegation still exists
az managedservices assignment list --output table

# If missing, redeploy template
# If present, wait 5 minutes for RBAC to propagate

Issue: "Invalid subscription ID format"

Cause: Subscription ID not in correct UUID format

Solution:

Subscription ID must be a valid UUID (e.g., xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)
Get correct ID: az account show --query id --output tsv
Copy-paste carefully (no extra spaces or characters)

Issue: "Subscription already connected to another organization"

Cause: This subscription ID is already in use by a different OpsCompanion organization

Solution:

Each Azure subscription can only be connected to one OpsCompanion organization
If you need to move it, contact support@opscompanion.ai
If multiple people in your company use OpsCompanion, coordinate to use the same organization

Updating the Integration

Rotating Credentials (Not Required)

Unlike OAuth flows, Lighthouse delegations don't require credential rotation because:

No secrets stored in your tenant
OpsCompanion manages its own credentials
Delegation uses Azure's built-in trust mechanism

You only need to act if OpsCompanion notifies you of a required update (rare).

Changing Permissions

If you want to modify permissions granted:

Remove existing delegation:

# List delegations
az managedservices assignment list --query "[].id" --output tsv

# Delete delegation (replace with actual ID)
az managedservices assignment delete --assignment <assignment-id>

Modify template (if needed):
- Download template from OpsCompanion
- Edit roleDefinitionId to different role (not recommended)
- Redeploy modified template
Redeploy template:

az deployment sub create \
  --location eastus \
  --template-file modified-lighthouse-delegation.json

Note: OpsCompanion expects Reader role. Using a different role may cause features to not work correctly.

Adding Multiple Subscriptions

To monitor multiple Azure subscriptions:

For each subscription:

# Switch to the subscription
az account set --subscription "<subscription-id-or-name>"

# Deploy delegation
az deployment sub create \
  --location eastus \
  --template-file lighthouse-delegation.json

In OpsCompanion:
- Add each subscription as a separate integration
- Use the "Add Integration" button to add another Azure connection

Removing the Integration

From OpsCompanion

Navigate to Integrations → Microsoft Azure
Click "Manage" or "Remove"
Confirm removal

This removes the integration from OpsCompanion but does not revoke Azure access.

From Azure (Revoke Access)

Via Azure Portal:

Navigate to Subscriptions → Select your subscription
Go to Access Control (IAM) → Role Assignments
Find OpsCompanion Service Principal
Click Remove

Via Azure CLI:

# List delegations
az managedservices assignment list --query "[].id" --output tsv

# Delete delegation (replace with actual ID from above)
az managedservices assignment delete --assignment <assignment-id>

Effect: OpsCompanion immediately loses access to your subscription. No coordination needed.

Comparison to Other Setup Methods

Feature	Lighthouse	Terraform	Bash Script
Setup Time	2 minutes	5-10 minutes	3-5 minutes
Deployment Method	Azure Portal (1-click)	Terraform apply	Bash script
Credentials Created	None (in your tenant)	Service Principal	Service Principal
Secrets to Manage	0	1	1
Transparency	High (ARM template review)	High (Terraform code)	Medium (script code)
Revocation	Instant (delete delegation)	Requires Terraform destroy	Manual deletion
Enterprise Friendly	Very	Yes	Moderate
Recommended For	All users	IaC users	CLI users

Recommendation: Use Lighthouse for the simplest and most secure setup. Use Terraform or Bash if you need service principals for other reasons.

Documentation: https://opscompanion.ai/docs
Community: https://discord.gg/TdMZTqSFTq
Email: support@opscompanion.ai

Reporting Issues

If you encounter issues with the Lighthouse integration:

Check the Troubleshooting section above
Verify delegation is active: az managedservices assignment list
Test access in OpsCompanion chat: "Show me my Azure VMs"
If still having issues, contact support with:
- Subscription ID (first 8 characters only)
- Error message from OpsCompanion
- Output of az managedservices assignment list

Last updated: January 2026 Lighthouse template version: 1.0

Azure Lighthouse Setup Guide

On this page