Microsoft Fabric의 워크로드 인증 지침 개요

이 문서에서는 Microsoft Fabric 워크로드를 빌드할 때 인증을 사용하는 방법에 대한 지침을 제공합니다. 여기에는 토큰 및 동의 작업에 대한 정보가 포함됩니다.

시작하기 전에 인증 개요 및 인증 설정개념을 잘 알고 있는지 확인합니다.

Data plane and control plane APIs

데이터 평면 API 워크로드 백 엔드가 노출하는 API입니다. 워크로드 프런트 엔드는 직접 호출할 수 있습니다. For data plane APIs, the workload backend can decide on what APIs to expose.
Control plane APIs are APIs that go through Fabric. 이 프로세스는 JavaScript API를 호출하는 워크로드 프런트 엔드로 시작하고 워크로드 백 엔드를 호출하는 패브릭으로 끝납니다. 이러한 API의 예는 항목 만들기입니다.

컨트롤 플레인 API의 경우 워크로드는 워크로드 백 엔드에 정의된 계약을 따르고 해당 API를 구현해야 합니다.

Microsoft Entra ID에서 워크로드 애플리케이션에 API 탭 노출

On the Expose an API tab, you need to add scopes for control plane APIs and scopes for data plane APIs:

The scopes added for control plane APIs should preauthorize the Fabric Client for Workloads application with application ID d2450708-699c-41e3-8077-b0c8341509aa. 이러한 범위는 Fabric이 호출할 때 워크로드 백 엔드가 수신하는 토큰에 포함됩니다.

흐름이 작동하려면 컨트롤 플레인 API에 대해 하나 이상의 범위를 추가해야 합니다.
The scopes added for data plane APIs should preauthorize Microsoft Power BI with application ID 871c010f-5e61-4fb1-83ac-98610a7e9110. acquireAccessToken JavaScript API가 반환하는 토큰에 포함됩니다.

데이터 평면 API의 경우 이 탭을 사용하여 워크로드가 노출하는 각 API에 대한 세분화된 권한을 관리할 수 있습니다. 이상적으로는 워크로드 백 엔드가 노출하는 각 API에 대한 범위 집합을 추가하고 클라이언트에서 해당 API가 호출될 때 수신된 토큰에 해당 범위가 포함되어 있는지 확인해야 합니다. 예를 들어:
- 워크로드는 클라이언트에 ReadData 및 WriteData두 개의 API를 노출합니다.
- 워크로드는 data.read 및 data.write두 개의 데이터 평면 범위를 노출합니다.
- ReadData API에서 워크로드는 흐름이 계속되기 전에 data.read 범위가 토큰에 포함되어 있는지 확인합니다. WriteData에도 동일하게 적용됩니다.

API permissions tab on the workload's application in Microsoft Entra ID

API 권한 탭에서 워크로드가 토큰을 교환하는 데 필요한 모든 범위를 추가해야 합니다. 필수적으로 추가해야 하는 범위는 Power BI 서비스의 Fabric.Extend입니다. 이 범위가 없으면 Fabric에 대한 요청이 실패할 수 있습니다.

Working with tokens and consents

데이터 평면 API를 사용하는 경우 워크로드 프런트 엔드는 워크로드 백 엔드 호출에 대한 토큰을 획득해야 합니다.

The following sections describe how the workload frontend should use the JavaScript API and on-behalf-of (OBO) flows to acquire tokens for the workload and external services, and to work with consents.

1단계: 토큰 획득

워크로드는 매개 변수를 제공하지 않고 JavaScript API를 사용하여 토큰을 요청하는 것으로 시작합니다. 이 호출로 인해 다음 두 가지 시나리오가 발생할 수 있습니다.

