Azure

Covers only the subscriptions you list.

1. Open Azure Cloud Shell (Bash) in the Azure portal, or sign in with az login.

2. Set up your terminal

3. List the subscriptions OpsLyft should read. Find the IDs with List your subscriptions and replace the bracketed IDs by hand:

   Copy Text

   SUBSCRIPTIONS=(<SUBSCRIPTION_ID_1> <SUBSCRIPTION_ID_2>)

4. Run Check your directory rights and Check your subscription rights.

5. Check that nothing exists yet: run Check that OpsLyft's application is registered, Check that the role name is free and Check the role assignments on the subscriptions.

   Result: the app is reported as not found, the role check prints nothing and no subscription lists an assignment. If one prints a value, follow Existing integration with OpsLyft.

6. Register OpsLyft's application in your tenant:

   Copy Text

   az ad sp create --id "$OPSLYFT_APP_ID"

   Result: run Check that OpsLyft's application is registered; it prints a row with the application ID. If not, see Troubleshooting.

7. Create the custom role on every subscription in $SUBSCRIPTIONS:

   Copy Text

   SCOPES=$(for sub in "${SUBSCRIPTIONS[@]}"; do printf '"/subscriptions/%s",' "$sub"; done); SCOPES="[${SCOPES%,}]"
   az role definition create --role-definition "$(cat <<EOF
   {
     "properties": {
       "roleName": "$ROLE_NAME",
       "description": "OpsLyft optimization read-only role",
       "assignableScopes": $SCOPES,
       "permissions": [{
         "actions": ["*/read"], "notActions": [], "dataActions": [],
         "notDataActions": ["Microsoft.Storage/storageAccounts/blobServices/containers/blobs/*"]
       }]
     }
   }
   EOF
   )"

   Result: run Show the role; it prints actions as ["*/read"] and every subscription under Scopes. If not, see Troubleshooting.

8. Assign the role to each subscription:

   Copy Text

   for sub in "${SUBSCRIPTIONS[@]}"; do
     az role assignment create --assignee "$OPSLYFT_APP_ID" \
       --role "$ROLE_NAME" --scope "/subscriptions/$sub"
   done

   Result: run Check the role assignments on the subscriptions; it lists /subscriptions/<id> for each subscription. If not, see Troubleshooting.

9. Then go to Share with us.

Covers all current and future subscriptions under your root management group.

1. Open Azure Cloud Shell (Bash) in the Azure portal, or sign in with az login.

2. Set up your terminal

3. Get your root management group ID. If the output is empty, ask your Azure administrator:

   Copy Text

   export ROOT_MANAGEMENT_GROUP_ID="$(az account management-group list --query '[0].name' --output tsv)"; echo "$ROOT_MANAGEMENT_GROUP_ID"

4. Run Check the root management group, Check your directory rights and Check your management group rights.

5. Check that nothing exists yet: run Check that OpsLyft's application is registered, Check that the role name is free and Check the role assignment on the management group.

   Result: the app is reported as not found, and the role check and the assignment check print nothing. If one prints a value, follow Existing integration with OpsLyft.

6. Register OpsLyft's application in your tenant:

   Copy Text

   az ad sp create --id "$OPSLYFT_APP_ID"

   Result: run Check that OpsLyft's application is registered; it prints a row with the application ID. If not, see Troubleshooting.

7. Create the custom role at management group scope:

   Copy Text

   az role definition create --role-definition "$(cat <<EOF
   {
     "properties": {
       "roleName": "$ROLE_NAME",
       "description": "OpsLyft optimization read-only role",
       "assignableScopes": ["/providers/Microsoft.Management/managementGroups/$ROOT_MANAGEMENT_GROUP_ID"],
       "permissions": [{
         "actions": ["*/read"], "notActions": [], "dataActions": [],
         "notDataActions": ["Microsoft.Storage/storageAccounts/blobServices/containers/blobs/*"]
       }]
     }
   }
   EOF
   )"

   Result: run Show the role; it prints actions as ["*/read"] and the management group under Scopes. If not, see Troubleshooting.

