Esercitazione: Assegnare ruoli alle entità servizio (anteprima)

[Questo articolo è una documentazione preliminare soggetta a modifiche].

Il controllo degli accessi in base al ruolo in Power Platform consente agli amministratori di assegnare ruoli predefiniti a utenti, gruppi ed entità servizio nel tenant, nel gruppo di ambiente o nell'ambito dell'ambiente. Questa esercitazione illustra uno scenario di automazione comune: assegnazione del ruolo Collaboratore a un'entità servizio nell'ambito del tenant usando l'API di autorizzazione.

Per altre informazioni sui concetti relativi al controllo degli accessi in base al ruolo, sui ruoli predefiniti e sull'ereditarietà dell'ambito, vedere Controllo degli accessi in base al ruolo per l'interfaccia di amministrazione di Power Platform.

Importante

• Si tratta di una funzionalità di anteprima.
• Le funzionalità di anteprima non sono destinate ad essere utilizzate per la produzione e sono soggette a restrizioni. Queste funzionalità sono soggette a condizioni per l'utilizzo supplementari e sono disponibili prima di una versione ufficiale in modo che i clienti possano ottenere l'accesso iniziale e fornire feedback.

In questa esercitazione si imparerà a:

• Eseguire l'autenticazione con l'API Power Platform.
• Elencare le definizioni di ruolo disponibili.
• Creare un'assegnazione di ruolo per un'entità servizio nell'ambito del tenant.
• Verificare l'assegnazione di ruolo.

Prerequisiti

• Registrazione dell'app Microsoft Entra configurata per l'API Power Platform, con un certificato o un segreto client per l'autenticazione dell'entità servizio. Per indicazioni, vedere Autenticazione.
• ID oggetto applicazione organizzazione per l'entità servizio (disponibile nelle applicazioni Microsoft Entra ID>Enterprise).
• L'identità chiamante deve avere il ruolo di amministratore di Power Platform o amministratore del controllo degli accessi in base al ruolo di Power Platform .

Definizioni di ruolo predefinite

Power Platform offre quattro ruoli predefiniti che possono essere assegnati tramite il controllo degli accessi in base al ruolo. Ogni ruolo ha un set fisso di autorizzazioni e può essere assegnato nell'ambito del tenant, del gruppo di ambiente o dell'ambiente.

Nome ruolo	ID ruolo	Autorizzazioni
Proprietario di Power Platform	0cb07c69-1631-4725-ab35-e59e001c51ea	Tutte le autorizzazioni
Collaboratore di Power Platform	ff954d61-a89a-4fbe-ace9-01c367b89f87	Gestire e leggere tutte le risorse, ma non è possibile apportare o modificare le assegnazioni di ruolo
Lettore di Power Platform	c886ad2e-27f7-4874-8381-5849b8d8a090	Accesso in sola lettura a tutte le risorse
Amministratore del controllo degli accessi basato sui ruoli di Power Platform	95e94555-018c-447b-8691-bdac8e12211e	Leggere tutte le risorse e gestire le assegnazioni di ruolo

Passaggio 1: Elencare le definizioni dei ruoli disponibili

Prima di tutto, autenticare e recuperare le definizioni di ruolo disponibili per confermare l'ID ruolo collaboratore.

PowerShell

# Install the Az.Accounts module if not already installed
Install-Module -Name Az.Accounts

# Set your tenant ID
$TenantId = "YOUR_TENANT_ID"

# Authenticate and obtain an access token
Connect-AzAccount
$AccessToken = Get-AzAccessToken -TenantId $TenantId -ResourceUrl "https://api.powerplatform.com/"

$headers = @{ 'Authorization' = 'Bearer ' + $AccessToken.Token }
$headers.Add('Content-Type', 'application/json')

# List all role definitions
$roleDefinitions = Invoke-RestMethod -Method Get -Uri "https://api.powerplatform.com/authorization/roleDefinitions?api-version=2024-10-01" -Headers $headers

$roleDefinitions.value | Format-Table roleDefinitionName, roleDefinitionId

