Authentication

Artikel ini memberikan gambaran umum tentang penyiapan Microsoft Entra untuk memanggil Power Platform API. Untuk mengakses sumber daya yang tersedia melalui Power Platform API, Anda harus mendapatkan token pembawa dari Microsoft Entra dan mengirimkannya sebagai header bersama dengan setiap permintaan. Bergantung pada jenis identitas yang Anda dukung (pengguna vs. perwakilan layanan) ada alur yang berbeda untuk mendapatkan token pembawa ini, seperti yang dijelaskan dalam artikel ini.

Untuk mendapatkan token pembawa dengan izin yang benar, selesaikan langkah-langkah berikut:

1. Membuat pendaftaran aplikasi di penyewa Microsoft Entra Anda
2. Mengonfigurasi izin API
3. Mengonfigurasi platform dan mengalihkan URI
4. (Opsional) Mengonfigurasi sertifikat dan rahasia
5. Meminta token akses

Langkah 1. Membuat pendaftaran aplikasi di penyewa Anda Microsoft Entra

1. Buka portal Azure.
2. Pilih ID Microsoft Entra di bagian atas halaman. Lalu pilih + Tambahkan>Pendaftaran aplikasi.
3. Isi halaman Daftarkan aplikasi :
   1. Nama — Beri aplikasi nama yang dapat dikenali, seperti Power Platform Admin SDK.
   2. Jenis akun yang didukung — Pilih Penyewa tunggal saja - <nama> perusahaan Anda.
   3. URI Pengalihan — Lewati ini untuk saat ini. Anda mengonfigurasinya di Langkah 3.
4. Pilih Daftar untuk membuat aplikasi. Setelah pendaftaran selesai, perhatikan ID Aplikasi (klien) dan ID Direktori (penyewa) dari halaman gambaran umum — Anda memerlukan kedua nilai nanti.

Anda juga dapat membuat pendaftaran dengan menggunakan Azure CLI:

az login

az ad app create --display-name "Power Platform Admin SDK" --sign-in-audience AzureADMyOrg

Perintah mengembalikan objek JSON. Perhatikan nilainya appId — nilai ini adalah ID klien Anda.

Langkah 2. Mengonfigurasikan izin API

Di pendaftaran aplikasi baru Anda, buka tab Kelola - Izin API . Di bawah bagian Konfigurasikan izin , pilih Tambahkan Izin. Dalam kotak dialog, pilih tab API yang digunakan organisasi saya , lalu cari Power Platform API. Anda mungkin melihat beberapa entri dengan nama yang mirip dengan ini, jadi pastikan Anda menggunakan yang dengan GUID 8578e004-a5c6-46e7-913e-12f58912df43.

Jika Anda tidak melihat Api Power Platform ditampilkan dalam daftar saat mencari berdasarkan GUID, Anda mungkin masih memiliki akses ke dalamnya tetapi visibilitas tidak di-refresh. Untuk memaksa refresh, jalankan skrip berikut:

PowerShell

#Install the Microsoft Graph PowerShell SDK module
Install-Module Microsoft.Graph -Scope CurrentUser -Repository PSGallery -Force

Connect-MgGraph
New-MgServicePrincipal -AppId 8578e004-a5c6-46e7-913e-12f58912df43 -DisplayName "Power Platform API"

Azure CLI

az login

az ad sp create --id 8578e004-a5c6-46e7-913e-12f58912df43

Dari sini, pilih izin yang Anda butuhkan. Izin ini dikelompokkan menurut Namespace. Dalam namespace, Anda akan melihat jenis dan tindakan sumber daya, seperti AppManagement.ApplicationPackages.Read, yang memberikan izin baca untuk paket aplikasi. Untuk informasi selengkapnya, lihat artikel Referensi izin .

Note

Power Platform API hanya menggunakan izin yang didelegasikan saat ini. Untuk aplikasi yang berjalan dengan konteks pengguna, minta izin yang didelegasikan dengan menggunakan parameter cakupan . Izin ini mendelegasikan hak istimewa pengguna yang masuk ke aplikasi Anda, sehingga dapat bertindak sebagai pengguna saat memanggil titik akhir API Power Platform.

