From fdb34251333622adcc646ec6b70bd5aeaa2b598c Mon Sep 17 00:00:00 2001 From: Brian Rinaldi Date: Mon, 13 Jul 2026 16:33:51 -0400 Subject: [PATCH] Add RBAC enforcement documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - **role-assignment.mdx** — new "Enabling RBAC enforcement" section plus updated Limitations bullet - **role-definition.mdx**, **resource-manager.mdx** — Limitations bullets rewritten to reflect opt-in enforcement, linking back to role-assignment.mdx - **blob-storage.mdx**, **queue-storage.mdx**, **table-storage.mdx** — new Limitations bullet on opt-in data-plane enforcement with the relevant role name - **key-vault.mdx** — Limitations converted to a list, noting opt-in enforcement covers secrets/certs only, not keys - **managed-identity.mdx** — Features bullet noting IMDS/Workload Identity tokens now carry the principal ID RBAC evaluates against `cosmos-db.mdx` and the Event Grid stub pages were intentionally left untouched (still accurate / no existing prose to extend). Nothing else in the working tree changed — let me know if you'd like this committed. Fixes [DOC-300](https://linear.app/localstack/issue/DOC-300/doc-azure-rbac-opt-in-enforcement) --- .../docs/azure/services/blob-storage.mdx | 1 + src/content/docs/azure/services/key-vault.mdx | 3 ++- .../docs/azure/services/managed-identity.mdx | 1 + .../docs/azure/services/queue-storage.mdx | 1 + .../docs/azure/services/resource-manager.mdx | 2 +- .../docs/azure/services/role-assignment.mdx | 18 +++++++++++++++--- .../docs/azure/services/role-definition.mdx | 2 +- .../docs/azure/services/table-storage.mdx | 1 + 8 files changed, 23 insertions(+), 6 deletions(-) diff --git a/src/content/docs/azure/services/blob-storage.mdx b/src/content/docs/azure/services/blob-storage.mdx index c0d1ac523..08a2d8914 100644 --- a/src/content/docs/azure/services/blob-storage.mdx +++ b/src/content/docs/azure/services/blob-storage.mdx @@ -264,6 +264,7 @@ The Blob Storage emulator supports the following features: - **Storage account keys**: Keys are emulator-generated rather than managed by Azure. - **Header validation**: Unsupported request headers or parameters are silently accepted instead of being rejected. - **API version enforcement**: The emulator does not validate the `x-ms-version` header; all API versions are accepted. +- **RBAC enforcement is opt-in**: By default, data-plane operations succeed regardless of role assignments. Set `LS_AZURE_ENFORCE_RBAC` to require the caller to hold a role such as `Storage Blob Data Contributor`; see [Role Assignment: Enabling RBAC enforcement](/azure/services/role-assignment/#enabling-rbac-enforcement). ## Samples diff --git a/src/content/docs/azure/services/key-vault.mdx b/src/content/docs/azure/services/key-vault.mdx index baed48a22..6f728c367 100644 --- a/src/content/docs/azure/services/key-vault.mdx +++ b/src/content/docs/azure/services/key-vault.mdx @@ -141,7 +141,8 @@ az keyvault secret list \ ## Limitations -Key Vault keys, HSM-related operations, and getting a real certificate from an official CA are not supported. +- **Keys and HSM not supported:** Key Vault keys, HSM-related operations, and getting a real certificate from an official CA are not supported. +- **RBAC enforcement is opt-in and covers secrets/certificates only:** By default, data-plane operations succeed regardless of role assignments. Set `LS_AZURE_ENFORCE_RBAC` to enforce roles such as `Key Vault Secrets User` or `Key Vault Certificates Officer` on vaults created with `enableRbacAuthorization=true`; keys are not covered. See [Role Assignment: Enabling RBAC enforcement](/azure/services/role-assignment/#enabling-rbac-enforcement). ## Samples diff --git a/src/content/docs/azure/services/managed-identity.mdx b/src/content/docs/azure/services/managed-identity.mdx index 1aa10cfc9..74bd8c314 100644 --- a/src/content/docs/azure/services/managed-identity.mdx +++ b/src/content/docs/azure/services/managed-identity.mdx @@ -276,6 +276,7 @@ The Managed Identity emulator supports the following features: - **Management locks**: Create, delete, retrieve, and list management locks at the resource group level. Supported lock levels are `CanNotDelete` and `ReadOnly`. - **Microsoft Graph service principal queries**: List, create, and delete service principals through the Microsoft Graph `/v1.0/servicePrincipals` endpoint with OData query support including `$filter`, `$select`, `$top`, `$count`, and `$orderby`. - **Directory object lookups**: Resolve multiple directory objects by ID through the `/v1.0/directoryObjects/getByIds` endpoint. +- **Principal propagation**: Tokens minted for a managed identity via the Instance Metadata Service (IMDS) or AKS Workload Identity carry that identity's principal ID, which is what [RBAC enforcement](/azure/services/role-assignment/#enabling-rbac-enforcement) evaluates role assignments against when enabled. ## Limitations diff --git a/src/content/docs/azure/services/queue-storage.mdx b/src/content/docs/azure/services/queue-storage.mdx index 235f4623d..940df0977 100644 --- a/src/content/docs/azure/services/queue-storage.mdx +++ b/src/content/docs/azure/services/queue-storage.mdx @@ -253,6 +253,7 @@ The Queue Storage emulator supports the following features: - **Storage account keys**: Keys are emulator-generated rather than managed by Azure. - **Header validation**: Unsupported request headers or parameters are silently accepted instead of being rejected. - **API version enforcement**: The emulator does not validate the `x-ms-version` header; all API versions are accepted. +- **RBAC enforcement is opt-in**: By default, data-plane operations succeed regardless of role assignments. Set `LS_AZURE_ENFORCE_RBAC` to require the caller to hold a role such as `Storage Queue Data Contributor`; see [Role Assignment: Enabling RBAC enforcement](/azure/services/role-assignment/#enabling-rbac-enforcement). ## Samples diff --git a/src/content/docs/azure/services/resource-manager.mdx b/src/content/docs/azure/services/resource-manager.mdx index ace9b3c88..e3decd431 100644 --- a/src/content/docs/azure/services/resource-manager.mdx +++ b/src/content/docs/azure/services/resource-manager.mdx @@ -241,7 +241,7 @@ The Resource Manager emulator supports the following features: - **No what-if analysis**: The `az deployment group what-if` operation is not implemented. - **ARM template function coverage**: While over 60 functions are supported, some less common functions or advanced overloads may not be fully implemented. - **No resource tags on generic resource listings**: Tags and extended properties may not be fully populated when listing resources across a subscription. -- **No RBAC enforcement on resource operations**: All API calls succeed without role-based access control checks. +- **RBAC enforcement on resource operations is opt-in**: By default, all API calls succeed without role-based access control checks. Set `LS_AZURE_ENFORCE_RBAC` to enable control-plane checks across ARM resource types; see [Role Assignment: Enabling RBAC enforcement](/azure/services/role-assignment/#enabling-rbac-enforcement). - **Deployment concurrency**: Resources within a single deployment are created sequentially with dependency resolution, not in full parallel as in Azure. - **No deployment cancellation**: Running deployments cannot be cancelled. - **No deployment deletion**: Deployments are retained in memory and cannot be explicitly deleted via the API. diff --git a/src/content/docs/azure/services/role-assignment.mdx b/src/content/docs/azure/services/role-assignment.mdx index 434b5d871..f2f1dd872 100644 --- a/src/content/docs/azure/services/role-assignment.mdx +++ b/src/content/docs/azure/services/role-assignment.mdx @@ -1,10 +1,10 @@ --- -title: "Role Assignment" +title: 'Role Assignment' description: Get started with Azure Role Assignments on LocalStack template: doc --- -import AzureFeatureCoverage from "../../../../components/feature-coverage/AzureFeatureCoverage"; +import AzureFeatureCoverage from '../../../../components/feature-coverage/AzureFeatureCoverage'; ## Introduction @@ -316,6 +316,18 @@ az role assignment delete \ --scope "/subscriptions/$SUBSCRIPTION_ID/resourceGroups/rg-rbac-demo" ``` +## Enabling RBAC enforcement + +By default, Azure RBAC on LocalStack is **not enforced**: role assignments and role definitions are stored, but every operation succeeds regardless of the assigned roles. Set `LS_AZURE_ENFORCE_RBAC` to `true`, `yes`, or `1` when starting the emulator to turn on enforcement. + +With enforcement enabled: + +- **Control plane**: every ARM request, across all Azure services and resource types, is checked against the caller's role assignments at the target scope and denied with a `403` if unauthorized. +- **Data plane**: checked for [Blob](/azure/services/blob-storage/), [Queue](/azure/services/queue-storage/), and [Table](/azure/services/table-storage/) Storage, RBAC-mode [Key Vault](/azure/services/key-vault/) vaults (secrets and certificates only), and Event Grid publish/receive. Denials match the shape Azure returns for each service, for example a Storage `AuthorizationPermissionMismatch` XML error or a Key Vault `ForbiddenByRbac` error. +- **Not covered yet**, even with enforcement enabled: Storage File, the Service Bus data plane, Cosmos DB's data plane, and Microsoft Entra database authentication for Azure SQL, PostgreSQL, and MySQL flexible servers. Requests to these continue to succeed regardless of role assignments. + +The default SDK/Terraform service principal and the `az` CLI's `any-app` principal are always treated as a Global Administrator and subscription Owner, and bypass data-plane checks by default too. To observe a deny, use a managed identity or service principal that assumes neither role — for example, the identity created in [Create a user-assigned managed identity](#create-a-user-assigned-managed-identity) without a role assigned at the target scope. + ## Features - **Role assignment creation:** Create role assignments by specifying an assignee principal ID, role name or ID, and scope. @@ -327,7 +339,7 @@ az role assignment delete \ ## Limitations -- **RBAC not enforced:** Role assignments are stored but not evaluated. All operations on LocalStack succeed regardless of assigned roles. +- **RBAC enforcement is opt-in:** By default, role assignments are stored but not evaluated, and all operations succeed regardless of assigned roles. Set `LS_AZURE_ENFORCE_RBAC` to enable enforcement. - **Condition-based assignments:** Attribute-based access control (ABAC) conditions in assignments are accepted at the model level but are not evaluated. - **Deny assignments:** `Microsoft.Authorization/denyAssignments` are not supported. - **Management group scopes:** Assignments at management group scope are not supported. diff --git a/src/content/docs/azure/services/role-definition.mdx b/src/content/docs/azure/services/role-definition.mdx index 4a93fb012..9e3a7b187 100644 --- a/src/content/docs/azure/services/role-definition.mdx +++ b/src/content/docs/azure/services/role-definition.mdx @@ -166,7 +166,7 @@ az role definition list --name "Custom Storage Reader" ## Limitations -- **RBAC not enforced:** Role definitions and assignments are stored in the emulator but permissions are not enforced: API calls are not gated the way they are in Azure, and effective access for a principal at a scope is not evaluated from assignments and role definitions. +- **RBAC enforcement is opt-in:** By default, role definitions and assignments are stored but permissions are not enforced, so API calls are not gated the way they are in Azure. Set `LS_AZURE_ENFORCE_RBAC` to enable enforcement; see [Role Assignment: Enabling RBAC enforcement](/azure/services/role-assignment/#enabling-rbac-enforcement) for scope and coverage. - **Management group scopes:** Management group–level assignable scopes are not supported. ## Samples diff --git a/src/content/docs/azure/services/table-storage.mdx b/src/content/docs/azure/services/table-storage.mdx index d70d3211b..6553f5dfc 100644 --- a/src/content/docs/azure/services/table-storage.mdx +++ b/src/content/docs/azure/services/table-storage.mdx @@ -308,6 +308,7 @@ The Table Storage emulator supports the following features: - **Storage account keys**: Keys are emulator-generated rather than managed by Azure. - **Header validation**: Unsupported request headers or parameters are silently accepted (Azurite runs in loose mode) instead of being rejected. - **API version enforcement**: The emulator does not validate the `x-ms-version` header; all API versions are accepted. +- **RBAC enforcement is opt-in**: By default, data-plane operations succeed regardless of role assignments. Set `LS_AZURE_ENFORCE_RBAC` to require the caller to hold a role such as `Storage Table Data Contributor`; see [Role Assignment: Enabling RBAC enforcement](/azure/services/role-assignment/#enabling-rbac-enforcement). ## Samples