Azure Setup

Azure Service Principal Setup Guide for Cloud Sweeper

Follow these steps to securely connect your Azure subscription to Cloud Sweeper. This guide covers app registration, custom role creation, and role assignment.

1. Register an Application in Entra ID

  1. Go to the Azure Portal.
  2. Navigate to Entra ID > App registrations > New registration.
  3. Enter a Name (e.g., CloudSweeper).
  4. Leave Redirect URI blank.
  5. Click Register.

2. Collect Application Details

  • After registration, copy:
    • Application (client) ID (ClientId)
    • Directory (tenant) ID (TenantId)

3. Create a Client Secret

  1. In your app registration, go to Certificates & secrets.
  2. Click New client secret.
  3. Add a description and select an expiration.
  4. Click Add.
  5. Copy the secret value immediately—it will not be shown again.

4. Create a Custom Role

  • In the Azure Portal, go to Subscriptions and select your subscription.
  • In the left menu, click Access control (IAM).
  • Click the Roles tab, then click + Add > Add custom role.
  • On the Basics tab, enter a Name (e.g., CloudSweeper-Role) and an optional description.
  • On the Permissions tab, click JSON mode.
  • Click Upload and select the az-role-portal.json file provided by Cloud Sweeper.
  • Review the permissions and click Next.
  • On the Assignable scopes tab, ensure your subscription is selected (the portal will auto-select your current subscription).
  • Click Review + create, then Create to finish.
  • Note: Cloud Sweeper does not require delete permissions. The role is designed to allow reading, tagging, and updating resources only.

5. Assign the Custom Role to the Service Principal

Using Azure Portal

  1. Go to Subscriptions in the Azure Portal.
  2. Select your subscription.
  3. Go to Access control (IAM) > Add > Add role assignment.
  4. Role: Select your custom role (e.g., CloudSweeper-Role).
  5. Assign access to: User, group, or service principal.
  6. Select: Search for your CloudSweeper app and select it.
  7. Click Review + assign.

6. Gather Required Information

  • TenantId: Directory (tenant) ID
  • ClientId: Application (client) ID
  • ClientSecret: The secret you created
  • SubscriptionId: Your Azure subscription ID
Need help? Contact Support
How to Update Existing Custom Role

When to Update: If Cloud Sweeper adds new permissions or features, you may need to update your custom role to grant additional access. This process is straightforward and your service principal will automatically get the new permissions without requiring reassignment.

Important: Role Updates Are Automatic

Once you update the custom role definition, all service principals and app registrations that have this role assigned will automatically get the new permissions. You don't need to reassign the role or reconfigure Cloud Sweeper.

Before You Begin

Download the updated az-role-portal.json file. This file contains the complete role definition with all existing permissions plus any new ones.

Steps to Update Custom Role via JSON:

  1. Navigate to Subscriptions:
    • Go to Azure Portal
    • Search for and select Subscriptions from the top search bar
    • Select any of your subscriptions from the list
  2. Access Access Control (IAM):
    • In the left navigation menu, click Access control (IAM)
    • Click the Roles tab at the top of the page
  3. Find and Open Your Custom Role:
    • In the search box, type your custom role name (e.g., CloudSweeper-Role)
    • Click on the role name to open its details page
  4. Start Editing the Role:
    • Click the Edit button at the top of the role details page
    • You will see tabs for Basics, Permissions, and Assignable scopes
  5. Switch to JSON Mode:
    • Click on the Permissions tab
    • Click the JSON button to switch to JSON edit mode
    • You will see the current role definition in JSON format
  6. Upload the Updated JSON File:
    • Click the Upload button in the JSON editor
    • Browse and select the az-role-portal.json file you downloaded earlier
    • The JSON editor will be populated with the new role definition
    • Important: This replaces the entire role definition with the updated one containing all permissions
  7. Review the Changes:
    • Scroll through the JSON to verify the permissions are correct
    • Look for the new permissions like Microsoft.Web/serverfarms/* and Microsoft.App/containerApps/*
    • Click Save or click Next to proceed
  8. Review and Update:
    • Review the Assignable scopes tab (no changes needed here)
    • Click Review + update button
    • Review the summary of changes
    • Click Update to apply the changes
  9. Wait for Completion:
    • Azure will process the role update (usually takes 10-30 seconds)
    • You will see a success notification when complete
    • The updated permissions are now active across all subscriptions where the role is assigned

What Happens After Update:

  • The custom role definition is updated with new permissions
  • All service principals with this role automatically receive the new permissions
  • No need to reassign the role or update credentials in Cloud Sweeper
  • Changes take effect immediately (may take a few minutes to propagate)

Troubleshooting Updates:

  • Can't Find Custom Role? Make sure you're looking at the correct subscription. Custom roles are scoped to specific subscriptions.
  • Permission Not Available? Some permissions may require specific Azure resource providers to be registered. Check the Activity Log for details.
  • Update Failed? Ensure you have Owner or User Access Administrator role on the subscription to modify custom roles.
  • Changes Not Taking Effect? Wait a few minutes for changes to propagate across Azure services. You can also try signing out and back into Cloud Sweeper.