Untuk identitas perwakilan layanan, jangan gunakan izin aplikasi. Sebagai gantinya, setelah Anda membuat pendaftaran aplikasi, tetapkan peran RBAC untuk memberikan izin tercakup (seperti Kontributor atau Pembaca). Untuk informasi selengkapnya, lihat Tutorial: Menetapkan peran RBAC ke perwakilan layanan.

Setelah Anda menambahkan izin yang diperlukan ke aplikasi, pilih Berikan persetujuan admin untuk menyelesaikan penyiapan. Dengan memberikan persetujuan admin, Anda mengotorisasi izin untuk semua pengguna di penyewa sehingga mereka tidak diminta dengan dialog persetujuan interaktif saat pertama kali mereka menggunakan aplikasi Anda. Jika Anda lebih suka persetujuan interaktif per pengguna, ikuti platform identitas Microsoft dan alur kode otorisasi OAuth 2.0.

Anda juga dapat memberikan persetujuan admin dengan menggunakan Azure CLI:

# Replace <app-id> with your application (client) ID
az ad app permission admin-consent --id <app-id>

Langkah 3. Mengonfigurasi platform dan mengalihkan URI

SDK, skrip PowerShell, dan aplikasi desktop yang mengautentikasi atas nama pengguna memerlukan URI pengalihan sehingga Microsoft Entra dapat mengembalikan token kembali ke aplikasi Anda setelah autentikasi.

1. Dalam pendaftaran aplikasi Anda, buka Kelola - Autentikasi.

2. Pilih Tambahkan URI Pengalihan, lalu pilih Aplikasi seluler dan desktop.

3. Pilih URI pengalihan bawaan berikut:

   https://login.microsoftonline.com/common/oauth2/nativeclient

4. Pilih Konfigurasikan untuk menyimpan.

Anda juga dapat menambahkan URI pengalihan dengan menggunakan Azure CLI:

# Replace <app-id> with your application (client) ID
az ad app update --id <app-id> --public-client-redirect-uris https://login.microsoftonline.com/common/oauth2/nativeclient

Pengaturan klien publik

Di bawah bagian Pengaturan tingkat lanjut pada tab Autentikasi yang sama, ada tombol Izinkan alur klien publik . Atur pengalih ini ke Ya hanya jika Anda berencana untuk menggunakan alur Info Masuk Kata Sandi Pemilik Sumber Daya (ROPC), yang mengirim nama pengguna dan kata sandi langsung di isi permintaan token.

Alur ini tidak berfungsi untuk akun yang mengaktifkan autentikasi multifaktor. Untuk alur browser interaktif atau kode perangkat, Anda tidak perlu mengaktifkan pengaturan ini.

Langkah 4. (Opsional) Mengonfigurasi sertifikat dan rahasia

Jika aplikasi Anda memerlukan pembacaan dan penulisan sumber daya sebagai dirinya sendiri, juga dikenal sebagai perwakilan layanan, ada dua cara untuk mengautentikasi. Untuk menggunakan sertifikat, buka Kelola - Sertifikat dan rahasia. Di bawah bagian Sertifikat , unggah sertifikat x509 yang bisa Anda gunakan untuk mengautentikasi.

Cara lainnya adalah menggunakan bagian Rahasia untuk membuat rahasia klien. Simpan rahasia di lokasi yang aman untuk digunakan dengan kebutuhan otomatisasi Anda. Opsi sertifikat atau rahasia memungkinkan Anda mengautentikasi dengan Microsoft Entra dan menerima token untuk klien ini, yang Anda teruskan ke REST API atau cmdlet PowerShell.

Langkah 5. Meminta token akses

Anda dapat memperoleh token pembawa akses dengan dua cara: salah satu caranya adalah untuk nama pengguna dan kata sandi, dan cara lainnya adalah untuk perwakilan layanan.

Alur nama pengguna dan kata sandi

Pastikan untuk membaca bagian klien publik. Kemudian, kirim permintaan POST melalui HTTP ke Microsoft Entra ID dengan muatan nama pengguna dan kata sandi.