Output previsto:

roleDefinitionName                                          roleDefinitionId
------------------                                          ----------------
Power Platform owner                                        0cb07c69-1631-4725-ab35-e59e001c51ea
Power Platform contributor                                  ff954d61-a89a-4fbe-ace9-01c367b89f87
Power Platform reader                                       c886ad2e-27f7-4874-8381-5849b8d8a090
Power Platform role-based access control administrator      95e94555-018c-447b-8691-bdac8e12211e

C#

using Microsoft.PowerPlatform.Management;
using Microsoft.PowerPlatform.Management.Models;

var client = ServiceClientFactory.Create(clientId);

// List all role definitions
var roleDefinitions = await client.Authorization.RoleDefinitions.GetAsync();

foreach (var role in roleDefinitions.Value)
{
    Console.WriteLine($"{role.RoleDefinitionName}: {role.RoleDefinitionId}");
}

Output previsto:

Power Platform owner: 0cb07c69-1631-4725-ab35-e59e001c51ea
Power Platform contributor: ff954d61-a89a-4fbe-ace9-01c367b89f87
Power Platform reader: c886ad2e-27f7-4874-8381-5849b8d8a090
Power Platform role-based access control administrator: 95e94555-018c-447b-8691-bdac8e12211e

Python

import asyncio
from azure.identity import InteractiveBrowserCredential
from kiota_authentication_azure.azure_identity_authentication_provider import AzureIdentityAuthenticationProvider
from kiota_http.httpx_request_adapter import HttpxRequestAdapter
from mspp_management.service_client_base import ServiceClientBase

credential = InteractiveBrowserCredential()
auth_provider = AzureIdentityAuthenticationProvider(
    credential,
    scopes=["https://api.powerplatform.com/.default"]
)
adapter = HttpxRequestAdapter(auth_provider)
adapter.base_url = "https://api.powerplatform.com"
client = ServiceClientBase(adapter)

# List all role definitions
role_definitions = await client.authorization.role_definitions.get()

for role in role_definitions.value:
    print(f"{role.role_definition_name}: {role.role_definition_id}")

Output previsto:

Power Platform owner: 0cb07c69-1631-4725-ab35-e59e001c51ea
Power Platform contributor: ff954d61-a89a-4fbe-ace9-01c367b89f87
Power Platform reader: c886ad2e-27f7-4874-8381-5849b8d8a090
Power Platform role-based access control administrator: 95e94555-018c-447b-8691-bdac8e12211e

Informazioni di riferimento sulle API power platform: controllo di accessoRole-Based - Elencare le definizioni dei ruoli

Passaggio 2. Assegnare il ruolo Collaboratore a un'entità servizio

Creare un'assegnazione di ruolo che concede il ruolo di collaboratore di Power Platform a un'entità servizio nell'ambito del tenant. Sostituire YOUR_TENANT_ID con il GUID del tenant e YOUR_ENTERPRISE_APP_OBJECT_ID con l'ID oggetto applicazione dell'organizzazione dall'ID Microsoft Entra.

PowerShell

$TenantId = "YOUR_TENANT_ID"
$EnterpriseAppObjectId = "YOUR_ENTERPRISE_APP_OBJECT_ID"

$body = @{
    roleDefinitionId = "ff954d61-a89a-4fbe-ace9-01c367b89f87"
    principalObjectId = $EnterpriseAppObjectId
    principalType = "ApplicationUser"
    scope = "/tenants/$TenantId"
} | ConvertTo-Json

$roleAssignment = Invoke-RestMethod -Method Post -Uri "https://api.powerplatform.com/authorization/roleAssignments?api-version=2024-10-01" -Headers $headers -Body $body

$roleAssignment

Output previsto:

roleAssignmentId   : a1b2c3d4-e5f6-7890-abcd-ef1234567890
principalObjectId  : <your-enterprise-app-object-id>
roleDefinitionId   : ff954d61-a89a-4fbe-ace9-01c367b89f87
scope              : /tenants/<your-tenant-id>
principalType      : ApplicationUser
createdOn          : 2026-03-02T12:00:00.0000000+00:00

