Skip to content

Commit e083061

Browse files
Stacyrch140Stacyrch140
authored
Merge pull request #301875 from maddieminn/update-partner-spn-doc
Reformat Doc Structure for "Assign EA roles to SPNs"
2 parents 87221ba + d460f71 commit e083061

File tree

1 file changed

+34
-135
lines changed

1 file changed

+34
-135
lines changed

‎articles/cost-management-billing/manage/assign-roles-azure-service-principals.md

Lines changed: 34 additions & 135 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ ms.reviewer: prsaini
66
ms.service: cost-management-billing
77
ms.subservice: enterprise
88
ms.topic: how-to
9-
ms.date: 05/14/2025
9+
ms.date: 06/25/2025
1010
ms.author: prsaini
1111
---
1212

@@ -78,7 +78,7 @@ Later in this article, you give permission to the Microsoft Entra app to act by
7878
| SubscriptionCreator | Create new subscriptions in the given scope of Account. | a0bcee42-bf30-4d1b-926a-48d21664ef71 |
7979
| Partner Admin Reader | View data for all enrollments under the partner organization. This role is only available for the following APIs:<br>- [Balances](/rest/api/consumption/balances/get-by-billing-account)<br>- [Exports V2 (api-version 2025-03-01 only)](/rest/api/cost-management/exports)<br>- [Generate Cost Details Report](/rest/api/cost-management/generate-cost-details-report)<br>- [Marketplaces](/rest/api/consumption/marketplaces/list)<br>- [Consumption Price sheet](/rest/api/consumption/price-sheet)<br>- [Cost Management Price sheet Download](/rest/api/cost-management/price-sheet/download-by-billing-account)<br>- [Generate Reservation Details Report](/rest/api/cost-management/generate-reservation-details-report/by-billing-account-id)<br>- [Reservation Summaries](/rest/api/consumption/reservations-summaries)<br>- [Reservation Recommendations](/rest/api/consumption/reservation-recommendations/list)<br>- [Reservation Transactions](/rest/api/consumption/reservation-transactions) | 4f6144c0-a809-4c55-b3c8-7f9b7b15a1bf |
8080