8. Assign the role at the management group:

   Copy Text

   az role assignment create \
     --assignee "$OPSLYFT_APP_ID" \
     --role "$ROLE_NAME" \
     --scope "/providers/Microsoft.Management/managementGroups/$ROOT_MANAGEMENT_GROUP_ID"

   Result: run Check the role assignment on the management group; it lists your role at the management group. If not, see Troubleshooting.

9. Then go to Share with us.

1. Open Azure Cloud Shell (Bash) in the Azure portal, or sign in with az login.

2. Set up your terminal

3. List the subscriptions to check. Find the IDs with List your subscriptions and replace the bracketed IDs by hand:

   Copy Text

   SUBSCRIPTIONS=(<SUBSCRIPTION_ID_1> <SUBSCRIPTION_ID_2>)

4. Run Check that OpsLyft's application is registered.

   Result: a row with the application ID. If the app is not found, follow New integration with OpsLyft.

5. Find the role and where it is assigned: run Find the role assignments.

   Result: the Role (its name) and the Scope: /subscriptions/<id> or the management group. Nothing printed means no role: follow New integration with OpsLyft.

6. Set the role name to the one printed. If several roles are printed, repeat this check and the update once per role:

   Copy Text

   export ROLE_NAME="<role name printed above>"; echo "$ROLE_NAME"

7. Look at the role: run Show the role.

   Result: actions is ["*/read"], notActions and dataActions are [], notDataActions is ["Microsoft.Storage/storageAccounts/blobServices/containers/blobs/*"], and Scopes lists every subscription OpsLyft should read. If all match, there is nothing to update: go to Share with us. Otherwise continue with the update that matches the scope you found.

$SUBSCRIPTIONS must list every subscription OpsLyft should read, including those the role already covers.

1. Update the role. name and description are read from the existing role:

   Copy Text

   SCOPES=$(for sub in "${SUBSCRIPTIONS[@]}"; do printf '"/subscriptions/%s",' "$sub"; done); SCOPES="[${SCOPES%,}]"
   az role definition update --role-definition "$(cat <<EOF
   {
     "name": "$(az role definition list --name "$ROLE_NAME" --query '[0].name' --output tsv)",
     "roleName": "$ROLE_NAME",
     "description": "$(az role definition list --name "$ROLE_NAME" --query '[0].description' --output tsv)",
     "assignableScopes": $SCOPES,
     "permissions": [{
       "actions": ["*/read"], "notActions": [], "dataActions": [],
       "notDataActions": ["Microsoft.Storage/storageAccounts/blobServices/containers/blobs/*"]
     }]
   }
   EOF
   )"

   Result: run Show the role; it prints the expected values. If not, see Troubleshooting.

2. Assign the role to each subscription that does not have it:

   Copy Text

   for sub in "${SUBSCRIPTIONS[@]}"; do
     az role assignment create --assignee "$OPSLYFT_APP_ID" \
       --role "$ROLE_NAME" --scope "/subscriptions/$sub"
   done

   Result: run Check the role assignments on the subscriptions; it lists /subscriptions/<id> for each subscription. RoleAssignmentExists is not a failure.

3. Then go to Share with us.

1. Get your root management group ID. If the output is empty, ask your Azure administrator:

   Copy Text

   export ROOT_MANAGEMENT_GROUP_ID="$(az account management-group list --query '[0].name' --output tsv)"; echo "$ROOT_MANAGEMENT_GROUP_ID"

2. Update the role. name and description are read from the existing role:

   Copy Text

   az role definition update --role-definition "$(cat <<EOF
   {
     "name": "$(az role definition list --name "$ROLE_NAME" --query '[0].name' --output tsv)",
     "roleName": "$ROLE_NAME",
     "description": "$(az role definition list --name "$ROLE_NAME" --query '[0].description' --output tsv)",
     "assignableScopes": ["/providers/Microsoft.Management/managementGroups/$ROOT_MANAGEMENT_GROUP_ID"],
     "permissions": [{
       "actions": ["*/read"], "notActions": [], "dataActions": [],
       "notDataActions": ["Microsoft.Storage/storageAccounts/blobServices/containers/blobs/*"]
     }]
   }
   EOF
   )"

   Result: run Show the role; it prints the expected values. If not, see Troubleshooting.

