Azure Managed Applications: Fix Setup & Config Errors
Why Azure Managed Applications Keep Breaking , And What Microsoft Doesn't Tell You
You've been tasked with deploying or publishing an Azure Managed Application, and somewhere between the definition artifact, the managed resource group, and the permission model, something has gone sideways. Maybe you're getting an access denied error when trying to update resources. Maybe the application deployed fine but your publisher identity can't touch anything in the customer's subscription. Or maybe you're trying to publish to the service catalog and the portal just stares back at you with a vague failure message that helps no one.
I've seen this exact situation on dozens of enterprise engagements. The frustrating part isn't that Azure Managed Applications are broken , they aren't. The frustrating part is that Microsoft's error messages give you almost zero signal about which layer of the system has the problem. Is it the permission scenario you chose? The managed identity configuration? A deny assignment blocking you from an unexpected direction? The portal tells you almost nothing useful.
Here's the core thing to understand before we fix anything: Azure Managed Applications are fundamentally a two-subscription, two-resource-group system. When a customer deploys your managed application, Azure creates two resource groups. One sits in the customer's subscription and the customer interacts with it directly. The other, the managed resource group, also lives in the customer's subscription, but the publisher can be granted management access to it from their own tenant. That cross-tenant access model is elegant when it works and deeply confusing when it doesn't.
The four permission scenarios Microsoft gives you, publisher managed, publisher and customer access, locked mode, and customer managed, each create a completely different access topology. If you're in the wrong scenario for your use case, you'll hit walls at every turn. Publishers who expect to manage resources but accidentally deployed in locked mode? Classic. Customers who can't reboot a VM because the deny assignment is blocking them even though the publisher set things up in good faith? Happens all the time.
Azure Managed Applications setup problems also spike whenever organizations try to move from a service catalog deployment to an Azure Marketplace offer without understanding that the publication pipeline is completely different. Service catalog is internal and relatively forgiving. The Marketplace offer goes through Microsoft's validation and has strict artifact requirements.
So: wrong permission scenario, misconfigured managed identities, deny assignment conflicts, and broken definition artifacts account for roughly 80% of the issues I see. Let's fix them. Browse all Microsoft fix guides →
The Quick Fix, Try This First
Before you go deep into ARM templates and role assignment audits, do this one check. It resolves more Azure Managed Applications configuration issues than anything else I've seen.
Open the Azure portal, navigate to your managed application instance, and look at the Overview blade. Find the "Managed resource group" link, it's usually listed as a direct property of the application. Click through to that resource group. Now go to Access control (IAM) and check the "Deny assignments" tab.
If you see an active deny assignment scoped to the managed resource group, that's your culprit for a large class of "why can't I do anything here" problems. Microsoft places a deny assignment on the managed resource group by default in the publisher managed scenario, this is intentional, it restricts the customer from modifying the managed infrastructure. But here's what trips people up: the publisher's identities are supposed to be exempt from that deny assignment. If your publisher service principal or managed identity isn't listed as excluded, it will be blocked too. That's the bug.
To verify your publisher identity is properly exempt, check the deny assignment details. You'll see a "Does not apply to" section. Your publisher's identity, whether that's a service principal, a user, or a managed identity, needs to appear here. If it doesn't, that means either the application definition was published with the wrong authorization block, or the identity changed after the fact (common after service principal rotation).
The remediation: update your managed application definition with the correct authorizations array, making sure the principalId values match your current publisher identities, then redeploy. You cannot edit a deployed managed application's permission scenario in place, you need to update the definition and either redeploy or create a new instance.
Every Azure Managed Applications deployment problem starts with the definition. The definition package is a ZIP file containing at minimum two files: mainTemplate.json (your ARM or Bicep template) and createUiDefinition.json (the portal UI). If either file is malformed or referencing resources incorrectly, you'll see cryptic deployment failures that have nothing to do with runtime permissions.
Start by validating your mainTemplate.json independently. Deploy it to a test resource group directly before you ever wrap it in a managed application package. Use the Azure CLI:
az deployment group validate \
--resource-group myTestRG \
--template-file mainTemplate.json \
--parameters @parameters.jsonIf that validates cleanly, move to your createUiDefinition.json. The fastest way to test the UI definition without a full deployment cycle is to use the Create UI Definition Sandbox. In the Azure portal, navigate to the URL https://portal.azure.com/?feature.customPortal=false#blade/Microsoft_Azure_CreateUIDef/SandboxBlade and paste your JSON directly. The sandbox shows you exactly how the portal UI will render and flags any output reference errors before you burn 20 minutes on a failed publish.
One thing that catches teams constantly: the outputs of createUiDefinition.json must map exactly to parameters expected by mainTemplate.json. A mismatch here, a typo in a parameter name, a case sensitivity difference, produces a "deployment validation failed" error that gives you no indication that it's actually a parameter mapping problem.
When everything validates, package your files: both JSON files must be at the root of the ZIP, not inside a subfolder. I've seen this specific mistake cause silent failures where the managed application definition publishes but every subsequent deployment from it fails.
If it worked, the portal sandbox renders your UI without errors and the CLI validate command returns "provisioningState": "Succeeded".
This is the step where most Azure Managed Applications configuration errors originate. Microsoft gives you four permission scenarios and the wrong one will make your setup feel broken even when technically everything deployed correctly. Let me explain each one in plain terms.
Publisher managed is the default. The publisher gets management access to the managed resource group, and a deny assignment blocks the customer from changing resources there. Use this when you, the publisher, are responsible for keeping the application healthy and you don't want customers accidentally reconfiguring things you're actively managing.
Publisher and customer access removes the deny assignment entirely. Both you and the customer have full access to the managed resource group. Use this for collaborative scenarios where customers legitimately need to configure resources themselves, like adjusting network security group rules for their own environment.
Locked mode is the most restrictive: the publisher has no access at all, and the customer is also locked out by a deny assignment. This is for scenarios where neither party should be touching the deployed infrastructure, fully automated lifecycle management only.
Customer managed gives the customer full control. No deny assignment, no publisher access. Use this when you're licensing an application but not providing ongoing management, you're essentially shipping software, not a managed service.
To set the permission scenario in your managed application definition, the key field is in the ARM template for the definition itself. In the Microsoft.Solutions/applicationDefinitions resource, the lockLevel property controls this. Valid values are ReadOnly (publisher managed, default), None (publisher and customer), and CanNotDelete. For the customer managed scenario where you want no publisher involvement, set your authorizations array to empty.
{
"lockLevel": "ReadOnly",
"authorizations": [
{
"principalId": "<publisher-object-id>",
"roleDefinitionId": "<contributor-role-id>"
}
]
}If this deployed correctly, your publisher identity appears in the "Access control (IAM)" section of the managed resource group with the role you specified.
Azure Managed Applications support managed identities for Azure resources, and when managed identity is part of your setup, either for the application itself to authenticate to other Azure services, or as the publisher identity in the authorization block, misconfiguration here causes some of the hardest-to-diagnose Azure Managed Applications deployment errors you'll encounter.
First, understand the distinction. A system-assigned managed identity on the managed application is tied to the lifecycle of that specific application instance. Delete the instance, the identity is gone. A user-assigned managed identity exists independently and can be associated with multiple managed application instances, much more practical for publisher scenarios where you want consistent authorization across deployments.
If your managed application needs to call other Azure services (Key Vault, Storage, etc.) using a managed identity, you need to grant that identity access to those resources before the deployment happens, or handle it in the deployment template itself. A common pattern is to use the user-assigned managed identity in the authorizations block of the managed application definition so the publisher can manage the app, and then separately assign roles to that same identity for downstream resource access.
To diagnose identity errors, go to your managed application instance in the portal, click Identity in the left menu. Confirm the managed identity is enabled and note the Object ID. Now navigate to any resource the application should be accessing and check its IAM role assignments for that Object ID. If the Object ID isn't there, that's your missing assignment.
Use this PowerShell to quickly audit role assignments for a managed identity across a resource group:
$principalId = "<your-managed-identity-object-id>"
Get-AzRoleAssignment -ObjectId $principalId | `
Select-Object RoleDefinitionName, Scope, DisplayNameA clean result here shows every resource the identity can touch. If the scope you expected is missing, add it with New-AzRoleAssignment.
Publishing an Azure Managed Applications definition to the service catalog sounds straightforward. It mostly is, until it isn't. Here are the failure modes I see most often when organizations try to get this working for internal users.
Navigate to the Azure portal and search for Service Catalog Managed Application Definitions. Click + Add. The wizard asks for your definition package (the ZIP you validated in step 1), the storage account to host it, and the authorization block (who from the publisher side gets what role).
The storage account is where people trip up. The package ZIP has to be uploaded to an Azure Storage account and the definition needs to reference the URI of that blob. If the storage account has network restrictions, say a firewall that blocks access from Azure services, the definition upload will succeed but any attempt to deploy from that definition will fail with a misleading "package could not be accessed" error. Make sure the storage account allows access from Azure services, or use the bring-your-own-storage option which gives you explicit control over access.
For organizations that want to deploy programmatically, the Azure CLI command is:
az managedapp definition create \
--name "MyManagedApp" \
--location "eastus" \
--resource-group "AppDefinitionRG" \
--lock-level ReadOnly \
--display-name "My Managed Application" \
--description "Application for internal teams" \
--authorizations "<principal-id>:<role-definition-id>" \
--package-file-uri "https://<storageaccount>.blob.core.windows.net/<container>/app.zip"After publishing, have a test user from your organization navigate to Marketplace in the portal, click Service Catalog, and verify your definition appears. If it doesn't, check that you published to the correct subscription and resource group that the user has read access to. Internal service catalog visibility is scope-dependent, users need at least Reader on the resource group containing the definition to see it.
Once your definition is published (whether to the service catalog or Azure Marketplace), you need to verify that deployed instances land in the correct resource group configuration. This step is about confirming the deployment worked as intended, not just that it succeeded.
After deploying, you should see two resource groups in the customer's subscription. One is the application resource group, the one the customer specified during deployment, which contains the managed application resource itself. The other is the managed resource group, which Azure creates automatically with a name in the format mrg-<appname>-<timestamp> unless you specified a custom name.
To confirm both exist and are correctly linked, use the Azure CLI:
az managedapp list \
--resource-group "<customer-resource-group>" \
--query "[].{Name:name, ManagedRG:managedResourceGroupId, State:provisioningState}" \
--output tableThe managedResourceGroupId field in the output tells you the exact path of the managed resource group. If this is null or missing, the deployment failed partway through and you need to look at the deployment activity log for the root cause.
Now validate access from the publisher side. Using the publisher identity (service principal or managed identity you configured in the authorizations block), try a simple read operation against a resource in the managed resource group:
az resource list \
--resource-group "<managed-resource-group-name>" \
--output tableIf you get an authorization error here as the publisher, go back to step 2 and re-examine your permission scenario. If you get a list of resources, your deployment is healthy. From the customer side, verify they can see the application in their portal and access whatever level of management was intended by the permission scenario you selected. A customer in a publisher-managed scenario should see the managed resource group but be restricted from modifying resources there.
Advanced Troubleshooting for Azure Managed Applications
When the standard steps don't resolve things, you're usually dealing with one of three more complex scenarios: enterprise policy enforcement blocking deployments, just-in-time access configuration problems, or cross-tenant identity resolution failures.
Azure Policy Blocking Managed Application Deployments
Azure Policy can absolutely block managed application deployments, and the error messages from Policy are notoriously vague. The most common policy conflict I see is a "deny" policy effect on resource types that your managed application template tries to create. For example, if your organization has a policy that requires all storage accounts to have HTTPS-only access and your mainTemplate.json creates a storage account without setting supportsHttpsTrafficOnly: true, the deployment will fail at the policy enforcement layer.
To audit this, check your organization's policy assignments in the Azure portal under Policy > Compliance. Filter by the subscription where you're deploying. Look for any "deny" effect policies scoped to your target subscription or resource groups. Cross-reference those with the resource types in your mainTemplate.json.
Azure Managed Applications also has a specific Policy feature for associations, this allows policies to target resources within managed applications specifically, which means a policy could be written to only apply to managed resources, or to exempt them. If you're seeing unexpected Policy behavior around managed application resources, check if there are policy definitions using the Microsoft.Solutions/associations resource type targeting your application.
Just-in-Time Access Problems
Just-in-time (JIT) access for Azure Managed Applications gives publishers time-constrained access to the managed resource group instead of permanent access. This is the right model for security-conscious enterprises, but it introduces a workflow that breaks if any step goes wrong.
The publisher requests JIT access from the portal (navigate to the managed application instance > JIT Access > Request access). The customer then approves it under the same blade on their side. If approval isn't happening, check whether the customer's subscription has the JIT feature enabled at the managed application definition level. JIT must be explicitly configured when the definition is created, it can't be added to an existing deployed instance.
If JIT approval is stuck in "Pending" for more than 24 hours with no customer action, the request automatically expires. The publisher must submit a new request. I'd recommend coordinating directly with the customer admin and having them check their Azure portal notification center, since JIT approval requests don't always generate email notifications by default.
Event Log and Activity Log Analysis
For any managed application deployment failure, the Activity Log is your best friend. Navigate to the managed resource group and open Activity Log. Filter by "Failed" operations. Each failed entry has a "JSON" tab in the detail panel that contains the full ARM error response, this is where the actual error code lives, not the vague portal message you see in the UI.
Common error codes you'll see: AuthorizationFailed (identity doesn't have the right role), RequestDisallowedByPolicy (Azure Policy blocking the resource), InvalidTemplate (ARM template syntax issue that slipped through validation), and LinkedInvalidPropertyId (a resource reference in your template is pointing to something that doesn't exist or uses the wrong resource ID format).
If you're seeing cross-tenant identity resolution failures, where your publisher identity exists and has the right roles, but Azure consistently treats it as unauthorized when accessing the managed resource group, that's a platform-layer issue that goes beyond what you can fix yourself. Similarly, if you're publishing to Azure Marketplace and your offer is failing Microsoft's automated validation with error codes you can't find in the documentation, escalate. These problems have specific engineering team owners at Microsoft. Open a support case through Microsoft Support, categorize it under Azure > Azure Managed Applications, and attach your definition package ZIP and the full Activity Log JSON from the failed deployment. Do this before you spend another day guessing.
Prevention & Best Practices for Azure Managed Applications
Once you've fixed the immediate Azure Managed Applications deployment problem, here's how you keep it from coming back. Most of these I learned the hard way from watching organizations deploy managed applications at scale and then scramble when something breaks months later.
Version your definition packages. Every time you update your mainTemplate.json or createUiDefinition.json, publish it as a new version in your service catalog. Don't overwrite the existing definition package in storage without updating the definition resource, deployed instances don't automatically update, but you want a clear audit trail of what definition each instance was deployed from. Use semantic versioning in your definition display names: MyApp v1.2.0.
Use user-assigned managed identities over service principals for your publisher authorization. Service principal credentials expire. Managed identity credentials don't. I've seen managed application publisher access break silently because a service principal's client secret rotated on a schedule and no one updated the authorization block. A user-assigned managed identity tied to an Azure AD group eliminates that entire failure mode for Azure Managed Applications access control.
Test your createUiDefinition.json in the sandbox after every change, not just the first time. The portal UI rendering engine has quirks with certain output types and conditional visibility rules. Ten minutes in the sandbox saves two hours of "why won't this deploy" debugging later.
Document your chosen permission scenario and why you chose it in your application's README. When someone joins your team six months from now and the customer reports they can't access something, knowing immediately whether you're in publisher managed or customer managed mode saves a lot of confusion about what "correct behavior" even looks like.
- Validate your definition package in the Azure CLI and UI sandbox before every publish, catch errors before customers see them
- Use user-assigned managed identities in your authorization block to prevent access breaks from service principal rotation
- Set a storage account lifecycle policy to archive old definition packages, but never delete them, you'll want them for rollback investigation
- Enable Azure Monitor alerts on the managed resource group for any "AuthorizationFailed" activity log events, so you know immediately when the permission model breaks
Frequently Asked Questions
What exactly is the difference between a managed resource group and a regular resource group in Azure?
A managed resource group is a standard Azure resource group that Azure creates automatically when a customer deploys a managed application, it lives in the customer's subscription just like any other resource group. The key difference is access control: depending on the permission scenario the publisher configured, there may be a deny assignment on the managed resource group that restricts what the customer can do with the resources inside it. The publisher's identity, granted access through the managed application's authorization configuration, can be given management rights to that resource group even though it's in the customer's tenant. Regular resource groups have no such cross-tenant publisher relationship.
Why can't the customer modify resources in the managed resource group even though they own the subscription?
This is the "publisher managed" permission scenario working exactly as designed. When the managed application definition is configured with publisher management access, Azure places a deny assignment on the managed resource group. This deny assignment blocks the customer from modifying resources there, even though they technically own the subscription. The deny assignment has explicit exclusions for the publisher's identities so the publisher can still manage the resources. If you want the customer to have full access, the application needs to be redeployed using the "publisher and customer access" scenario, which removes the deny assignment entirely.
How do I publish an Azure Managed Application to the service catalog vs. Azure Marketplace, what's the difference?
The service catalog is for internal distribution within your own organization. You publish the definition to a resource group in your Azure subscription, and employees in your organization can find and deploy it from the portal's Service Catalog section. Azure Marketplace is for distributing to customers outside your organization, it goes through Microsoft's offer publication process and is visible to all Azure customers. The underlying managed application technology is the same; what changes is the publication target, the validation process (Marketplace has automated and manual review), and the billing model (Marketplace supports transactable offers through Azure billing).
My managed application deployed but the publisher identity can't access the managed resource group, how do I fix this?
First, check the deny assignment on the managed resource group under Access Control (IAM) > Deny assignments. The "Does not apply to" section should list your publisher identity's Object ID. If it's missing, your authorization block in the managed application definition has a wrong or outdated principalId. You'll need to update the definition with the correct Object ID and redeploy a new instance, you cannot patch an existing deployed instance's permission configuration in place. Before redeploying, verify your publisher identity's current Object ID using az ad sp show --id <your-app-id> --query objectId.
Can I update an already-deployed Azure Managed Application without the customer having to redeploy from scratch?
You can update the resources within the managed resource group using the publisher's management access, for example, deploying new code to a VM or updating a configuration, without requiring the customer to do anything. What you can't change after the fact is the fundamental permission scenario (e.g., switching from publisher managed to customer managed), the managed resource group itself, or the core application structure. For those kinds of changes, the customer needs to deploy a new instance from an updated definition. Microsoft does support update flows for managed application definitions, where you publish a new version and the customer can choose to update to it, but this depends on how your application definition and template are structured to handle in-place updates.
What is just-in-time access for Azure Managed Applications and when should I use it?
Just-in-time (JIT) access is an alternative to permanent publisher access to the managed resource group. Instead of the publisher having always-on management rights, the publisher requests access for a specific time window, and the customer approves or denies that request. This is the right choice when your customers have strict security requirements, particularly regulated industries like finance or healthcare, where persistent third-party access to infrastructure is a compliance concern. JIT must be enabled at the definition level when you publish the managed application; you can't add it to an already-deployed instance. The publisher requests access through the managed application's JIT Access blade in the portal, and the customer approves it through the same blade in their own portal view.