Tilbakemeldinger Rediger

Assign roles to Azure Enterprise Agreement service principal names

  • Artikkel
  • 7 minutter å lese

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).

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 an Azure Active Directory (Azure AD) 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.

  1. Open Azure Active Directory, 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 Azure AD 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 Azure AD 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 Azure AD 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 Can view usage and charges across all accounts and subscriptions. 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. 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.
  • 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.

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/196987/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.

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.