StratoLens Installation Guide

Deploy StratoLens to your Azure environment from the Azure Marketplace. This guide covers prerequisites, permissions, and the four-step installation from Marketplace provisioning through first sign-in.

Permission Requirements

StratoLens installation requires elevated Microsoft Entra ID permissions to configure authentication and enable tenant-wide scanning capabilities. These elevated permissions are only required during the initial installation process and are not needed for ongoing operation.

Required Access Summary

At minimum, you need:

Why These Permissions Are Needed

Elevate Access to the Tenant Root

Global Administrators do not have access to manage Azure subscriptions and management groups by default. The setup script needs to assign the Reader role to the StratoLens scanner managed identity at the Tenant Root Management Group, which requires this access. If you're a Global Administrator, you can grant it to yourself by toggling on Access management for Azure resources in your tenant's properties.

Toggle on Access management for Azure resources

1. Sign in to the Azure Portal with a Global Administrator account.
2. Navigate to Microsoft Entra ID.
3. In the left navigation, scroll down and click Properties.
4. Find the Access management for Azure resources section.
5. Toggle the switch to Yes, then click Save.

Once enabled, your account is granted the User Access Administrator role at the tenant root scope, which allows you to assign roles on the Tenant Root Management Group and every subscription and management group beneath it. The setup script will use this access to assign Reader to the scanner managed identity.

1Deploy from Azure Marketplace

Open the StratoLens listing on the Azure Marketplace, choose the subscription you want to use (StratoLens currently offers a single plan, selected by default), and click Create to launch the deployment wizard.

The portal link takes you straight to the Create wizard (you'll be asked to sign in). The marketplace link is public and shows the listing, pricing, and screenshots without sign-in.

Marketplace Wizard Inputs

The Create StratoLens wizard has four tabs: Basics, Resource Names, Networking, and Review + submit.

Basics tab

Fill in the project and instance details:

Resource Names tab

The second tab shows the names of each Azure resource the offer will create. All names are pre-populated from your Company Name (for example, Company Name contoso produces ca-contoso-stratolens, cosmos-contoso-stratolens, etc.). You can customize any of them if your organization has naming conventions that differ from the defaults.

Networking tab

The third tab lets you choose how the StratoLens backends (Cosmos DB and Key Vault) are reached on the network. Pick a Deployment mode:

AdvancedConfiguring Private (network-isolated) mode

Private mode gives you two ways to provide the network. Pick the one that fits your environment:

Option 1: Let StratoLens create the VNet (recommended)

The default, and the right choice for most installs. StratoLens builds a dedicated, correctly sized virtual network with its own subnets and private endpoints, so you don't prepare any networking ahead of time. Choose this unless your security or networking team specifically requires StratoLens to sit inside an existing network.

Selecting Private (network-isolated backends) reveals additional fields for the virtual network, subnets, and private endpoints that StratoLens creates. You can keep the defaults shown below (they are valid and non-overlapping), or define your own naming and address spaces if you have an existing network convention. Just ensure both subnet ranges fall inside the VNet address space and don't overlap.

Private DNS

By default (Create new (recommended)), StratoLens automatically deploys the required private DNS zones, creates the appropriate A records, and wires up DNS resolution for the Cosmos DB and Key Vault private endpoints end to end. You don't have to configure anything.

If you switch the toggle to I'll manage DNS myself (bring your own zones), StratoLens skips creating the private DNS zones so you can use your existing zones instead. You'll be responsible for configuring DNS resolution for the private endpoints yourself.

Don't disable public access until after Step 2

For the initial install, Cosmos DB and Key Vault are deployed with public network access enabled, so the setup script in Step 2 can reach them and run. This is expected.

Once that script completes, you can (and should) fully disable public network access on both the Cosmos DB account and the Key Vault as a manual step. Do not disable it before running the Step 2 script, or the setup will fail.

Option 2: Bring your own VNet (deploy into an existing network)

For when your organization needs StratoLens to live inside a network you already control (a spoke in a hub-and-spoke topology, a VNet with existing peering, firewall routing, or address-management rules). Set Virtual network source to Use existing and point the wizard at your own VNet and subnets. The installer never modifies your VNet; you prepare it up front. This is considerably more work than Option 1, and every prerequisite below has to be right before you deploy or the install fails.

Prepare the VNet before you deploy

The VNet must live in the same subscription and region you'll deploy StratoLens into, and you'll need permission to create networking resources and to assign roles on it. Everything below must be done by you ahead of time. You can do it in the Azure portal or with the CLI; adjust names and address space to suit.

1. Prepare two subnets

StratoLens needs two subnets in your VNet. The wizard dropdowns are pre-filtered: the Container Apps list shows only eligible subnets, and so does the private endpoint list. If a dropdown is empty, create or delegate a suitable subnet first.

Subnet	Requirements
Container Apps subnet	/27 or larger, delegated to Microsoft.App/environments, and empty (not used by any other Container Apps environment).
Private endpoint subnet	/27 or larger, with no service delegation and at least 2 free IP addresses. This is where the Cosmos DB and Key Vault private endpoints land.

2. Make sure the app has outbound egress

The app needs outbound internet access to pull its container image and reach Azure Resource Manager, Microsoft Graph, and the StratoLens license server. If your VNet routes traffic through a firewall, NAT, or user-defined routes, or the subnets were created with default outbound access disabled (a private subnet), you must provide egress (for example a NAT gateway) and allow those destinations.

Running behind a firewall?

The Networking tab has a Running behind a firewall? info banner (visible in the screenshot above). Click the link in that banner to open the exact outbound allow-list StratoLens needs, then add those rules to your firewall before deploying.

3. Grant the deployment principal permission to join your subnets

Required prerequisite: grant this before deploying

StratoLens installs as an Azure Marketplace managed application, so its resources are created by a first-party Azure service principal, not by the signed-in user. That principal has rights only inside the managed resource group and none on a VNet you bring, so unless you pre-grant it access the deployment fails partway with LinkedAuthorizationFailed on Microsoft.Network/virtualNetworks/subnets/join/action.

The principal's application id is the same in every tenant (35cbcc06-defd-44d2-ace4-bc2bf2466970); its object id is unique to yours. In the portal IAM picker it usually appears as Managed Applications On Behalf Application. Grant it Network Contributor on the VNet before deploying (resolve the object id first so the assignment doesn't depend on a Graph lookup that can fail intermittently):

