Azure Setup Guide - Cloud Sweeper

Update Existing Custom Role

When CloudSweeper adds support for new Azure resources, you may need to update your custom role to grant the required permissions. This is a simple process that won't require any reconfiguration.

Automatic Permission Updates

✓ Service Principal credentials stay the same
✓ No need to reassign the role
✓ All subscriptions get new permissions automatically
✓ No reconfiguration needed in CloudSweeper

Fastest Option 1: Azure CLI (One Command)

Run this command in Azure Cloud Shell:

# Get existing role scope, download new permissions, and update
SCOPE=$(az role definition list --name "CloudSweeper-Reader-Tagger" \
  --query "[0].assignableScopes[0]" -o tsv) && \
curl -sL https://cloudsweeper.io/static/cloudsweeper-azure-role.json | \
  sed "s|/subscriptions/SUBSCRIPTION_ID|$SCOPE|" > /tmp/cs-role.json && \
az role definition update --role-definition /tmp/cs-role.json

Option 2: Azure Portal

Download the updated cloudsweeper-azure-role.json file
Go to Azure Portal - Subscriptions
Select any subscription
Click Access control (IAM) in the left menu
Click the Roles tab
Search for CloudSweeper and click on the role
Click Edit
Go to Permissions tab → Click JSON
Click Upload and select the downloaded JSON file
Click Review + update → Update

What Actually Changes:

Only the role permissions are updated. The Service Principal, credentials, and role assignments remain unchanged. New permissions are added to support additional Azure resource types.

Troubleshooting

Role not found?

Custom roles are scoped to specific subscriptions. Make sure you're looking at a subscription where the CloudSweeper role was originally created. Try the Roles tab in different subscriptions.

AuthorizationFailed error?

You need Owner or User Access Administrator role on the subscription to modify custom roles. Contact your Azure administrator for elevated access.

RoleDefinitionDoesNotExist or "SCOPE is empty"?

The CloudSweeper custom role doesn't exist yet. Use the one-click setup in CloudSweeper Settings to create it first, then come back here to update permissions when needed.

Changes not taking effect?

Azure role updates can take a few minutes to propagate. Wait 5-10 minutes and try again. You can also sign out and back into CloudSweeper to refresh the connection.

CLI command fails with "not valid JSON"?

The download may have failed. Try opening the JSON file in your browser first to verify it's accessible, then try the CLI command again.

Security Notes

CloudSweeper uses read and write permissions only - never delete
The custom role includes NotActions: ["*/delete"] to prevent accidental deletion
Service Principal credentials should never be shared publicly
The role uses tenant-level scope for simplified multi-subscription access
You can review all permissions in the role definition JSON

Advanced: Manual Setup (if not using one-click)

Note: Most users should use the one-click setup in the Settings page. This manual guide is for advanced users who prefer full control over the deployment process.

1. Register an Application in Entra ID

Go to Azure Portal
Navigate to Entra ID → App registrations → New registration
Enter name: CloudSweeper
Leave Redirect URI blank
Click Register

2. Create a Client Secret

In the app registration, go to Certificates & secrets
Click New client secret
Add description and select expiration
Click Add and copy the secret value immediately

3. Create and Assign Custom Role

Go to Subscriptions → Select your subscription
Click Access control (IAM) → Roles → Add custom role
Name: CloudSweeper
On Permissions tab, click JSON → Upload
Upload cloudsweeper-azure-role.json
Click Review + create
Then assign the role to your Service Principal

4. Gather Required Information

Tenant ID: Entra ID → Overview → Directory (tenant) ID
Client ID: App registration → Overview → Application (client) ID
Client Secret: The secret value you copied
Subscription ID: Subscriptions → Your subscription ID

Azure Custom Role Guide