사용자에게 워크로드가 구성한 모든 정적 종속성(API 권한 탭에 구성된 항목)의 동의 창이 표시됩니다. 이 시나리오는 사용자가 애플리케이션의 홈 테넌트에 속하지 않고 사용자가 이전에 이 애플리케이션에 대한 Microsoft Graph에 동의를 부여하지 않은 경우에 발생합니다.
사용자에게 동의 창이 표시되지 않습니다. 이 시나리오는 사용자가 이미 이 애플리케이션에 대해 Microsoft Graph에 한 번 이상 동의했거나 사용자가 애플리케이션의 홈 테넌트의 일부인 경우에 발생합니다.

두 시나리오 모두에서 워크로드는 사용자가 모든 종속성에 대해 전체 동의를 했는지 여부를 신경 쓰지 않아야 합니다(이 시점에서는 알 수 없음). 수신된 토큰은 워크로드 백 엔드 대상 그룹을 가지고 있으며 워크로드 프런트 엔드에서 워크로드 백 엔드를 직접 호출하는 데 사용할 수 있습니다.

2단계: 외부 서비스에 액세스 시도

워크로드는 인증이 필요한 서비스에 액세스해야 할 수 있습니다. For that access, it needs to perform the OBO flow, where it exchanges the token that it received from its client or from Fabric to another service. 동의가 부족하거나 워크로드가 토큰을 교환하려는 리소스에 구성된 일부 Microsoft Entra 조건부 액세스 정책으로 인해 토큰 교환이 실패할 수 있습니다.

To solve this problem, it's the workload's responsibility to propagate the error to the client when working with direct calls between the frontend and the backend. It's also the workload's responsibility to propagate the error to the client when working with calls from Fabric by using the error propagation described in Workload communication.

워크로드가 오류를 전파한 후 acquireAccessToken JavaScript API를 호출하여 동의 또는 조건부 액세스 정책 문제를 해결하고 작업을 다시 시도할 수 있습니다.

For data plane API failures, see Handling multifactor authentication, Conditional Access, and incremental consent. For control plane API failures, see Workload communication.

예제 시나리오

세 가지 패브릭 API에 액세스해야 하는 워크로드를 살펴보겠습니다.

List workspaces: GET https://api.fabric.microsoft.com/v1/workspaces
Create a warehouse: POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/warehouses
Write to a lakehouse file: PUT https://onelake.dfs.fabric.microsoft.com/{filePath}?resource=file

To be able to work with those APIs, the workload backend needs to exchange tokens for the following scopes:

작업 영역을 나열하는 경우: https://analysis.windows.net/powerbi/api/Workspace.Read.All 또는 https://analysis.windows.net/powerbi/api/Workspace.ReadWrite.All
웨어하우스 생성용: https://analysis.windows.net/powerbi/api/Warehouse.ReadWrite.All 또는 https://analysis.windows.net/powerbi/api/Item.ReadWrite.All
For writing to a lakehouse file: https://storage.azure.com/user_impersonation

Note

각 Fabric API에 필요한 범위는 이 참조 문서 에서 찾을 수 있습니다.

앞에서 언급한 범위는 API 권한워크로드 애플리케이션에서 구성해야 합니다.

워크로드가 발생할 수 있는 시나리오의 예를 살펴보겠습니다.

Example 1

워크로드 백 엔드에 사용자의 작업 영역을 가져오고 클라이언트에 반환하는 데이터 평면 API가 있다고 가정해 보겠습니다.