Azure CLI (Bash / Cloud Shell)Copy

# (optional) confirm the principal name in your tenant
az ad sp show --id 35cbcc06-defd-44d2-ace4-bc2bf2466970 --query displayName -o tsv

# resolve its object id, then assign the role on your VNet
OID=$(az ad sp show --id 35cbcc06-defd-44d2-ace4-bc2bf2466970 --query id -o tsv)
az role assignment create \
  --assignee-object-id "$OID" \
  --assignee-principal-type ServicePrincipal \
  --role "Network Contributor" \
  --scope "/subscriptions/<SUB_ID>/resourceGroups/<VNET_RG>/providers/Microsoft.Network/virtualNetworks/<VNET_NAME>"

Prefer least privilege?

Instead of Network Contributor you can use a custom role with just Microsoft.Network/virtualNetworks/subnets/join/action (plus virtualNetworks/read and subnets/read), scoped to only the two subnets.

4. Bring your own DNS zones (only if you're managing DNS yourself)

If you keep Create new (recommended) for Private DNS zones, skip this: the template wires them for you. If you chose I'll manage DNS myself, make sure these two zones exist and are linked to this VNet so the app can resolve its backends:

• privatelink.documents.azure.com (Cosmos DB)
• privatelink.vaultcore.azure.net (Key Vault)

5. Select your network on the Networking tab, then deploy

With the VNet prepared, launch the deployment and, on the Networking tab (Step 1):

• Deployment mode: Private (network-isolated backends)
• Virtual network source: Use existing, then select your VNet
• Container Apps subnet: your delegated, empty subnet from step 1
• Private endpoint subnet: your non-delegated subnet from step 1
• Private DNS zones: Create new (recommended), or manage yourself if you prepared the zones in step 4

From here the flow is identical to a new-VNet deployment: complete the wizard, then run the setup script in Step 2 while public access is still enabled, and disable public access on Cosmos DB and Key Vault afterward as described in the warning above.

Already failed with LinkedAuthorizationFailed?

If a deployment failed before you granted the join permission, delete the failed managed application, run the step 3 grant, then redeploy.

On the Review + submit tab, review your selections and click Create. Azure will provision the Container Apps environment, Container App, Scheduler Job, Cosmos DB, Key Vault, Log Analytics workspace, and the managed identity into the Managed Resource Group you chose.

2Run the Setup Script

Once the Marketplace deployment finishes, open the newly-provisioned Container App in the Azure Portal and navigate to its Application Url. You'll land on the StratoLens Setuppage, which contains a one-line PowerShell command pre-filled with all of your deployment's values (resource group, subscription ID, container app name, managed identity, Key Vault, and more).

Before You Run the Command: Prerequisites

Have all three of the following ready before you click Copy to Clipboard on the Setup page:

Running the Setup Command

1. On the StratoLens Setup page, click Copy to Clipboard to copy the pre-filled command.
2. Open Azure Cloud Shell from the Azure Portal and confirm the shell type is PowerShell.
3. Paste the command into Cloud Shell and press Enter.
4. Wait for the script to finish. It prints progress as it runs.

What the Script Does

Running the setup command performs four actions in your tenant:

1. Creates a StratoLens admin user. Sets up the initial administrator inside the StratoLens app. They'll be able to add additional users from within StratoLens once it's up.
2. Registers two Azure AD apps. Creates one Entra ID app registration for signing in to StratoLens (with the required Microsoft Graph API permissions), and a second one named StratoLens Notifications that StratoLens uses to send email notifications.
3. Assigns managed identity permissions. Grants the scanner managed identity Reader access across your tenant so StratoLens can discover resources.
4. Installs the StratoLens container. Replaces the Setup page with the full StratoLens application.

$MI_OBJECT_ID = "<MANAGED-IDENTITY-OBJECT-ID>"
$GRAPH_SP_ID = $(az ad sp show --id "00000003-0000-0000-c000-000000000000" --query id -o tsv)

# Application.Read.All
az rest --method POST --uri "https://graph.microsoft.com/v1.0/servicePrincipals/$MI_OBJECT_ID/appRoleAssignments" --headers "Content-Type=application/json" --body "{`"principalId`":`"$MI_OBJECT_ID`",`"resourceId`":`"$GRAPH_SP_ID`",`"appRoleId`":`"9a5d68dd-52b0-4cc2-bd40-abcf44ac3a30`"}"

# User.Read.All
az rest --method POST --uri "https://graph.microsoft.com/v1.0/servicePrincipals/$MI_OBJECT_ID/appRoleAssignments" --headers "Content-Type=application/json" --body "{`"principalId`":`"$MI_OBJECT_ID`",`"resourceId`":`"$GRAPH_SP_ID`",`"appRoleId`":`"df021288-bdef-4463-88db-98f22de89214`"}"

# Group.Read.All
az rest --method POST --uri "https://graph.microsoft.com/v1.0/servicePrincipals/$MI_OBJECT_ID/appRoleAssignments" --headers "Content-Type=application/json" --body "{`"principalId`":`"$MI_OBJECT_ID`",`"resourceId`":`"$GRAPH_SP_ID`",`"appRoleId`":`"5b567255-7703-4780-807c-7be8301ae99b`"}"

$TENANT_ID = $(az account show --query tenantId -o tsv)

az role assignment create --assignee-object-id "<MANAGED-IDENTITY-OBJECT-ID>" --assignee-principal-type ServicePrincipal --role "Reader" --scope "/providers/Microsoft.Management/managementGroups/$TENANT_ID"

# Graph permissions
az rest --method GET --uri "https://graph.microsoft.com/v1.0/servicePrincipals/<MANAGED-IDENTITY-OBJECT-ID>/appRoleAssignments"

# Reader role
az role assignment list --assignee "<MANAGED-IDENTITY-OBJECT-ID>" --scope "/providers/Microsoft.Management/managementGroups/<TENANT-ID>" --role "Reader" -o table

3Grant Admin Consent

When the setup script finishes, it prints a DEPLOYMENT COMPLETE – ADMIN CONSENT REQUIRED banner with two Azure Portal URLs, one for each app registration the script created. You must grant admin consent on both:

1. Authentication app (used for signing in to StratoLens). Permissions: User.Read.All, Group.Read.All.
2. Email notifications app (named StratoLens Notifications). Permissions: User.Read, Mail.Send, offline_access.

For each URL the script prints:

1. Open the link in the Azure Portal, signed in as a user who can grant admin consent (Global Administrator or Privileged Role Administrator).
2. Review the permissions, then click the blue Grant admin consent for [Your Organization] button.
3. Click Yes to confirm. The Status column will switch from Not granted to a green check for each permission.

4Access StratoLens & First-Time Setup

Once the application deploy completes, your StratoLens URL is displayed in the script output. You can also find it in the Azure Portal by navigating to the Container App named ca-{company}-stratolens and viewing the Application Url on the Overview page.

Sign in with your Entra ID (Azure AD) credentials. The user who ran the setup script in Step 2 is the initial StratoLens administrator and has full access. What follows is a walkthrough of the first-time setup flow.

1. Sign in and land on the Dashboard

After sign-in you arrive at the Executive Dashboard. A banner at the top of the page notes that registration is still incomplete.

2. Register your StratoLens instance

Click the registration banner. You'll be routed to Settings → General. Fill in Company Name and Technical Contact (Billing Contact is optional) and click Save Changes. This information is used for license management and support.

3. Accept the Terms of Service

Once registration is saved, the registration banner clears and a new banner prompts you to accept the Terms of Service. Clicking it opens the Terms of Service modal. Review the terms and click I Accept to continue.

4. (Optional) Verify your license

Back in Settings → General, the License Status panel now shows your license state: Install ID, API reachability, expiry date, and days remaining. Click Check License Status to refresh.

5. Run your first scan

Navigate to Scans → Overview and click Start New Scan. StratoLens will check registration and Terms first (re-prompting if either is missing), then verify the scanner identity's permissions.

Once the scan starts, the Scan Controls tile flips to Scan in Progress with a Cancel option, and a progress panel below shows live stages (Resource Graph Changes, Subscription Batches, Total Changes Collected) with a percentage complete. You can leave the page while it runs.

6. Post-scan backfill (first scan only)

When the first scan completes, a Background Data Collection Started modal appears. It explains that background backfills kick off within about 15 minutes for Activity Log (up to 80 days), Cost Data (up to 180 days), and Resource Graph history (up to 14 days). The modal is dismissible with Close or View Scan History. Backfills run asynchronously; you can continue using StratoLens while they complete.

7. (Optional) Review billing

With a scan under your belt, the Billing Configuration card on Settings → General will now show accurate plan details, including your price and next billing date. StratoLens is billed through your Azure subscription via the Azure Marketplace, and billing is enabled by default. Every StratoLens deployment includes a 28-day free trial; no charges are incurred during the trial regardless of this toggle.

To change billing:

1. Toggle Billing Enabled off if you want to pause billing, or leave it on to be billed automatically once the trial ends.
2. Set Billing Cycle to Monthly or Annual to match how you want to be invoiced.
3. Click Save Changes.

What Gets Deployed

The Marketplace offer provisions seven resources into your Managed Resource Group. The names shown below are the defaults derived from your Company Name. You can override any of them on the wizard's Resource Names tab.

Troubleshooting

Marketplace Deployment Fails

• Verify you have Owner permissions on the target subscription
• Check Azure quota limits for the selected region (Container Apps, Cosmos DB)
• Review the deployment's error details in the Azure Portal under Deployments for the target resource group

Placeholder Page Shows an Error or Doesn't Load

• The Container App may still be starting. Wait 2–3 minutes and refresh
• Confirm the Container App shows status Running in the Azure Portal
• Verify the Application Url on the Overview page matches the URL you're opening

Application Deploy Script Fails

• Ensure you're running Azure Cloud Shell in PowerShell mode (not Bash)
• Confirm you're signed in to the same tenant and subscription where the Marketplace deployment ran
• Check internet connectivity and that https://api.strato-lens.com is reachable

Invalid or Missing Deploy Command

• Copy the full command from the placeholder page. It's a single line and must be pasted in its entirety
• If the command is missing from the placeholder page, refresh after a few minutes; the Marketplace deployment may still be finalizing

Subscription Selection Issues

• Run az login to authenticate
• Verify you have access to the target subscription: az account list

Admin Consent Not Granted

• Confirm you're signing in to the Azure Portal with a user that has permission to grant admin consent (Global Administrator or Privileged Role Administrator)
• Navigate to the app registration created by the deployment, open API Permissions, and click Grant admin consent for [Your Organization]

Validation Errors

• Company Name: Must be 3–12 characters, lowercase alphanumeric only
• Region: Must be a valid Azure region (default: East US 2)