Tutorial: Menetapkan peran ke prinsipal layanan (pratinjau)

[Artikel ini adalah dokumentasi prarilis dan dapat berubah.]

Kontrol akses berbasis peran (RBAC) di Power Platform memungkinkan administrator menetapkan peran bawaan untuk pengguna, grup, dan perwakilan layanan di cakupan penyewa, grup lingkungan, atau lingkungan. Tutorial ini menjelaskan skenario otomatisasi umum: menetapkan peran Kontributor ke perwakilan layanan di cakupan penyewa menggunakan API Otorisasi.

Untuk mempelajari selengkapnya tentang konsep RBAC, peran bawaan, dan pewarisan cakupan, lihat Kontrol akses berbasis peran untuk pusat admin Power Platform.

Important

• Ini adalah fitur pratinjau.
• Fitur pratinjau tidak dimaksudkan untuk digunakan dalam produksi dan fungsinya mungkin terbatas. Fitur-fitur ini tunduk pada ketentuan penggunaan tambahan, dan tersedia sebelum rilis resmi sehingga pelanggan dapat memperoleh akses awal dan memberikan umpan balik.

Dalam tutorial ini, Anda akan belajar untuk:

• Autentikasi dengan API Power Platform.
• Mencantumkan definisi peran yang tersedia.
• Buat penetapan peran untuk perwakilan layanan di cakupan penyewa.
• Verifikasi penetapan peran.

Prasyarat

• Pendaftaran aplikasi Microsoft Entra yang dikonfigurasi untuk API Power Platform, dengan sertifikat atau rahasia klien untuk autentikasi perwakilan layanan. Untuk panduan, lihat Autentikasi.
• ID Objek Aplikasi Perusahaan untuk perwakilan layanan (ditemukan di aplikasi Microsoft Entra ID>Enterprise).
• Identitas panggilan harus memiliki peran Administrator Power Platform atau administrator kontrol akses berbasis peran Power Platform .

Definisi peran bawaan

Power Platform menyediakan empat peran bawaan yang dapat ditetapkan melalui RBAC. Setiap peran memiliki serangkaian izin tetap dan dapat ditetapkan di penyewa, grup lingkungan, atau cakupan lingkungan.

Nama peran	ID Peran	Permissions
Pemilik Power Platform	0cb07c69-1631-4725-ab35-e59e001c51ea	Semua izin
Kontributor Power Platform	ff954d61-a89a-4fbe-ace9-01c367b89f87	Mengelola dan membaca semua sumber daya, tetapi tidak dapat membuat atau mengubah penetapan peran
Pembaca Power Platform	c886ad2e-27f7-4874-8381-5849b8d8a090	Akses baca-saja ke semua sumber daya
Administrator kontrol akses berbasis peran Power Platform	95e94555-018c-447b-8691-bdac8e12211e	Membaca semua sumber daya + mengelola penetapan peran

Langkah 1. Mencantumkan definisi peran yang tersedia

Pertama, autentikasi dan ambil definisi peran yang tersedia untuk mengonfirmasi ID peran kontributor.

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 yang diharapkan:

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 yang diharapkan:

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 yang diharapkan:

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

Referensi API Power Platform: Role-Based Access Control - Definisi Peran Daftar

Langkah 2. Menetapkan peran Kontributor ke perwakilan layanan

Buat penetapan peran yang memberikan peran kontributor Power Platform kepada perwakilan layanan di cakupan penyewa. Ganti YOUR_TENANT_ID dengan GUID penyewa Anda dan YOUR_ENTERPRISE_APP_OBJECT_ID dengan ID objek aplikasi perusahaan dari 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 yang diharapkan:

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}")

Referensi API Power Platform: Role-Based Access Control - Membuat Penetapan Peran

Langkah 3. Memverifikasi penetapan peran

Ambil semua penetapan peran untuk mengonfirmasi adanya tugas baru.

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 yang diharapkan:

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}")

Referensi API Power Platform: Kontrol Akses Berbasis Peran - Mencantumkan Penetapan Peran

Konten terkait

• Kontrol akses berbasis peran untuk pusat admin Power Platform
• Referensi izin
• Autentikasi - buat pendaftaran aplikasi pertama Anda