Content-Type: application/x-www-form-urlencoded
Host: login.microsoftonline.com
Accept: application/json
POST https://login.microsoftonline.com/YOUR_TENANT.COM/oauth2/v2.0/token
BODY:
client_id={CLIENT_ID_FROM_AZURE_CLIENT_APP}&scope=https://api.powerplatform.com/.default&username={USER_EMAIL_ADDRESS}&password={PASSWORD}&grant_type=password

Contoh sebelumnya berisi tempat penampung yang dapat Anda ambil dari aplikasi klien Anda di ID Microsoft Entra. Anda menerima respons yang dapat Anda gunakan untuk melakukan panggilan berikutnya ke Power Platform API.

{
  "token_type": "Bearer",
  "scope": "https://api.powerplatform.com/AppManagement.ApplicationPackages.Install https://api.powerplatform.com/AppManagement.ApplicationPackages.Read https://api.powerplatform.com/.default",
  "expires_in": 4747,
  "ext_expires_in": 4747,
  "access_token": "eyJ0eXAiOiJKV1QiLCJu..."
}

Gunakan nilai access_token dalam panggilan berikutnya ke API Power Platform dengan header HTTP Autorisasi.

Alur perwakilan layanan

Pastikan untuk membaca bagian Konfigurasikan sertifikat dan rahasia . Kemudian, kirim permintaan POST melalui HTTP ke Microsoft Entra ID dengan payload rahasia klien. Metode autentikasi ini sering disebut sebagai autentikasi perwakilan layanan.

Important

Sebelum menggunakan autentikasi perwakilan layanan, selesaikan Langkah 1-4 sebelumnya dalam artikel ini untuk membuat dan mengonfigurasi pendaftaran aplikasi Anda dengan sertifikat atau rahasia klien. Kemudian tetapkan perwakilan layanan peran RBAC untuk mengontrol tingkat aksesnya. Untuk mempelajari lebih lanjut, lihat Tutorial: Menetapkan peran RBAC ke perwakilan layanan.

Content-Type: application/x-www-form-urlencoded
Host: login.microsoftonline.com
Accept: application/json
POST https://login.microsoftonline.com/YOUR_TENANT.COM/oauth2/v2.0/token
BODY:
client_id={CLIENT_ID_FROM_AZURE_CLIENT_APP}&scope=https://api.powerplatform.com/.default&client_secret={SECRET_FROM_AZURE_CLIENT_APP}&grant_type=client_credentials

Contoh sebelumnya berisi tempat penampung yang dapat Anda ambil dari aplikasi klien Anda di ID Microsoft Entra. Anda menerima respons yang dapat Anda gunakan untuk melakukan panggilan berikutnya ke Power Platform API.

{
  "token_type": "Bearer",
  "expires_in": 3599,
  "ext_expires_in": 3599,
  "access_token": "eyJ0eXAiOiJKV1..."
}

Gunakan nilai access_token dalam panggilan berikutnya ke API Power Platform dengan header HTTP Autorisasi. Izin efektif perwakilan layanan ditentukan oleh peran RBAC yang ditetapkan untuknya. Untuk mempelajari cara menetapkan peran, lihat Tutorial: Menetapkan peran RBAC ke perwakilan layanan.

Mulai cepat dengan Azure CLI

Skrip berikut membuat pendaftaran aplikasi secara end-to-end. Jalankan setiap perintah secara berurutan dan ganti nilai tempat penampung dengan nilai Anda sendiri.

# Sign in to Azure CLI
az login

# Create the app registration (single tenant)
az ad app create --display-name "Power Platform Admin SDK" --sign-in-audience AzureADMyOrg

# Save the app ID from the output, then create a service principal for it
az ad sp create --id <app-id>

# Add a delegated permission (example: AppManagement.ApplicationPackages.Read)
# The --api value is the Power Platform API app ID.
# The --api-permissions value is the permission ID and type (Scope = delegated).
# Repeat this command for each permission you need. See the Permission reference for IDs.
az ad app permission add --id <app-id> \
  --api 8578e004-a5c6-46e7-913e-12f58912df43 \
  --api-permissions <permission-id>=Scope

