Uredi

Assign roles to Azure Enterprise Agreement service principal names

  • Članak

You can manage your Enterprise Agreement (EA) enrollment in the Azure Enterprise portal. Direct Enterprise customer can now manage Enterprise Agreement(EA) enrollment in 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 Azure service principal names (SPNs).

Note

If you have multiple EA billing accounts in your organization, you must grant the EA roles to Azure SPNs individually in each EA billing account.

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

Create and authenticate your service principal

To automate EA actions by using an SPN, you need to create a Microsoft Entra application. It can authenticate in an automated manner.

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

Here's an example of the application registration page.

Screenshot showing Register an application.

Find your SPN and tenant ID

You also need the object ID of the SPN and the tenant ID of the app. 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 object ID is what you see under App Registrations in Microsoft Entra ID. The object ID should not be used 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 SPN.

  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

Your tenant ID might be called a principal ID, SPN, or object ID in other locations. The value of your Microsoft Entra tenant ID looks like a GUID with the following format: 11111111-1111-1111-1111-111111111111.

Permissions that can be assigned to the SPN

Later in this article, you'll give permission to the Microsoft Entra app to act by using an EA role. You can assign only the following roles to the SPN, 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 will in turn 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 an SPN only by a user who has an enrollment writer role. The EnrollmentReader role assigned to an SPN isn't shown in the EA portal. It's created by programmatic means and is only for programmatic use.
  • A DepartmentReader role can be assigned to an SPN only by a user who has an enrollment writer or department writer role.
  • A SubscriptionCreator role can be assigned to an SPN only by a user who is the owner of the enrollment account (EA administrator). The role isn't shown in the EA portal. It's created by programmatic means and is only for programmatic use.
  • The EA purchaser role isn't shown in the EA portal. It's created by programmatic means and is only for programmatic use.

When you grant an EA role to an SPN, 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.

An SPN can have only one role.

Assign enrollment account role permission to the SPN

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

    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 is the value of Object ID. See Find your SPN and tenant ID.
      properties.principalTenantId See Find your SPN and tenant ID.
      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 EA portal and 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 put Try It with example information ready to run.

    A 200 OK response shows that the SPN was successfully added.

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

Assign EA Purchaser role permission to the SPN

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 SPN

  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 is the value of Object ID. See Find your SPN and tenant ID.
      properties.principalTenantId See Find your SPN and tenant ID.
      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 EA portal and 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 SPN was successfully added.

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

Assign the subscription creator role to the SPN

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

    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 is the value of Object ID. See Find your SPN and tenant ID.
      properties.principalTenantId See Find your SPN and tenant ID.
      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 EA portal and 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 SPN has been successfully added.

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

Verify SPN role assignments

SPN role assignments are not 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 will 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 may be incorrectly using the SPN object ID value located in App Registrations. To resolve this error, ensure you're using the SPN 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

Learn more about Azure EA portal administration.