Setting Up an Azure service principal for billing data monitoring

Task overview

To set up a service principal for billing data monitoring, perform the following tasks in the Azure portal:

• Scenario 1: Use the existing service principal that you set up for workload monitoring.

  Skip the first three tasks in this topic and perform only the following tasks:

  1. Enable access to billing data.

  2. (Azure Government only) Enable access to reservations.

• Scenario 2: Create a new service principal specifically for billing data monitoring.

  Perform all the tasks in this topic.

  1. Register Turbonomic with Microsoft Entra ID (formerly known as Azure Active Directory).

  2. Create a client secret key.

  3. Configure API permissions.

  4. Enable access to billing data.

  5. (Azure Government only) Enable access to reservations.

Registering Turbonomic with Microsoft Entra ID (formerly known as Azure Active Directory)

Creating a client secret

1. Browse to Microsoft Entra ID > App registrations and then select the app registration for the service principal that you created for Turbonomic.

2. In the navigation menu, select Certificates & secrets.

3. Select Client secrets and then select New client secret.

4. Configure the following settings:

   Setting	Instructions
   Description	Specify a meaningful description.
   Expires	Choose Never.

5. Select Add.

6. Record the client secret value. You will need this information later when you add an Azure service principal target in the Turbonomic user interface.

   Important:

   The client secret value only displays once. It will no longer be available after you leave the page.

Configuring API permissions

1. Browse to Microsoft Entra ID > App registrations and then select the app registration for the service principal that you created for Turbonomic.

2. In the navigation menu, select API permissions.

3. Click Add a permission and select Azure Service Management.

4. Select Delegated permissions and user_impersonation, and then click Add permissions.

Enabling access to billing data

To enable access to billing data, assign the required role to the service principal that you set up for Turbonomic. Note that only users with the Global Administrator role and with elevated access can assign the role to the service principal. Elevated access grants permissions to assign roles in Azure subscriptions and management groups associated with Microsoft Entra ID (formerly known as Azure Active Directory). For instructions on elevating access for users, see the Azure documentation.

The following roles are required:

Assigning the Enrollment Reader role to Global Azure EA accounts

If you have global Azure EA accounts, assign the Enrollment Reader role to enable access to billing data. To assign the role, execute an API request in the Microsoft Learn portal.

1. Record the values for the following parameters. These values are required when assigning the role:

   Parameter	Value
   billingAccountName	Billing account ID: In the Azure portal, navigate to Cost management + Billing, open your EA account, and then select Overview. The screen that displays includes a field for the Billing Account ID. "
   billingRoleAssignmentName	A unique GUID: To generate a GUID, use the New-Guid PowerShell command in Microsoft Learn or the Online GUID / UUID Generator website.
   api-version	2019-10-01-preview: This is a static value.
   properties.principalId	Object ID specified in Microsoft Entra ID: For help locating the Object ID, see the Azure documentation.
   properties.principalTenantId	Tenant ID specified in Microsoft Entra ID: For help locating the Tenant ID, see the Azure documentation.

2. Open the Microsoft Learn portal. Sign in when prompted.

3. In the following fields, specify the values that you recorded in the previous step.

   Field	Value
   billingAccountName	{your_billing_account_ID}
   billingRoleAssignmentName	{your_unique_GUID}
   api-version	2019-10-01-preview

4. In the Body field, paste the following content.

   {
     "properties": {
       "principalId": "{your_object_ID}",
       "principalTenantId": "{your_tenant_ID}",
       "roleDefinitionId": "/providers/Microsoft.Billing/billingAccounts/{your_billing_account_ID}/billingRoleAssignments/24f8edb6-1668-4659-b5e2-40bb5f3a7d7e"
     }
   }

   Note:

   24f8edb6-1668-4659-b5e2-40bb5f3a7d7e is the ID that Microsoft assigned to the Enrollment Reader role.