3. Assign the role at the management group if it is not there yet:

   Copy Text

   az role assignment create \
     --assignee "$OPSLYFT_APP_ID" \
     --role "$ROLE_NAME" \
     --scope "/providers/Microsoft.Management/managementGroups/$ROOT_MANAGEMENT_GROUP_ID"

   Result: run Check the role assignment on the management group; it lists your role at the management group. RoleAssignmentExists is not a failure.

4. Then go to Share with us.

If OpsLyft sends updated role permissions, replace the permissions block below with the one OpsLyft sent, then run it. name, description and assignableScopes are read from the current role, and the assignments stay. $ROLE_NAME must be set.

az role definition update --role-definition "$(cat <<EOF
{
  "name": "$(az role definition list --name "$ROLE_NAME" --query '[0].name' --output tsv)",
  "roleName": "$ROLE_NAME",
  "description": "$(az role definition list --name "$ROLE_NAME" --query '[0].description' --output tsv)",
  "assignableScopes": $(az role definition list --name "$ROLE_NAME" --query '[0].assignableScopes' --output json),
  "permissions": [{
    "actions": ["*/read"], "notActions": [], "dataActions": [],
    "notDataActions": ["Microsoft.Storage/storageAccounts/blobServices/containers/blobs/*"]
  }]
}
EOF
)"

Result: run Show the role permissions; it prints the new permissions.

Use a bash terminal or Azure Cloud Shell. Run these once per terminal. If your terminal disconnects, run them again and set SUBSCRIPTIONS or ROOT_MANAGEMENT_GROUP_ID again.

1. Only in your own terminal (not needed in Azure Cloud Shell): Check that you are signed in

2. Set the default variables. Do not change OPSLYFT_APP_ID. ROLE_NAME is the role you create; change it if you prefer another name or the name is taken:

   Copy Text

   export OPSLYFT_APP_ID="01e5a9c2-d25f-4468-9875-12789b94ef71"; echo "$OPSLYFT_APP_ID"
   export ROLE_NAME="OpsLyftFetchUsageMetricsRole"; echo "$ROLE_NAME"
   export TENANT_ID="$(az account show --query tenantId --output tsv)"; echo "$TENANT_ID"
   export MY_ID="$(az ad signed-in-user show --query id --output tsv)"; echo "$MY_ID"

   If TENANT_ID or MY_ID is empty, sign in again (see the AADSTS700082 row in Troubleshooting) and repeat.

Shows the subscription and tenant you are signed in to.

az account show --query '{subscriptionId:id, tenantId:tenantId}' --output table

Prints your subscription ID and tenant ID. If az says "Please run 'az login'", run az login.

Shows your directory roles. You need a member account (not a guest) with the Application Administrator, Cloud Application Administrator or Global Administrator role.

az rest --method get --url "https://graph.microsoft.com/v1.0/me/memberOf/microsoft.graph.directoryRole" \
  --query "value[].displayName" --output tsv

Prints your directory roles; one of those three must be listed. If not, ask your Azure administrator to run the registration or grant you a role. A sign-in name containing #EXT# is a guest account, which cannot register it.

Shows your roles on each subscription in $SUBSCRIPTIONS. Uses $MY_ID.

for sub in "${SUBSCRIPTIONS[@]}"; do
  echo "== $sub"
  az role assignment list --assignee "$MY_ID" \
    --include-inherited --include-groups --scope "/subscriptions/$sub" \
    --query '[].roleDefinitionName' --output tsv
done

Prints your roles on each subscription. Owner or User Access Administrator must be listed (a message "Failed to query ... by invoking Graph API" above it is harmless). If neither is, ask your Azure administrator to run the steps or grant you the role.

Checks that the root management group exists. Uses $ROOT_MANAGEMENT_GROUP_ID.

az account management-group show --name "$ROOT_MANAGEMENT_GROUP_ID" --query '{groupId:id, name:displayName}' --output table

Prints one row.

Shows your roles on the root management group. Uses $MY_ID and $ROOT_MANAGEMENT_GROUP_ID.