81-
- The following user roles are required to assign each service principal role:
81+
The following user roles are required to assign each service principal role:
8282
- **EnrollmentReader:** user assigning must have _enrollment writer_ role.
8383
- **DepartmentReader:** user assigning must have _enrollment writer_ or _department writer_ role.
8484
- **SubscriptionCreator:** user assigning must be the _enrollment account owner_ (EA administrator).
@@ -91,139 +91,38 @@ When you grant an EA role to a service principal, you must use the `billingRoleA
9191

9292
A service principal can have only one role.
9393

94-
## Assign enrollment account role permission to the service principal
95-
96-
1. Read the [Role Assignments - Put](/rest/api/billing/2019-10-01-preview/role-assignments/put) REST API article. While you read the article, select **Try it** to get started by using the service principal.
97-
98-
:::image type="content" source="./media/assign-roles-azure-service-principals/put-try-it.png" alt-text="Screenshot showing the Try It option in the Put article." lightbox="./media/assign-roles-azure-service-principals/put-try-it.png" :::
99-
100-
1. Use your account credentials to sign in to the tenant with the enrollment access that you want to assign.
101-
102-
1. Provide the following parameters as part of the API request.
103-
104-
- `billingAccountName`: This parameter is the **Billing account ID**. You can find it in the Azure portal on the **Cost Management + Billing** overview page.
105-
- For the **Partner Admin Reader** role, use the format `pcn.{PCN}` for the billing account name, where `{PCN}` is your partner organization's Partner Customer Number.
106-
- For all other roles, use the standard billing account ID as shown in the Azure portal.
107-
108-
:::image type="content" source="./media/assign-roles-azure-service-principals/billing-account-id.png" alt-text="Screenshot showing Billing account ID." lightbox="./media/assign-roles-azure-service-principals/billing-account-id.png" :::
109-
110-
- `billingRoleAssignmentName`: This parameter is a unique GUID that you need to provide. You can generate a GUID using the [New-Guid](/powershell/module/microsoft.powershell.utility/new-guid) PowerShell command. You can also use the [Online GUID / UUID Generator](https://guidgenerator.com/) website to generate a unique GUID.
111-
112-
- `api-version`: Use the **2019-10-01-preview** version. Use the sample request body at [Role Assignments - Put - Examples](/rest/api/billing/2019-10-01-preview/role-assignments/put#examples).
113-
114-
The request body has JSON code with three parameters that you need to use.
115-
116-
| Parameter | Where to find it |
117-
| --- | --- |
118-
| `properties.principalId` | It's the value of Object ID. See [Find your service principal and tenant IDs](#find-your-service-principal-and-tenant-ids). |
119-
| `properties.principalTenantId` | See [Find your service principal and tenant IDs](#find-your-service-principal-and-tenant-ids). |
120-
| `properties.roleDefinitionId` | `/providers/Microsoft.Billing/billingAccounts/{BillingAccountName}/billingRoleDefinitions/24f8edb6-1668-4659-b5e2-40bb5f3a7d7e` |
121-
122-
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.
123-
124-
Notice that `24f8edb6-1668-4659-b5e2-40bb5f3a7d7e` is a billing role definition ID for an EnrollmentReader.
125-
126-
1. Select **Run** to start the command.
127-
128-
:::image type="content" source="./media/assign-roles-azure-service-principals/roleassignments-put-try-it-run.png" alt-text="Screenshot showing an example role assignment with example information that is ready to run." lightbox="./media/assign-roles-azure-service-principals/roleassignments-put-try-it-run.png" :::
129-
130-
A `200 OK` response shows that the service principal was successfully added.
131-
132-
Now you can use the service principal to automatically access EA APIs. The service principal has the EnrollmentReader role.
133-
134-
## Assign EA Purchaser role permission to the service principal
135-
136-
For the EA purchaser role, use the same steps for the enrollment reader. Specify the `roleDefinitionId`, using the following example:
137-
138-
`"/providers/Microsoft.Billing/billingAccounts/1111111/billingRoleDefinitions/ da6647fb-7651-49ee-be91-c43c4877f0c4"`
139-
140-
## Assign the department reader role to the service principal
141-
142-
1. Read the [Enrollment Department Role Assignments - Put](/rest/api/billing/2019-10-01-preview/enrollment-department-role-assignments/put) REST API article. While you read the article, select **Try it**.
143-
144-
:::image type="content" source="./media/assign-roles-azure-service-principals/enrollment-department-role-assignments-put-try-it.png" alt-text="Screenshot showing the Try It option in the Enrollment Department Role Assignments Put article." lightbox="./media/assign-roles-azure-service-principals/enrollment-department-role-assignments-put-try-it.png" :::
145-
146-
1. Use your account credentials to sign in to the tenant with the enrollment access that you want to assign.
147-
148-
1. Provide the following parameters as part of the API request.
149-
150-
- `billingAccountName`: This parameter is the **Billing account ID**. You can find it in the Azure portal on the **Cost Management + Billing** overview page.
151-
152-
:::image type="content" source="./media/assign-roles-azure-service-principals/billing-account-id.png" alt-text="Screenshot showing Billing account ID." lightbox="./media/assign-roles-azure-service-principals/billing-account-id.png" :::
153-
154-
- `billingRoleAssignmentName`: This parameter is a unique GUID that you need to provide. You can generate a GUID using the [New-Guid](/powershell/module/microsoft.powershell.utility/new-guid) PowerShell command. You can also use the [Online GUID / UUID Generator](https://guidgenerator.com/) website to generate a unique GUID.
155-
156-
- `departmentName`: This parameter is the department ID. You can see department IDs in the Azure portal on the **Cost Management + Billing** > **Departments** page.
157-
158-
For this example, we used the ACE department. The ID for the example is `84819`.
159-
160-
:::image type="content" source="./media/assign-roles-azure-service-principals/department-id.png" alt-text="Screenshot showing an example department ID." lightbox="./media/assign-roles-azure-service-principals/department-id.png" :::
161-
162-
- `api-version`: Use the **2019-10-01-preview** version. Use the sample at [Enrollment Department Role Assignments - Put](/rest/api/billing/2019-10-01-preview/enrollment-department-role-assignments/put).
163-
164-
The request body has JSON code with three parameters that you need to use.
165-
166-
| Parameter | Where to find it |
167-
| --- | --- |
168-
| `properties.principalId` | It's the value of Object ID. See [Find your service principal and tenant IDs](#find-your-service-principal-and-tenant-ids). |
169-
| `properties.principalTenantId` | See [Find your service principal and tenant IDs](#find-your-service-principal-and-tenant-ids). |
170-
| `properties.roleDefinitionId` | `/providers/Microsoft.Billing/billingAccounts/{BillingAccountName}/billingRoleDefinitions/db609904-a47f-4794-9be8-9bd86fbffd8a` |
171-
172-
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.
173-
174-
The billing role definition ID of `db609904-a47f-4794-9be8-9bd86fbffd8a` is for a department reader.
175-
176-
1. Select **Run** to start the command.
177-
178-
:::image type="content" source="./media/assign-roles-azure-service-principals/enrollment-department-role-assignments-put-try-it-run.png" alt-text="Screenshot showing an example Enrollment Department Role Assignments – Put REST Try It with example information ready to run." lightbox="./media/assign-roles-azure-service-principals/enrollment-department-role-assignments-put-try-it-run.png" :::
179-
180-
A `200 OK` response shows that the service principal was successfully added.
181-
182-
Now you can use the service principal to automatically access EA APIs. The service principal has the DepartmentReader role.
183-
184-
## Assign the subscription creator role to the service principal
185-
186-
1. Read the [Enrollment Account Role Assignments - Put](/rest/api/billing/2019-10-01-preview/enrollment-account-role-assignments/put) article. While you read it, select **Try It** to assign the subscription creator role to the service principal.
187-
188-
:::image type="content" source="./media/assign-roles-azure-service-principals/enrollment-department-role-assignments-put-try-it.png" alt-text="Screenshot showing the Try It option in the Enrollment Account Role Assignments Put article." lightbox="./media/assign-roles-azure-service-principals/enrollment-department-role-assignments-put-try-it.png" :::
189-
190-
1. Use your account credentials to sign in to the tenant with the enrollment access that you want to assign.
191-
192-
1. Provide the following parameters as part of the API request. Read the article at [Enrollment Account Role Assignments - Put - URI Parameters](/rest/api/billing/2019-10-01-preview/enrollment-account-role-assignments/put#uri-parameters).
193-
194-
- `billingAccountName`: This parameter is the **Billing account ID**. You can find it in the Azure portal on the **Cost Management + Billing overview** page.
195-
196-
:::image type="content" source="./media/assign-roles-azure-service-principals/billing-account-id.png" alt-text="Screenshot showing the Billing account ID." lightbox="./media/assign-roles-azure-service-principals/billing-account-id.png" :::
197-
198-
- `billingRoleAssignmentName`: This parameter is a unique GUID that you need to provide. You can generate a GUID using the [New-Guid](/powershell/module/microsoft.powershell.utility/new-guid) PowerShell command. You can also use the [Online GUID/UUID Generator](https://guidgenerator.com/) website to generate a unique GUID.
199-
200-
- `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.
201-
202-
For this example, we used the `GTM Test Account`. The ID is `196987`.
203-
204-
:::image type="content" source="./media/assign-roles-azure-service-principals/account-id.png" alt-text="Screenshot showing the account ID." lightbox="./media/assign-roles-azure-service-principals/account-id.png" :::
205-
206-
- `api-version`: Use the **2019-10-01-preview** version. Use the sample at [Enrollment Department Role Assignments - Put - Examples](/rest/api/billing/2019-10-01-preview/enrollment-department-role-assignments/put#examples).
207-
208-
The request body has JSON code with three parameters that you need to use.
209-
210-
| Parameter | Where to find it |
211-
| --- | --- |
212-
| `properties.principalId` | It's the value of Object ID. See [Find your service principal and tenant IDs](#find-your-service-principal-and-tenant-ids). |
213-
| `properties.principalTenantId` | See [Find your service principal and tenant IDs](#find-your-service-principal-and-tenant-ids). |
214-
| `properties.roleDefinitionId` | `/providers/Microsoft.Billing/billingAccounts/{BillingAccountID}/enrollmentAccounts/{enrollmentAccountID}/billingRoleDefinitions/a0bcee42-bf30-4d1b-926a-48d21664ef71` |
215-
216-
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.
217-
218-
The billing role definition ID of `a0bcee42-bf30-4d1b-926a-48d21664ef71` is for the subscription creator role.
219-
220-
1. Select **Run** to start the command.
221-
222-
:::image type="content" source="./media/assign-roles-azure-service-principals/enrollment-account-role-assignments-put-try-it.png" alt-text="Screenshot showing the Try It option in the Enrollment Account Role Assignments - Put article." lightbox="./media/assign-roles-azure-service-principals/enrollment-account-role-assignments-put-try-it.png" :::
223-
224-
A `200 OK` response shows that the service principal was successfully added.
225-
226-
Now you can use the service principal to automatically access EA APIs. The service principal has the SubscriptionCreator role.
94+
## Assign a role to the service principal
95+
96+
Follow these steps to assign any of the supported roles to a service principal:
97+
98+
1. Use the appropriate **Role Assignments Put REST API** and select **Try it**. Find the correct API to use in the table below.
99+
:::image type="content" source="./media/assign-roles-azure-service-principals/put-try-it.png" alt-text="Screenshot showing the Try It option in the Put article." lightbox="./media/assign-roles-azure-service-principals/put-try-it.png" :::
100+
2. Sign in to the tenant with the required access.
101+
3. Provide the following parameters in your API request:
102+
- `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.
103+
104+
:::image type="content" source="./media/assign-roles-azure-service-principals/billing-account-id.png" alt-text="Screenshot showing Billing account ID." lightbox="./media/assign-roles-azure-service-principals/billing-account-id.png" :::
105+
106+
- `billingRoleAssignmentName`: A unique GUID you generate (see [New-Guid](/powershell/module/microsoft.powershell.utility/new-guid)).
107+
- `api-version`: Use `2019-10-01-preview` unless otherwise noted.
108+
- Request body parameters:
109+
- `properties.principalId`: The Object ID of the service principal.
110+
- `properties.principalTenantId`: The tenant ID.
111+
- `properties.roleDefinitionId`: Use the value from the table below.
112+
113+
| Role | Required user role to assign | Role definition ID | API Reference | Notes |
114+
|-----------------------|-----------------------------|---------------------------------------------|------------------------------------------------------------------------------|-----------------------------------------------------------------------|
115+
| EnrollmentReader | Enrollment writer | 24f8edb6-1668-4659-b5e2-40bb5f3a7d7e | [Role Assignments - Put](/rest/api/billing/2019-10-01-preview/role-assignments/put) | |
116+
| EA purchaser | Enrollment writer | da6647fb-7651-49ee-be91-c43c4877f0c4 | [Role Assignments - Put](/rest/api/billing/2019-10-01-preview/role-assignments/put) | |
117+
| DepartmentReader | Enrollment writer or department writer | db609904-a47f-4794-9be8-9bd86fbffd8a | [Enrollment Department Role Assignments - Put](/rest/api/billing/2019-10-01-preview/enrollment-department-role-assignments/put) | Use departmentName parameter. |
118+
| SubscriptionCreator | Enrollment account owner (EA admin) | a0bcee42-bf30-4d1b-926a-48d21664ef71 | [Enrollment Account Role Assignments - Put](/rest/api/billing/2019-10-01-preview/enrollment-account-role-assignments/put) | Use enrollmentAccountName parameter. |
119+
| Partner Admin Reader | Partner Administrator | 4f6144c0-a809-4c55-b3c8-7f9b7b15a1bf | [Role Assignments - Put](/rest/api/billing/2019-10-01-preview/role-assignments/put) | Use `pcn.{PCN}` for billingAccountName. |
120+
121+
1. Select **Run** to execute the command.
122+
123+
:::image type="content" source="./media/assign-roles-azure-service-principals/roleassignments-put-try-it-run.png" alt-text="Screenshot showing an example role assignment with example information that is ready to run." lightbox="./media/assign-roles-azure-service-principals/roleassignments-put-try-it-run.png" :::
124+
125+
5. A `200 OK` response means the service principal was successfully assigned the role.
227126

228127
## Verify service principal role assignments
229128

0 commit comments

Comments
 (0)