Edit

Share via

Assign Enterprise Agreement roles to service principals

  • Article

You can manage your Enterprise Agreement (EA) enrollment in the Azure portal. You can create different roles to manage your organization, view costs, and create subscriptions. This article helps you automate some of those tasks by using Azure PowerShell and REST APIs with Microsoft Entra ID service principals.

Note

If you have multiple EA billing accounts in your organization, you must grant the EA roles to Microsoft Entra ID service principals individually in each EA billing account.

Before you begin, ensure that you're familiar with the following articles:

You need a way to call REST APIs. Some popular ways to query the API are:

Create and authenticate your service principal

To automate EA actions by using a service principal, you need to create a Microsoft Entra app identity, which can then authenticate in an automated manner.

Follow the steps in these articles to create and authenticate using your service principal.

Here's an example of the application registration page.

Screenshot showing Register an application.

Find your service principal and tenant IDs

You need the service principal's object ID and the tenant ID. You need this information for permission assignment operations later in this article. All applications are registered in Microsoft Entra ID in the tenant. Two types of objects get created when the app registration is completed:

  • Application object - The application ID is what you see under Enterprise Applications. Don't use the ID to grant any EA roles.
  • Service Principal object - The Service Principal object is what you see in the Enterprise Registration window in Microsoft Entra ID. The object ID is used to grant EA roles to the service principal.

  1. Open Microsoft Entra ID, and then select Enterprise applications.

  2. Find your app in the list.

    Screenshot showing an example enterprise application.

  3. Select the app to find the application ID and object ID:

    Screenshot showing an application ID and object ID for an enterprise application.

  4. Go to the Microsoft Entra ID Overview page to find the tenant ID.

    Screenshot showing the tenant ID.

Note

The value of your Microsoft Entra tenant ID looks like a GUID with the following format: aaaabbbb-0000-cccc-1111-dddd2222eeee.

Permissions that can be assigned to the service principal

Later in this article, you give permission to the Microsoft Entra app to act by using an EA role. You can assign only the following roles to the service principal, and you need the role definition ID, exactly as shown.

Role Actions allowed Role definition ID
EnrollmentReader Enrollment readers can view data at the enrollment, department, and account scopes. The data contains charges for all of the subscriptions under the scopes, including across tenants. Can view the Azure Prepayment (previously called monetary commitment) balance associated with the enrollment. 24f8edb6-1668-4659-b5e2-40bb5f3a7d7e
EA purchaser Purchase reservation orders and view reservation transactions. It has all the permissions of EnrollmentReader, which have all the permissions of DepartmentReader. It can view usage and charges across all accounts and subscriptions. Can view the Azure Prepayment (previously called monetary commitment) balance associated with the enrollment. da6647fb-7651-49ee-be91-c43c4877f0c4
DepartmentReader Download the usage details for the department they administer. Can view the usage and charges associated with their department. db609904-a47f-4794-9be8-9bd86fbffd8a
SubscriptionCreator Create new subscriptions in the given scope of Account. a0bcee42-bf30-4d1b-926a-48d21664ef71
  • An EnrollmentReader role can be assigned to a service principal only by a user who has an enrollment writer role. The EnrollmentReader role assigned to a service principal isn't shown in the Azure portal. It gets created by programmatic means and is only for programmatic use.
  • A DepartmentReader role can be assigned to a service principal only by a user who has an enrollment writer or department writer role.
  • A SubscriptionCreator role can be assigned to a service principal only by a user who is the owner of the enrollment account (EA administrator). The role isn't shown in the Azure portal. It gets created by programmatic means and is only for programmatic use.
  • The EA purchaser role isn't shown in the Azure portal. It gets created by programmatic means and is only for programmatic use.

When you grant an EA role to a service principal, you must use the billingRoleAssignmentName required property. The parameter is a unique GUID that you must provide. You can generate a GUID using the New-Guid PowerShell command. You can also use the Online GUID / UUID Generator website to generate a unique GUID.

A service principal can have only one role.

Assign enrollment account role permission to the service principal

  1. Read the Role Assignments - Put REST API article. While you read the article, select Try it to get started by using the service principal.

    Screenshot showing the Try It option in the Put article.

  2. Use your account credentials to sign in to the tenant with the enrollment access that you want to assign.

  3. Provide the following parameters as part of the API request.

    • billingAccountName: This parameter is the Billing account ID. You can find it in the Azure portal on the Cost Management + Billing overview page.

      Screenshot showing Billing account ID.

    • billingRoleAssignmentName: This parameter is a unique GUID that you need to provide. You can generate a GUID using the New-Guid PowerShell command. You can also use the Online GUID / UUID Generator website to generate a unique GUID.

    • api-version: Use the 2019-10-01-preview version. Use the sample request body at Role Assignments - Put - Examples.

      The request body has JSON code with three parameters that you need to use.

      Parameter Where to find it
      properties.principalId It's the value of Object ID. See Find your service principal and tenant IDs.
      properties.principalTenantId See Find your service principal and tenant IDs.
      properties.roleDefinitionId /providers/Microsoft.Billing/billingAccounts/{BillingAccountName}/billingRoleDefinitions/24f8edb6-1668-4659-b5e2-40bb5f3a7d7e

      The billing account name is the same parameter that you used in the API parameters. It's the enrollment ID that you see in the Azure portal.

      Notice that 24f8edb6-1668-4659-b5e2-40bb5f3a7d7e is a billing role definition ID for an EnrollmentReader.

  4. Select Run to start the command.

    Screenshot showing an example role assignment with example information that is ready to run.

    A 200 OK response shows that the service principal was successfully added.