az role assignment list --assignee "$MY_ID" \
  --include-inherited --include-groups \
  --scope /providers/Microsoft.Management/managementGroups/$ROOT_MANAGEMENT_GROUP_ID \
  --query '[].roleDefinitionName' --output tsv

Prints your roles on the management group. Owner or User Access Administrator must be listed; if neither is, ask your Azure administrator to run the steps or grant you the role.

Lists the subscriptions in your tenant.

az account list --query "[?tenantId=='$(az account show --query tenantId --output tsv)'].{name:name, subscriptionId:id}" --output table

Prints name and subscription ID of each subscription in your tenant. Subscriptions of other tenants from other sign-ins fail with InvalidAuthenticationTokenTenant.

Checks that OpsLyft's application is in your tenant. Uses $OPSLYFT_APP_ID.

az ad sp show --id "$OPSLYFT_APP_ID" --query '{appId:appId, name:displayName}' --output table

Prints a row with the application ID. An error saying the resource does not exist means it is not registered yet.

Checks that no role with that name exists. Uses $ROLE_NAME.

az role definition list --name "$ROLE_NAME" --query '[].roleName' --output tsv

Prints nothing when the name is free. If it prints the name, the role already exists: follow Existing integration with OpsLyft, or set another ROLE_NAME.

Checks that the role is assigned on each subscription. Uses $OPSLYFT_APP_ID, $ROLE_NAME and $SUBSCRIPTIONS.

for sub in "${SUBSCRIPTIONS[@]}"; do
  echo "== $sub"
  az role assignment list --assignee "$OPSLYFT_APP_ID" --subscription "$sub" \
    --query "[?roleDefinitionName=='$ROLE_NAME'].scope" --output tsv
done

Prints /subscriptions/<id> under each subscription that has the role, and nothing under one that does not.

Checks that the role is assigned at the management group. Uses $OPSLYFT_APP_ID, $ROLE_NAME and $ROOT_MANAGEMENT_GROUP_ID.

az role assignment list --assignee "$OPSLYFT_APP_ID" \
  --scope "/providers/Microsoft.Management/managementGroups/$ROOT_MANAGEMENT_GROUP_ID" \
  --query '[].{Role:roleDefinitionName, Scope:scope}' --output table

Prints the role and scope; your role is listed when it is assigned, and nothing prints when it is not.

Shows the role and its scopes. Uses $ROLE_NAME.

az role definition list --name "$ROLE_NAME" \
  --query '[].{Scopes:assignableScopes, Permissions:permissions[0]}' --output json

Prints Scopes (the subscriptions or the management group) and the permission fields actions, notActions, dataActions and notDataActions.

Finds the role and where it is assigned. Uses $OPSLYFT_APP_ID and $SUBSCRIPTIONS.

for sub in "${SUBSCRIPTIONS[@]}"; do
  echo "== $sub"
  az role assignment list --assignee "$OPSLYFT_APP_ID" --subscription "$sub" --include-inherited \
    --query '[].{Role:roleDefinitionName, Scope:scope}' --output table
done

Prints per subscription the Role (the role name to set) and the Scope (a subscription or the management group).

Shows the permissions of the role. Run it after an update. Uses $ROLE_NAME.

az role definition list --name "$ROLE_NAME" --query '[].permissions[0]' --output json

Prints the permissions of the role.

Removing the role assignment is enough to stop OpsLyft reading; deleting the role is optional. Tell OpsLyft when you have removed access. Set $OPSLYFT_APP_ID and $ROLE_NAME first, plus $SUBSCRIPTIONS or $ROOT_MANAGEMENT_GROUP_ID for the level you use (see Set up your terminal). Run only the command for the level you used.

For subscriptions:

for sub in "${SUBSCRIPTIONS[@]}"; do
  az role assignment delete --assignee "$OPSLYFT_APP_ID" --role "$ROLE_NAME" \
    --scope "/subscriptions/$sub"
done

For the root management group:

az role assignment delete --assignee "$OPSLYFT_APP_ID" --role "$ROLE_NAME" \
  --scope "/providers/Microsoft.Management/managementGroups/$ROOT_MANAGEMENT_GROUP_ID"

To delete the role afterwards (once every assignment is removed):

az role definition delete --name "$ROLE_NAME"