5. Replace the following variables with the values that you recorded in the previous step.

   • {your_object_ID}

   • {your_tenant_ID}

   • {your_billing_account_ID}

6. Review the request preview and then click Run.

   The Enrollment Reader role is now assigned.

Assigning the Enrollment Reader role to Azure Government EA accounts

For Azure Government EA accounts, it is not possible to execute an API request in the Microsoft Learn portal. This is because the API request in the portal is hard-coded and executes against https://management.azure.com, which only applies to global Azure EA accounts. The API request for Azure Government EA accounts should execute against https://management.usgovcloudapi.net.

This section describes how to assign the Enrollment Reader role using a script that you run in a PowerShell session in Azure Cloud Shell.

Before proceeding, be sure you have the Application (client) ID for the service principal that you set up for Turbonomic in a previous task. You will specify this ID when you run the script.

1. In your local machine, create a file named Turbonomic-GovCloudBillingReader.ps1 and then copy the following script to the file.

   ### Get your Azure Authentication token and create your Azure Authentication Header
   $token = (Get-AzAccessToken).Token
   $headers = @{'Authorization' = "Bearer $token" }
   
   ### Get the Service Principal, Tenant, Billing Account, and Role properties
   $servicePrincipalApplicationID = Read-Host "Enter your Service Principal's Application (client) ID" 
   $servicePrincipalApplication = (Get-AzADServicePrincipal -ApplicationID $servicePrincipalApplicationID)
   $servicePrincipalObjectID = $servicePrincipalApplication.id
   $tenant = Get-AzTenant
   write-host "Your tenant ID is: $($tenant.Name) (ID: $($tenant.id))"
   $billingAccount = (Get-AzBillingAccount).Name
   write-host "Your Billing Account ID is: $billingAccount"
   $roleDefinitionID = "/providers/Microsoft.Billing/billingAccounts/$billingAccount/billingRoleDefinitions/24f8edb6-1668-4659-b5e2-40bb5f3a7d7e"
   $billingRoleAssignmentName = (New-GUID).GUID
   write-host "Your Application permission's unique GUID is $billingRoleAssignmentName"
   $apiVersion = "api-version=2019-10-01-preview"
   
   ### Create the JSON payload used in the permissions API call
   write-host "Creating the permission JSON body"
   $json = @"
    {
    "properties":{
    "principalId": "$servicePrincipalObjectID",
        "principalTenantId": "$tenant",
        "roleDefinitionId": "$roleDefinitionID"
        }
    }
   "@
   
   ### Create the URL path for the permissions API call
   $invokeBaseURL = "https://management.usgovcloudapi.net"
   $invokeBillingURL = "/providers/Microsoft.Billing/billingAccounts/$billingAccount/billingRoleAssignments/$($billingRoleAssignmentName)?$apiVersion"
   $invokeURL = $invokeBaseURL+$invokeBillingURL
   
   ### Print the specifics that will be used in the API call for verification
   write-host "Attempting to set permissions for the following Application"
   write-host "`tAzure Tenant: $($tenant.Name) (ID: $($tenant.Id))"
   write-host "`tService Principal Application Name: $($servicePrincipalApplication.DisplayName)"
   write-host "`tService Principal Application (client) ID: $($servicePrincipalApplicationID)"
   write-host "`tService Principal Object ID: $($servicePrincipalObjectID)"
   write-host "`nThe permission JSON is:"
   write-host $json
   write-host "`n`nContinuing will attempt to set the Billing Reader role permissions for this Service Principal in Azure tenant $($tenant.Name) (ID: $($tenant.Id))"
   Pause
   
   ### Attempt to set the Billing Reader role permissions for the Service Principal
   Invoke-RestMethod -Uri $invokeURL -headers $headers -ContentType "application/json" -body $json -Method PUT

2. Sign in to the Azure Government portal with a user account that has permissions to use Azure Cloud Shell and assign roles to billing accounts.

   https://portal.azure.us