Now you can use the service principal to automatically access EA APIs. The service principal has the EnrollmentReader role.

Assign EA Purchaser role permission to the service principal

For the EA purchaser role, use the same steps for the enrollment reader. Specify the roleDefinitionId, using the following example:

"/providers/Microsoft.Billing/billingAccounts/1111111/billingRoleDefinitions/ da6647fb-7651-49ee-be91-c43c4877f0c4"

Assign the department reader role to the service principal

  1. Read the Enrollment Department Role Assignments - Put REST API article. While you read the article, select Try it.

    Screenshot showing the Try It option in the Enrollment Department Role Assignments Put article.

  2. Use your account credentials to sign in to the tenant with the enrollment access that you want to assign.

  3. Provide the following parameters as part of the API request.

    • billingAccountName: This parameter is the Billing account ID. You can find it in the Azure portal on the Cost Management + Billing overview page.

      Screenshot showing Billing account ID.

    • billingRoleAssignmentName: This parameter is a unique GUID that you need to provide. You can generate a GUID using the New-Guid PowerShell command. You can also use the Online GUID / UUID Generator website to generate a unique GUID.

    • departmentName: This parameter is the department ID. You can see department IDs in the Azure portal on the Cost Management + Billing > Departments page.

      For this example, we used the ACE department. The ID for the example is 84819.

      Screenshot showing an example department ID.

    • api-version: Use the 2019-10-01-preview version. Use the sample at Enrollment Department Role Assignments - Put.

      The request body has JSON code with three parameters that you need to use.

      Parameter Where to find it
      properties.principalId It's the value of Object ID. See Find your service principal and tenant IDs.
      properties.principalTenantId See Find your service principal and tenant IDs.
      properties.roleDefinitionId /providers/Microsoft.Billing/billingAccounts/{BillingAccountName}/billingRoleDefinitions/db609904-a47f-4794-9be8-9bd86fbffd8a

      The billing account name is the same parameter that you used in the API parameters. It's the enrollment ID that you see in the Azure portal.

      The billing role definition ID of db609904-a47f-4794-9be8-9bd86fbffd8a is for a department reader.

  4. Select Run to start the command.

    Screenshot showing an example Enrollment Department Role Assignments – Put REST Try It with example information ready to run.

    A 200 OK response shows that the service principal was successfully added.

Now you can use the service principal to automatically access EA APIs. The service principal has the DepartmentReader role.

Assign the subscription creator role to the service principal

  1. Read the Enrollment Account Role Assignments - Put article. While you read it, select Try It to assign the subscription creator role to the service principal.

    Screenshot showing the Try It option in the Enrollment Account Role Assignments Put article.

  2. Use your account credentials to sign in to the tenant with the enrollment access that you want to assign.

  3. Provide the following parameters as part of the API request. Read the article at Enrollment Account Role Assignments - Put - URI Parameters.

    • billingAccountName: This parameter is the Billing account ID. You can find it in the Azure portal on the Cost Management + Billing overview page.

      Screenshot showing the Billing account ID.

    • billingRoleAssignmentName: This parameter is a unique GUID that you need to provide. You can generate a GUID using the New-Guid PowerShell command. You can also use the Online GUID/UUID Generator website to generate a unique GUID.

    • enrollmentAccountName: This parameter is the account ID. Find the account ID for the account name in the Azure portal on the Cost Management + Billing page.

      For this example, we used the GTM Test Account. The ID is 196987.

      Screenshot showing the account ID.

    • api-version: Use the 2019-10-01-preview version. Use the sample at Enrollment Department Role Assignments - Put - Examples.

      The request body has JSON code with three parameters that you need to use.

      Parameter Where to find it
      properties.principalId It's the value of Object ID. See Find your service principal and tenant IDs.
      properties.principalTenantId See Find your service principal and tenant IDs.
      properties.roleDefinitionId /providers/Microsoft.Billing/billingAccounts/{BillingAccountID}/enrollmentAccounts/{enrollmentAccountID}/billingRoleDefinitions/a0bcee42-bf30-4d1b-926a-48d21664ef71

      The billing account name is the same parameter that you used in the API parameters. It's the enrollment ID that you see in the Azure portal.

      The billing role definition ID of a0bcee42-bf30-4d1b-926a-48d21664ef71 is for the subscription creator role.

  4. Select Run to start the command.

    Screenshot showing the Try It option in the Enrollment Account Role Assignments - Put article.

    A 200 OK response shows that the service principal was successfully added.

Now you can use the service principal to automatically access EA APIs. The service principal has the SubscriptionCreator role.

Verify service principal role assignments

Service principal role assignments aren't visible in the Azure portal. You can view enrollment account role assignments, including the subscription creator role, with the Billing Role Assignments - List By Enrollment Account - REST API (Azure Billing) API. Use the API to verify that the role assignment was successful.

Troubleshoot

You must identify and use the Enterprise application object ID where you granted the EA role. If you use the Object ID from some other application, API calls fail. Verify that you’re using the correct Enterprise application object ID.

If you receive the following error when making your API call, then you might be incorrectly using the service principal object ID value located in App Registrations. To resolve this error, ensure you're using the service principal object ID from Enterprise Applications, not App Registrations.

The provided principal Tenant Id = xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx and principal Object Id xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx are not valid

Next steps

Get started with your Enterprise Agreement billing account.