# Grant admin consent so users aren't prompted individually
az ad app permission admin-consent --id <app-id>

# Add the native client redirect URI for interactive auth
az ad app update --id <app-id> \
  --public-client-redirect-uris https://login.microsoftonline.com/common/oauth2/nativeclient

Setelah menjalankan perintah ini, Anda dapat menggunakan pendaftaran aplikasi dengan panggilan SDK, PowerShell, atau REST langsung. Untuk mencari ID izin untuk --api-permissions parameter, lihat Referensi izin.

Pemecahan masalah umum

Kesalahan "Persetujuan diperlukan" atau "perlu persetujuan admin"

Kesalahan ini terjadi ketika admin belum menyetujui izin API pada pendaftaran aplikasi Anda. Buka Pendaftaran> aplikasi > aplikasi Anda dan pilih Berikan persetujuan admin.

Atau, jalankan:

az ad app permission admin-consent --id <app-id>

Kesalahan "Pengguna tidak ditetapkan ke peran untuk aplikasi"

Kesalahan ini berarti aplikasi perusahaan yang terkait dengan pendaftaran aplikasi Anda memiliki Penetapan pengguna yang diperlukan diatur ke Ya. Ketika pengaturan ini diaktifkan, hanya pengguna atau grup yang secara eksplisit ditetapkan ke aplikasi yang dapat masuk. Untuk memperbaiki kesalahan ini, lakukan salah satu tindakan berikut:

• BukaAplikasi>Microsoft Entra ID> Enterprise > aplikasi Anda dan atur Penugasan yang diperlukan ke Tidak.
• Tambahkan pengguna atau grup keamanan yang relevan di bawah Pengguna dan grup.

Kebijakan akses bersyarah memblokir akses

Jika organisasi Anda menerapkan kebijakan akses bersyarat, mereka mungkin memblokir akuisisi token untuk pendaftaran aplikasi Anda. Penyebab umum termasuk persyaratan kepatuhan perangkat, pembatasan lokasi, atau kebijakan berbasis risiko. Bekerja sama dengan administrator Microsoft Entra Anda untuk mengecualikan pendaftaran aplikasi Anda dari kebijakan atau memastikan klien memenuhi persyaratan kebijakan.

"POWER Platform API" tidak ditemukan di pemilih API

Jika mencari Power Platform API berdasarkan nama atau GUID dalam dialog izin API tidak mengembalikan hasil, perwakilan layanan tidak dibuat di penyewa Anda. Ikuti langkah-langkah penyegaran paksa di Langkah 2 untuk membuatnya.

Mengautentikasi dengan SDK Power Platform dan PowerShell

Contoh berikut menunjukkan cara mengautentikasi dan melakukan panggilan API sampel dengan menggunakan setiap SDK dan PowerShell. Sebelum menjalankan contoh ini, selesaikan Langkah 1-3 sebelumnya dalam artikel ini untuk membuat dan mengonfigurasi pendaftaran aplikasi Anda.

Autentikasi interaktif (pengguna yang didelegasikan)

Autentikasi interaktif membuka jendela browser bagi pengguna untuk masuk. Alur ini berfungsi paling baik untuk skrip pengembang, alat admin, dan skenario apa pun tempat pengguna berada.

PowerShell

# Sign in interactively (opens a browser)
Connect-AzAccount

# Get an access token for the Power Platform API
$token = Get-AzAccessToken -ResourceUrl "https://api.powerplatform.com"

# Call the List Environments endpoint as an example
$headers = @{ Authorization = "Bearer $($token.Token)" }
$environments = Invoke-RestMethod -Uri "https://api.powerplatform.com/environmentmanagement/environments?api-version=2024-10-01" -Headers $headers
$environments.value | Format-Table name, properties.displayName

C# SDK

using Microsoft.PowerPlatform.Management;

// Create an interactive client — opens a browser for sign-in
var factory = new ServiceClientFactory();
var client = factory.Create("YOUR_CLIENT_ID");

// List environments as an example
var environments = await client.Environmentmanagement.Environments.GetAsync();
foreach (var env in environments.Value)
{
    Console.WriteLine($"{env.Name} - {env.Properties.DisplayName}");
}