C#

var request = new RoleAssignmentRequest
{
    RoleDefinitionId = "ff954d61-a89a-4fbe-ace9-01c367b89f87",
    PrincipalObjectId = "YOUR_ENTERPRISE_APP_OBJECT_ID",
    PrincipalType = "ApplicationUser",
    Scope = "/tenants/YOUR_TENANT_ID"
};

var roleAssignment = await client.Authorization.RoleAssignments.PostAsync(request);

Console.WriteLine($"Assignment ID: {roleAssignment.Value[0].RoleAssignmentId}");
Console.WriteLine($"Scope: {roleAssignment.Value[0].Scope}");
Console.WriteLine($"Principal: {roleAssignment.Value[0].PrincipalObjectId}");

Python

from mspp_management.models.role_assignment_request import RoleAssignmentRequest

request = RoleAssignmentRequest(
    role_definition_id="ff954d61-a89a-4fbe-ace9-01c367b89f87",
    principal_object_id="YOUR_ENTERPRISE_APP_OBJECT_ID",
    principal_type="ApplicationUser",
    scope="/tenants/YOUR_TENANT_ID",
)

role_assignment = await client.authorization.role_assignments.post(request)

print(f"Assignment ID: {role_assignment.value[0].role_assignment_id}")
print(f"Scope: {role_assignment.value[0].scope}")
print(f"Principal: {role_assignment.value[0].principal_object_id}")

Informazioni di riferimento sulle API power platform: controllo di accessoRole-Based - Creare un'assegnazione di ruolo

Passaggio 3. Verificare l'assegnazione di ruolo

Recuperare tutte le assegnazioni di ruolo per verificare che la nuova assegnazione esista.

PowerShell

$roleAssignments = Invoke-RestMethod -Method Get -Uri "https://api.powerplatform.com/authorization/roleAssignments?api-version=2024-10-01" -Headers $headers

# Filter for the service principal's assignments
$roleAssignments.value | Where-Object { $_.principalObjectId -eq $EnterpriseAppObjectId } | Format-Table roleAssignmentId, roleDefinitionId, scope, principalType

Output previsto:

roleAssignmentId                        roleDefinitionId                        scope                          principalType
----------------                        ----------------                        -----                          -------------
a1b2c3d4-e5f6-7890-abcd-ef1234567890    ff954d61-a89a-4fbe-ace9-01c367b89f87    /tenants/<your-tenant-id>      ApplicationUser

C#

var roleAssignments = await client.Authorization.RoleAssignments.GetAsync();

var myAssignments = roleAssignments.Value
    .Where(a => a.PrincipalObjectId == "YOUR_ENTERPRISE_APP_OBJECT_ID");

foreach (var assignment in myAssignments)
{
    Console.WriteLine($"ID: {assignment.RoleAssignmentId}");
    Console.WriteLine($"Role: {assignment.RoleDefinitionId}");
    Console.WriteLine($"Scope: {assignment.Scope}");
    Console.WriteLine($"Type: {assignment.PrincipalType}");
}

Python

role_assignments = await client.authorization.role_assignments.get()

my_assignments = [
    a for a in role_assignments.value
    if a.principal_object_id == "YOUR_ENTERPRISE_APP_OBJECT_ID"
]

for assignment in my_assignments:
    print(f"ID: {assignment.role_assignment_id}")
    print(f"Role: {assignment.role_definition_id}")
    print(f"Scope: {assignment.scope}")
    print(f"Type: {assignment.principal_type}")

Informazioni di riferimento sull'API Power Platform: Controllo degli accessi in base al ruolo - Elencare le assegnazioni di ruolo

Contenuti correlati

• Controllo degli accessi in base al ruolo per l'interfaccia di amministrazione di Power Platform
• Informazioni di riferimento sulle autorizzazioni
• Autenticazione: creare la prima registrazione dell'app