Xác thực

Bài viết này cung cấp thông tin tổng quan về thiết lập Microsoft Entra để gọi API Power Platform. Để truy nhập các tài nguyên có sẵn thông qua API Power Platform, bạn phải nhận được mã thông báo người mang từ Microsoft Entra và gửi nó dưới dạng tiêu đề cùng với mỗi yêu cầu. Tùy thuộc vào loại định danh bạn đang hỗ trợ (người dùng so với tên dịch vụ chính) có các dòng khác nhau để có được mã thông báo người mang này, như được mô tả trong bài viết này.

Để có được mã thông báo người mang với các quyền phù hợp, hãy hoàn thành các bước sau đây:

Tạo đăng ký ứng dụng trong đối tượng thuê Microsoft Entra của bạn
Đặt cấu hình quyền API
Cấu hình nền tảng và chuyển hướng URI
(Tùy chọn) Cấu hình chứng chỉ và bí mật
Yêu cầu mã thông báo truy nhập

Bước 1. Tạo một đơn đăng ký ứng dụng trong Microsoft Entra người thuê nhà của bạn

Truy cập cổng thông tin Azure.
Chọn Microsoft Entra ID ở đầu trang. Sau đó chọn + Thêm Đăng>ký ứng dụng.
Điền vào trang Đăng ký ứng dụng:
1. Name — Đặt tên có thể nhận biết cho ứng dụng, chẳng hạn như SDK Quản trị Viên Nền tảng Nguồn.
2. Các loại tài khoản được hỗ trợ — Chọn Chỉ đối tượng thuê duy nhất - <tên công ty của bạn>.
3. Chuyển hướng URI — Bỏ qua bước này ngay bây giờ. Bạn đặt cấu hình trong Bước 3.
Chọn Đăng ký để tạo ứng dụng. Sau khi đăng ký hoàn tất, hãy lưu ý ID Ứng dụng (máy khách ) và ID Thư mục (đối tượng thuê) từ trang tổng quan — bạn cần cả hai giá trị sau này.

Bạn cũng có thể tạo đăng ký bằng cách sử dụng Azure CLI:

az login

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

Lệnh này trả về một đối tượng JSON. Lưu ý giá appId trị — giá trị này là ID máy khách của bạn.

Bước 2. Đặt cấu hình quyền API

Trong đăng ký ứng dụng mới của bạn, hãy đi tới tab Quản lý - Quyền API. Bên dưới phần Đặt cấu hình quyền, chọn Thêm Quyền. Trong hộp thoại, chọn tab API mà tổ chức của tôi sử dụng, rồi tìm kiếm API Nền tảng Power. Bạn có thể thấy một số mục nhập có tên tương tự như mục nhập này, vì vậy hãy đảm bảo bạn sử dụng cùng với GUID 8578e004-a5c6-46e7-913e-12f58912df43.

Nếu bạn không thấy API Nền tảng Power được hiển thị trong danh sách khi tìm kiếm bằng GUID, bạn vẫn có thể có quyền truy nhập vào đó nhưng khả năng hiển thị không được làm mới. Để bắt buộc làm mới, hãy chạy script sau đây:

PowerShell
dịch vụ Azure CLI

#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"

az login

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

Từ đây, chọn các quyền bạn cần. Các quyền này được nhóm theo Không gian tên. Trong không gian tên, bạn sẽ thấy các loại tài nguyên và hành động, chẳng hạn như AppManagement.ApplicationPackages.Read, cung cấp quyền đọc cho các gói ứng dụng. Để biết thêm thông tin, hãy xem bài viết Tham khảo về quyền.

Lưu ý

API Nền tảng Power chỉ sử dụng các quyền được ủy quyền tại thời điểm này. Đối với các ứng dụng chạy với ngữ cảnh người dùng, hãy yêu cầu cấp phép được ủy nhiệm bằng cách sử dụng tham số phạm vi. Các quyền này ủy quyền cho đặc quyền của người dùng đã đăng nhập vào ứng dụng của bạn để nó có thể hoạt động như người dùng khi gọi các điểm cuối API Nền tảng Power.

Đối với định danh chính của dịch vụ, không sử dụng quyền ứng dụng. Thay vào đó, sau khi bạn tạo đăng ký ứng dụng, hãy gán vai trò RBAC cho ứng dụng đó để cấp các quyền trong phạm vi (chẳng hạn như Người đóng góp hoặcNgười đọc). Để biết thêm thông tin, hãy xem Hướng dẫn: Gán vai trò RBAC cho tên dịch vụ chính.