Python SDK

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

async def main():
    # Create interactive browser credential
    credential = InteractiveBrowserCredential(client_id="YOUR_CLIENT_ID")

    # Wire up the Kiota request adapter
    auth_provider = AzureIdentityAuthenticationProvider(
        credentials=credential,
        scopes=["https://api.powerplatform.com/.default"]
    )
    adapter = HttpxRequestAdapter(authentication_provider=auth_provider)

    # Create the SDK client
    client = ServiceClientBase(adapter)

    # List environments as an example
    environments = await client.environmentmanagement.environments.get()
    for env in environments.value:
        print(f"{env.name} - {env.properties.display_name}")

asyncio.run(main())

Klien rahasia (perwakilan layanan)

Autentikasi klien rahasia menggunakan rahasia atau sertifikat klien dan tidak memerlukan interaksi pengguna. Alur autentikasi ini paling baik untuk layanan latar belakang, alur, dan otomatisasi.

Important

Sebelum menggunakan autentikasi perwakilan layanan, selesaikan Langkah 1-4 di atas untuk membuat dan mengonfigurasi pendaftaran aplikasi Anda dengan sertifikat atau rahasia klien. Kemudian tetapkan perwakilan layanan peran RBAC untuk mengontrol tingkat aksesnya. Untuk informasi selengkapnya, lihat Tutorial: Menetapkan peran RBAC ke perwakilan layanan.

PowerShell

$tenantId = "YOUR_TENANT_ID"
$clientId = "YOUR_CLIENT_ID"
$clientSecret = "YOUR_CLIENT_SECRET"

# Request a token using client credentials
$body = @{
    client_id     = $clientId
    scope         = "https://api.powerplatform.com/.default"
    client_secret = $clientSecret
    grant_type    = "client_credentials"
}
$tokenResponse = Invoke-RestMethod -Method Post `
    -Uri "https://login.microsoftonline.com/$tenantId/oauth2/v2.0/token" `
    -ContentType "application/x-www-form-urlencoded" `
    -Body $body

# Call the List Environments endpoint as an example
$headers = @{ Authorization = "Bearer $($tokenResponse.access_token)" }
$environments = Invoke-RestMethod -Uri "https://api.powerplatform.com/environmentmanagement/environments?api-version=2024-10-01" -Headers $headers
$environments.value | Format-Table name, properties.displayName

C# SDK

using Microsoft.PowerPlatform.Management;

// Create a confidential client with a client secret
var factory = new ServiceClientFactory();
var client = factory.CreateConfidential(
    "YOUR_TENANT_ID",
    "YOUR_CLIENT_ID",
    "YOUR_CLIENT_SECRET"
);

// List environments as an example
var environments = await client.Environmentmanagement.Environments.GetAsync();
foreach (var env in environments.Value)
{
    Console.WriteLine($"{env.Name} - {env.Properties.DisplayName}");
}

Python SDK

import asyncio
from azure.identity import ClientSecretCredential
from kiota_authentication_azure import AzureIdentityAuthenticationProvider
from kiota_http import HttpxRequestAdapter
from mspp_management import ServiceClientBase

async def main():
    # Create client secret credential
    credential = ClientSecretCredential(
        tenant_id="YOUR_TENANT_ID",
        client_id="YOUR_CLIENT_ID",
        client_secret="YOUR_CLIENT_SECRET"
    )

    # Wire up the Kiota request adapter
    auth_provider = AzureIdentityAuthenticationProvider(
        credentials=credential,
        scopes=["https://api.powerplatform.com/.default"]
    )
    adapter = HttpxRequestAdapter(authentication_provider=auth_provider)

    # Create the SDK client
    client = ServiceClientBase(adapter)

    # List environments as an example
    environments = await client.environmentmanagement.environments.get()
    for env in environments.value:
        print(f"{env.name} - {env.properties.display_name}")

asyncio.run(main())

Konten terkait

Tutorial: Menetapkan peran RBAC ke perwakilan layanan
Kontrol akses berbasis peran untuk pusat admin Power Platform
Referensi izin