3. In the navigation bar on top of the page, select the Cloud Shell icon.

4. In the Cloud Shell window that opens, go to the navigation bar and then perform the following steps:

   1. Select the dropdown list on the left and then choose PowerShell to start a PowerShell session.

   2. Select the upload/download files icon, select Upload, and then upload the file that you created.

5. In the command line, run the following command to execute the script.

   ./Turbonomic-GovCloudBillingReader.ps1

6. Specify the Application (client) ID for the service principal that you set up for Turbonomic.

   The Enrollment Reader role is now assigned.

Assigning the Billing Account Reader role to MCA accounts

If you have MCA accounts, assign the Billing Account Reader role to enable access to billing data.

1. Browse to Cost Management + Billing > Access control (IAM).

2. Select Add.

3. Select Billing account reader and then select the app registration for the service principal that you created for Turbonomic.

Enabling discovery of Azure reservations (Azure Government only)

If you have reservations for your Azure Government workloads, enable access to these reservations by assigning the built-in Reservations Reader role to the service principal that you set up for Turbonomic.

1. Sign in to the Azure Government portal with a user account that has permissions to assign roles to reservations.

   https://portal.azure.us

   Be sure that you are working in the correct Azure directory where you will assign the Reservations Reader role.

2. (Recommended) To speed up the process of connecting Turbonomic to Azure, create a Microsoft Entra group that includes all the service principals that will be assigned the Reservations Reader role.

   Any service principal that you add to the group in the future will automatically be assigned the Reservations Reader role.

3. Browse to the Reservations page.

   https://portal.azure.us/#view/Microsoft_Azure_Reservations/ReservationsBrowseBlade/productType/Reservations

4. In the Reservations page, choose Role Assignment.

5. In the Access Control page, choose Add role assignment.

6. In the Add role assignment page:

   1. Choose the Role tab.

   2. In the search bar, type Reservations Reader as your search keyword.

   3. Choose Reservations Reader from the list of built-in roles that display and then choose Next.

   4. In the Members tab, choose + Select members.

   5. Search for the service principal or Microsoft Entra group (if you created one in a previous step) that you set up for Turbonomic.

   6. Add the service principal or group to the list of members. Optionally, specify a description for this role assignment and then choose Next.

   7. In the Review + Assign tab, review your settings and then choose Review + assign.

Enabling discovery of Azure savings plans

If you have savings plans for your Azure workloads, enable access to these savings plans by assigning the built-in Savings Plan Reader role to the service principal that you set up for Turbonomic.

1. Sign in to the Azure portal with a user account that has permissions to assign roles to savings plans.

   https://portal.azure.com

   Be sure that you are working in the correct Azure directory where you will assign the Savings Plan Reader role.

2. (Recommended) To speed up the process of connecting Turbonomic to Azure, create a Microsoft Entra group that includes all the service principals that will be assigned the Savings Plan Reader role.

   Any service principal that you add to the group in the future will automatically be assigned the Savings Plan Reader role.

3. Browse to the Savings plans page.

   https://portal.azure.com/#view/Microsoft_Azure_Reservations/ReservationsBrowseBlade/productType/SavingsPlan

4. In the Savings plans page, choose Role Assignment.

5. In the Access Control page, choose Add role assignment.

6. In the Add role assignment page:

   1. Choose the Role tab.

   2. In the search bar, type savings plan reader as your search keyword.

   3. Choose Savings Plan Reader from the list of built-in roles that display and then choose Next.

   4. In the Members tab, choose + Select members.

   5. Search for the service principal or Microsoft Entra group (if you created one in a previous step) that you set up for Turbonomic.

   6. Add the service principal or group to the list of members. Optionally, specify a description for this role assignment and then choose Next.

   7. In the Review + Assign tab, review your settings and then choose Review + assign.

Next step

Add an Azure Billing target in Turbonomic. For details, see this topic.