Sau khi bạn thêm các quyền bắt buộc vào ứng dụng, hãy chọn Cấp sự chấp thuận của người quản trị để hoàn tất thiết lập. Bằng cách cấp sự chấp thuận của người quản trị, bạn ủy quyền quyền cho tất cả người dùng trong đối tượng thuê để họ không được nhắc bằng hộp thoại chấp thuận tương tác trong lần đầu tiên họ sử dụng ứng dụng của bạn. Nếu bạn muốn có sự chấp thuận tương tác cho mỗi người dùng, hãy tuân theo nền tảng định danh Microsoft và dòng mã ủy quyền OAuth 2.0.

Bạn cũng có thể cấp sự chấp thuận của người quản trị bằng cách sử dụng Azure CLI:

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

Bước 3. Cấu hình nền tảng và chuyển hướng URI

SDK, tập lệnh PowerShell và các ứng dụng trên máy tính để xác thực thay mặt cho người dùng yêu cầu URI chuyển hướng để Microsoft Entra có thể trả lại mã thông báo trở lại ứng dụng của bạn sau khi xác thực.

Trong đăng ký ứng dụng của bạn, hãy chuyển đến Quản lý - Xác thực.
Chọn Thêm URI Chuyển hướng, rồi chọn Ứng dụng dành cho thiết bị di động và máy tính để bàn.
Chọn URI chuyển hướng tích hợp sau:

https://login.microsoftonline.com/common/oauth2/nativeclient
Chọn Cấu hình để lưu.

Bạn cũng có thể thêm URI chuyển hướng bằng cách sử dụng 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

Thiết đặt máy khách công cộng

Trong phần Thiết đặt nâng cao trên cùng tab Xác thực, có nút bật tắt Cho phép dòng máy khách công cộng. Đặt công cụ chuyển đổi này thành Có chỉ khi bạn dự định sử dụng dòng Thông tin xác thực Mật khẩu chủ sở hữu tài nguyên (ROPC), dòng này sẽ gửi tên người dùng và mật khẩu trực tiếp trong nội dung yêu cầu mã thông báo.

Dòng này không hoạt động đối với các tài khoản đã bật xác thực đa yếu tố. Đối với các dòng mã thiết bị hoặc trình duyệt tương tác, bạn không cần phải bật cài đặt này.

Bước 4. (Tùy chọn) Cấu hình chứng chỉ và bí mật

Nếu ứng dụng của bạn yêu cầu tài nguyên đọc và viết dưới dạng chính nó, còn được gọi là tài nguyên chính của dịch vụ, có hai cách để xác thực. Để sử dụng chứng chỉ, hãy đi tới Quản lý - Chứng chỉ và bí mật. Bên dưới mục Chứng chỉ, tải lên một chứng chỉ x509 mà bạn có thể sử dụng để xác thực.

Cách khác là sử dụng phần Bí mật để tạo ra một mã bí mật của khách hàng. Lưu bí mật ở một vị trí an toàn để sử dụng với nhu cầu tự động hóa của bạn. Chứng chỉ hoặc các tùy chọn bí mật cho phép bạn xác thực với Microsoft Entra và nhận một mã thông báo cho máy khách này, mà bạn chuyển đến các API REST hoặc PowerShell cmdlets.

Bước 5. Yêu cầu mã thông báo truy cập

Bạn có thể lấy mã thông báo của người mang quyền truy nhập theo hai cách: một chiều cho tên người dùng và mật khẩu, còn cách khác là cho chủ thể dịch vụ.

Dòng tên người dùng và mật khẩu

Hãy đảm bảo đọc phần máy khách công cộng. Sau đó, gửi yêu cầu POST qua HTTP đến Microsoft Entra ID với thông tin tên người dùng và mật khẩu.

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

Ví dụ trước có chứa chỗ dành sẵn mà bạn có thể truy xuất từ ứng dụng máy khách của mình trong Microsoft Entra ID. Bạn nhận được phản hồi mà bạn có thể sử dụng để thực hiện các cuộc gọi tiếp theo đến API Nền tảng Power.

{
  "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..."
}

Sử dụng giá trịmã thông báo truy cập trong các lệnh gọi tiếp theo đến API của Power Platform API với tiêu đề HTTP Ủy quyền.

Dòng chảy của nguyên tắc dịch vụ

Hãy chắc chắn đọc phần Cấu hình chứng chỉ và bí mật. Sau đó, gửi yêu cầu POST qua HTTP đến Microsoft Entra ID có chứa thông tin bí mật của máy khách. Phương pháp xác thực này thường được gọi là xác thực chính của dịch vụ.

Quan trọng

