Assign Enterprise Agreement roles to service principals

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.

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

• Enterprise agreement roles
• Sign in with Azure PowerShell

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

• Visual Studio
• Insomnia
• Bruno
• PowerShell’s Invoke-RestMethod
• Curl

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.

• Create a service principal
• Get tenant and app ID values for signing in

Here's an example of the application registration page.

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.

   

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

   

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

   

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.

The following user roles are required to assign each service principal role:

• EnrollmentReader: user assigning must have enrollment writer role.
• DepartmentReader: user assigning must have enrollment writer or department writer role.
• SubscriptionCreator: user assigning must be the enrollment account owner (EA administrator).
• EA purchaser: user assigning must have enrollment writer role.
• Partner Admin Reader: user assigning must have partner administrator role.

All of these roles are created by programmatic means, aren't shown in the Azure portal, and are 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 a role to the service principal

Follow these steps to assign any of the supported roles to a service principal:

1. Use the appropriate Role Assignments Put REST API and select Try it. Find the correct API to use in the table below.

2. Sign in to the tenant with the required access.

3. Provide the following parameters in your API request:

   • billingAccountName: The Billing account ID. For the Partner Admin Reader role, use the format pcn.{PCN} (where {PCN} is your Partner Customer Number). For all other roles, use the standard billing account ID from the Azure portal.

   

   • billingRoleAssignmentName: A unique GUID you generate (see New-Guid).
   • api-version: Use 2019-10-01-preview unless otherwise noted.
   • Request body parameters:
     • properties.principalId: The Object ID of the service principal.
     • properties.principalTenantId: The tenant ID.
     • properties.roleDefinitionId: Use the value from the table below.

1. Select Run to execute the command.

5. A 200 OK response means the service principal was successfully assigned the 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.