From 5d1ba48948a8db0a88caa54da8133a4a54c6c487 Mon Sep 17 00:00:00 2001 From: Shayne Boyer Date: Fri, 20 Feb 2026 22:39:32 -0500 Subject: [PATCH] Add RBAC and authorization error rules to error suggestions pipeline Add YAML rules for 7 authorization-related ARM deployment error codes: - AuthorizationFailed: enhanced with role assignment guidance - Unauthorized: re-authentication + RBAC check - Forbidden: RBAC + Azure Policy guidance - RequestDisallowedByPolicy: policy troubleshooting - RoleAssignmentExists: safe-to-ignore on re-deployment - PrincipalNotFound: stale principal detection - NoRegisteredProviderFound: provider registration command Authorization errors account for ~3,432 errors (2.68%) over 90 days. Each rule provides targeted suggestions and documentation links. Add table-driven test covering all 7 RBAC error codes. Fixes #6798 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- cli/azd/pkg/errorhandler/pipeline_test.go | 71 +++++++++++++++++++++++ cli/azd/resources/error_suggestions.yaml | 71 ++++++++++++++++++++++- 2 files changed, 141 insertions(+), 1 deletion(-) diff --git a/cli/azd/pkg/errorhandler/pipeline_test.go b/cli/azd/pkg/errorhandler/pipeline_test.go index 71ca95d0eb8..d8ee888d53f 100644 --- a/cli/azd/pkg/errorhandler/pipeline_test.go +++ b/cli/azd/pkg/errorhandler/pipeline_test.go @@ -364,3 +364,74 @@ func TestPipeline_ResponseError_MatchesByErrorCode(t *testing.T) { "Should match mockResponseError by ErrorCode property") assert.Equal(t, "Resource not available in region.", result.Message) } + +// --- RBAC and authorization error rule tests --- + +func TestPipeline_RBACErrors(t *testing.T) { + tests := []struct { + name string + code string + wantMessage string + }{ + { + name: "AuthorizationFailed", + code: "AuthorizationFailed", + wantMessage: "You do not have sufficient permissions for this deployment.", + }, + { + name: "Unauthorized", + code: "Unauthorized", + wantMessage: "The request was unauthorized.", + }, + { + name: "Forbidden", + code: "Forbidden", + wantMessage: "Access to this resource is forbidden.", + }, + { + name: "RequestDisallowedByPolicy", + code: "RequestDisallowedByPolicy", + wantMessage: "An Azure Policy is blocking this deployment.", + }, + { + name: "RoleAssignmentExists", + code: "RoleAssignmentExists", + wantMessage: "A role assignment with this configuration already exists.", + }, + { + name: "PrincipalNotFound", + code: "PrincipalNotFound", + wantMessage: "The security principal for a role assignment was not found.", + }, + { + name: "NoRegisteredProviderFound", + code: "NoRegisteredProviderFound", + wantMessage: "A required Azure resource provider is not registered.", + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + pipeline := NewErrorHandlerPipeline(nil) + err := &testDeploymentError{ + Details: &testErrorDetails{Code: tt.code}, + Title: "deployment error: " + tt.code, + } + + result := pipeline.ProcessWithRules( + context.Background(), + err, + []ErrorSuggestionRule{ + { + ErrorType: "testDeploymentError", + Properties: map[string]string{"Details.Code": tt.code}, + Message: tt.wantMessage, + Suggestion: "test suggestion", + }, + }, + ) + require.NotNil(t, result, "Should match %s", tt.code) + assert.Equal(t, tt.wantMessage, result.Message) + }) + } +} diff --git a/cli/azd/resources/error_suggestions.yaml b/cli/azd/resources/error_suggestions.yaml index f5411d1ab88..1e77627a268 100644 --- a/cli/azd/resources/error_suggestions.yaml +++ b/cli/azd/resources/error_suggestions.yaml @@ -157,11 +157,80 @@ rules: message: "You do not have sufficient permissions for this deployment." suggestion: > Ensure you have the required RBAC role (e.g., Owner or Contributor) - on the target subscription. + on the target subscription. If the template creates role assignments, + the Owner or User Access Administrator role is required. links: - url: "https://learn.microsoft.com/azure/role-based-access-control/role-assignments-portal" title: "Assign Azure roles" + - errorType: "DeploymentErrorLine" + properties: + Code: "Unauthorized" + message: "The request was unauthorized." + suggestion: > + Run 'azd auth login' to re-authenticate, then verify you have + the required RBAC role on the target subscription or resource group. + links: + - url: "https://learn.microsoft.com/azure/role-based-access-control/role-assignments-portal" + title: "Assign Azure roles" + + - errorType: "DeploymentErrorLine" + properties: + Code: "Forbidden" + message: "Access to this resource is forbidden." + suggestion: > + You may lack the required RBAC role, or an Azure Policy is + blocking the operation. Check your role assignments and any + deny assignments or policies on the target scope. + links: + - url: "https://learn.microsoft.com/azure/role-based-access-control/troubleshooting" + title: "Troubleshoot Azure RBAC" + + - errorType: "DeploymentErrorLine" + properties: + Code: "RequestDisallowedByPolicy" + message: "An Azure Policy is blocking this deployment." + suggestion: > + Check which policies are assigned to your subscription or + resource group with 'az policy assignment list'. Contact your + administrator to add an exemption or adjust the policy. + links: + - url: "https://learn.microsoft.com/azure/governance/policy/troubleshoot/general" + title: "Troubleshoot Azure Policy" + + - errorType: "DeploymentErrorLine" + properties: + Code: "RoleAssignmentExists" + message: "A role assignment with this configuration already exists." + suggestion: > + This is usually safe to ignore on re-deployment. The role + assignment was already created in a previous run. + + - errorType: "DeploymentErrorLine" + properties: + Code: "PrincipalNotFound" + message: "The security principal for a role assignment was not found." + suggestion: > + The user, group, or service principal may have been deleted. + Check that the principal ID in your template is valid, or + remove the stale role assignment. + links: + - url: "https://learn.microsoft.com/azure/role-based-access-control/troubleshooting" + title: "Troubleshoot Azure RBAC" + + - errorType: "DeploymentErrorLine" + properties: + Code: "NoRegisteredProviderFound" + message: "A required Azure resource provider is not registered." + suggestion: > + Register the missing provider with + 'az provider register --namespace '. + Common providers: Microsoft.CognitiveServices, + Microsoft.Search, Microsoft.App, Microsoft.ContainerRegistry. + links: + - url: "https://learn.microsoft.com/azure/azure-resource-manager/troubleshooting/error-register-resource-provider" + title: "Resolve resource provider registration errors" + - errorType: "DeploymentErrorLine" properties: Code: "InvalidTemplate"