Trước khi sử dụng xác thực chính của dịch vụ, hãy hoàn thành các bước 1-4 trước đó trong bài viết này để tạo và cấu hình đăng ký ứng dụng của bạn với chứng chỉ hoặc bí mật máy khách. Sau đó, gán tên dịch vụ chính cho vai trò RBAC để kiểm soát cấp độ truy nhập của dịch vụ. Để tìm hiểu thêm, hãy xem Hướng dẫn: Gán vai trò RBAC cho tên dịch vụ chính.

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

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

Sử dụng giá trịmã thông báo truy cập trong các lệnh gọi tiếp theo đến API của Power Platform API với tiêu đề HTTP Ủy quyền. Quyền có hiệu lực của tên dịch vụ chính được xác định bởi vai trò RBAC được gán cho vai trò đó. Để tìm hiểu cách gán vai trò, hãy xem Hướng dẫn: Gán vai trò RBAC cho chủ thể dịch vụ.

Bắt đầu nhanh với Azure CLI

Tập lệnh sau tạo ra một ứng dụng đăng ký đầu cuối. Chạy từng lệnh theo thứ tự và thay thế giá trị chỗ dành sẵn bằng giá trị của riêng bạn.

# 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

Sau khi chạy các lệnh này, bạn có thể sử dụng đăng ký ứng dụng của mình với SDK, PowerShell hoặc cuộc gọi REST trực tiếp. Để tra cứu ID quyền cho tham số --api-permissions , hãy xem tham chiếu Quyền.

Khắc phục sự cố thường gặp

Lỗi này xảy ra khi người quản trị chưa đồng ý với các quyền API trên đăng ký ứng dụng của bạn. Đi tới Đăng ký ứng dụng quyền> API ứng dụng > bạn và chọn Cấp sự chấp thuận của người quản trị.

Ngoài ra, hãy chạy:

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

Lỗi "Người dùng không được gán vai trò cho ứng dụng"

Lỗi này có nghĩa là ứng dụng doanh nghiệp liên kết với đăng ký ứng dụng của bạn đã yêu cầu gán người dùng thành Có. Khi thiết đặt này được bật, chỉ người dùng hoặc nhóm được gán rõ ràng cho ứng dụng mới có thể đăng nhập. Để khắc phục lỗi này, hãy thực hiện một trong các hành động sau:

Đi tới Microsoft Entra ID Enterprise ứng dụng>Thuộc tính> ứng dụng của >bạn và đặt Gán bắt buộc thành Không.
Thêm người dùng hoặc nhóm bảo mật liên quan bên dưới Người dùng và nhóm.

Chính sách truy nhập có điều kiện chặn truy nhập

Nếu tổ chức của bạn áp dụng các chính sách truy nhập có điều kiện, họ có thể chặn việc mua lại mã thông báo cho đăng ký ứng dụng của bạn. Các nguyên nhân phổ biến bao gồm yêu cầu tuân thủ thiết bị, giới hạn về vị trí hoặc chính sách dựa trên rủi ro. Làm việc với người quản trị Microsoft Entra để loại trừ việc đăng ký ứng dụng của bạn khỏi chính sách hoặc đảm bảo máy khách đáp ứng các yêu cầu chính sách.

Không tìm thấy "API Nền tảng Power" trong bộ chọn API

Nếu tìm kiếm API Power Platform theo tên hoặc GUID trong hộp thoại quyền API không trả về kết quả nào, thì tên dịch vụ chính không được tạo trong đối tượng thuê của bạn. Làm theo các bước bắt buộc làm mới trong Bước 2 để tạo.

Xác thực với các SDK Nền tảng Nguồn và PowerShell

Các ví dụ sau đây cho thấy cách xác thực và thực hiện cuộc gọi API mẫu bằng cách sử dụng từng SDK và PowerShell. Trước khi chạy các ví dụ này, hãy hoàn thành Các bước 1-3 trước đó trong bài viết này để tạo và đặt cấu hình đăng ký ứng dụng của bạn.

Xác thực tương tác (người dùng được ủy quyền)

Xác thực tương tác sẽ mở ra một cửa sổ trình duyệt để người dùng đăng nhập. Dòng này hoạt động tốt nhất cho các tập lệnh dành cho nhà phát triển, công cụ quản trị và bất kỳ kịch bản nào có người dùng.

# 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

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

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

Máy khách bí mật (tên dịch vụ chính)

Xác thực máy khách bí mật sử dụng bí mật máy khách hoặc chứng chỉ và không yêu cầu tương tác người dùng. Dòng xác thực này phù hợp nhất với dịch vụ nền, đường ống dẫn và tự động hóa.