워크로드 프런트 엔드는 JavaScript API를 사용하여 토큰을 요청합니다.
The workload frontend calls the workload backend API to get the workspaces of the user and attaches the token in the request.
The workload backend validates the token and tries to exchange it for the required scope (let's say https://analysis.windows.net/powerbi/api/Workspace.Read.All).
사용자가 애플리케이션이 이 리소스에 액세스하는 데 동의하지 않았기 때문에 워크로드가 지정된 리소스에 대한 토큰을 교환하지 못합니다(AADSTS 오류 코드참조).
워크로드 백 엔드는 해당 리소스에 대한 동의가 필요하도록 지정하여 오류를 워크로드 프런트 엔드에 전파합니다. 워크로드 프런트 엔드는 acquireAccessToken JavaScript API를 호출하고 additionalScopesToConsent제공합니다.

workloadClient.auth.acquireAccessToken({additionalScopesToConsent: ["https://analysis.windows.net/powerbi/api/Workspace.Read.All"]})

또는 워크로드가 애플리케이션에 구성된 모든 정적 종속성에 대한 동의를 요청할 수 있으며, 그 후 JavaScript API를 호출하여 promptFullConsent을 제공합니다.

workloadClient.auth.acquireAccessToken({promptFullConsent: true}).

이 호출은 사용자가 일부 종속성에 동의했는지 여부에 관계없이 동의 창을 표시합니다. 그런 다음 워크로드 프런트 엔드가 작업을 다시 시도할 수 있습니다.

Note

토큰 교환이 여전히 동의 오류로 실패하는 경우 사용자가 동의를 부여하지 않았음을 의미합니다. 워크로드는 이러한 시나리오를 처리해야 합니다. 예를 들어 이 API는 동의가 필요하고 동의 없이는 작동하지 않음을 사용자에게 알립니다.

Example 2

워크로드 백 엔드가 항목 만들기 API(패브릭에서 워크로드로 호출)의 OneLake에 액세스해야 한다고 가정해 보겠습니다.

워크로드 프런트 엔드는 Create Item JavaScript API를 호출합니다.
워크로드 백 엔드는 Fabric에서 호출을 받고 위임된 토큰을 추출하여 유효성을 검사합니다.
The workload tries to exchange the token for https://storage.azure.com/user_impersonation but fails because the tenant administrator of the user-configured multifactor authentication needed to access Azure Storage (see AADSTS error codes).
The workload propagates the error alongside the claims returned in the error from Microsoft Entra ID to the client by using the error propagation described in Workload communication.
워크로드 프런트 엔드는 acquireAccessToken JavaScript API를 호출하고 claimsForConditionalAccessPolicy클레임을 제공합니다. 여기서 claims 워크로드 백 엔드에서 전파된 클레임을 참조합니다.

workloadClient.auth.acquireAccessToken({claimsForConditionalAccessPolicy: claims})

그런 다음 워크로드가 작업을 다시 시도할 수 있습니다.

Handling errors when requesting consents

경우에 따라 사용자는 다양한 오류로 인해 동의를 부여할 수 없습니다. 동의 요청 후 응답이 리디렉션 URI로 반환됩니다. 이 예제에서 이 코드는 응답을 처리합니다. (index.ts 파일에서 찾을 수 있습니다.)

const redirectUriPath = '/close'; 
const url = new URL(window.location.href); 
if (url.pathname?.startsWith(redirectUriPath)) { 
    // Handle errors, Please refer to https://learn.microsoft.com/entra/identity-platform/reference-error-codes 
    if (url?.hash?.includes("error")) { 
        // Handle missing service principal error 
        if (url.hash.includes("AADSTS650052")) { 
            printFormattedAADErrorMessage(url?.hash); 
        // handle user declined the consent error 
        } else  if (url.hash.includes("AADSTS65004")) { 
            printFormattedAADErrorMessage(url?.hash); 
        } 
    } 
    // Always close the window  
    window.close(); 
}

워크로드 프런트 엔드는 URL에서 오류 코드를 추출하고 그에 따라 처리할 수 있습니다.

Note

두 시나리오(오류 및 성공)에서 워크로드는 항상 대기 시간 없이 창을 즉시 닫아야 합니다.

피드백

이 페이지가 도움이 되었나요?

Last updated on 2025-04-13

다음을 통해 공유

Microsoft Fabric의 워크로드 인증 지침 개요

Data plane and control plane APIs

Microsoft Entra ID에서 워크로드 애플리케이션에 API 탭 노출

API permissions tab on the workload's application in Microsoft Entra ID

Working with tokens and consents

1단계: 토큰 획득

2단계: 외부 서비스에 액세스 시도

예제 시나리오

Example 1

Example 2

Handling errors when requesting consents

피드백

추가 리소스