Azure service principal integration setup

Azure service principal integration setup

1. Sign in:

   az login
   

2. Choose a scope.

   Per subscription - list your subscriptions and note the IDs you want monitored:

   az account list --output table
   

   Per management group - one assignment covers every
   subscription beneath it, including subscriptions moved in later. List
   your management groups and take the ID from the Name column:

   az account management-group list --output table
   

   To see which subscriptions a management group currently covers:

   az account management-group show \
     --name <management-group-id> \
     --expand --recurse --output table
   

3. Choose a role. Reader is a built-in role and needs no setup. To grant less than Reader, follow using custom role details(below) first, then substitute your role name below.

4. Create the service principal with the role at that scope.

   Subscriptions - pass as many as you want monitored:

   az ad sp create-for-rbac \
     --name "StatusGator" \
     --role Reader \
     --scopes /subscriptions/<subscription-id> /subscriptions/<another-subscription-id>
   

   Management group:

   az ad sp create-for-rbac \
     --name "StatusGator" \
     --role Reader \
     --scopes /providers/Microsoft.Management/managementGroups/<management-group-id>
   

5. Copy the output - the password is shown once and cannot be retrieved later:

   {
     "appId": "87654321-4321-4321-4321-210987654321",
     "displayName": "StatusGator",
     "password": "abc~1DEfgh2IJklmn3OPqrst4UVwxyz5AB6c",
     "tenant": "12345678-1234-1234-1234-123456789012"
   }
   

6. To widen the scope later, assign the role to the same app:

   az role assignment create \
     --assignee <appId> \
     --role Reader \
     --scope /subscriptions/<subscription-id>
   
   az role assignment create \
     --assignee <appId> \
     --role Reader \
     --scope /providers/Microsoft.Management/managementGroups/<management-group-id>
   

7. Confirm the credentials work and see every subscription they reach:

   az login --service-principal --username <appId> --password <password> --tenant <tenant>
   az account list --output table
   az rest --method get --url "<https://management.azure.com/subscriptions/><subscription-id>/providers/Microsoft.ResourceHealth/events?api-version=2025-05-01"
   

Using a custom role instead of Reader

Reader grants read access to every resource under the scope.
StatusGator needs only to list Resource Health events and enumerate the
subscriptions it can see. A custom role narrows the grant to those two
operations.

Do this before step 4 above.

1. Confirm the operation names available in your tenant:

   az provider operation show \
     --namespace Microsoft.ResourceHealth \
     --query "resourceTypes[?name=='events'].operations[].{name:name, display:displayName}" \
     --output table
   

2. Save the role definition, setting AssignableScopes to every scope you intend to assign it at:

   cat > statusgator-health-reader.json <<'EOF'
   {
     "Name": "StatusGator Health Reader",
     "Description": "Read Azure Resource Health events for StatusGator monitoring.",
     "IsCustom": true,
     "Actions": [
       "Microsoft.ResourceHealth/events/read",
       "Microsoft.Resources/subscriptions/read"
     ],
     "NotActions": [],
     "DataActions": [],
     "NotDataActions": [],
     "AssignableScopes": [
       "/providers/Microsoft.Management/managementGroups/<management-group-id>"
     ]
   }
   EOF
   

   For a per-subscription setup, use "/subscriptions/<subscription-id>" entries instead.

3. Create the role:

   az role definition create --role-definition @statusgator-health-reader.json
   

4. Confirm it exists - allow a few minutes for it to propagate:

   az role definition list --name "StatusGator Health Reader" --output table
   

5. Use it in place of Reader in step 4:

   az ad sp create-for-rbac \
     --name "StatusGator" \
     --role "StatusGator Health Reader" \
     --scopes /providers/Microsoft.Management/managementGroups/<management-group-id>
   

6. Verify the service principal can read events before configuring StatusGator:

   az login --service-principal --username <appId> --password <password> --tenant <tenant>
   az account list --output table
   az rest --method get --url "<https://management.azure.com/subscriptions/><subscription-id>/providers/Microsoft.ResourceHealth/events?api-version=2025-05-01"
   

   az account list must return the subscriptions you expect and the az rest call must return JSON rather than an authorization error. If either fails, assign Reader instead and open a support ticket with us.

To add a scope to an existing custom role, edit AssignableScopes in the JSON and run:

az role definition update --role-definition @statusgator-health-reader.json

In StatusGator

1. Go to Integrations and add or open your Azure integration.
2. Enter a Display name.
3. Under Authentication, choose Service principal.
4. Tenant ID - tenant from the output.
5. Application ID - appId from the output.
6. Client Secret - password from the output.
7. Subscription ID - leave blank to monitor every
   subscription the app can read. Leave it blank if you scoped to a
   management group, otherwise only the one subscription you name is
   monitored.
8. Select Save.