Microsoft Fabric의 워크로드 인증 지침 개요
이 문서에서는 Microsoft Fabric 워크로드를 빌드할 때 인증을 사용하는 방법에 대한 지침을 제공합니다. 여기에는 토큰 및 동의 작업에 대한 정보가 포함됩니다.
시작하기 전에 인증 개요 및 인증 설정개념을 잘 알고 있는지 확인합니다.
데이터 평면 및 컨트롤 플레인 API
데이터 평면 API 워크로드 백 엔드가 노출하는 API입니다. 워크로드 프런트 엔드는 직접 호출할 수 있습니다. 데이터 평면 API의 경우 워크로드 백 엔드는 노출할 API를 결정할 수 있습니다.
컨트롤 플레인 API 패브릭을 통과하는 API입니다. 이 프로세스는 JavaScript API를 호출하는 워크로드 프런트 엔드로 시작하고 워크로드 백 엔드를 호출하는 패브릭으로 끝납니다. 이러한 API의 예는 항목 만들기입니다.
컨트롤 플레인 API의 경우 워크로드는 워크로드 백 엔드에 정의된 계약을 따르고 해당 API를 구현해야 합니다.
Microsoft Entra ID에서 워크로드 애플리케이션에 API 탭 노출
API를 노출 탭에서, 컨트롤 플레인 API의 범위와 데이터 평면 API에 대한 범위를 추가해야 합니다.
컨트롤 플레인 API에 추가된 범위는 애플리케이션 ID
d2450708-699c-41e3-8077-b0c8341509aa인 Fabric Client for Workloads 애플리케이션을 사전 승인해야 합니다. 이러한 범위는 Fabric이 호출할 때 워크로드 백 엔드가 수신하는 토큰에 포함됩니다.흐름이 작동하려면 컨트롤 플레인 API에 대해 하나 이상의 범위를 추가해야 합니다.
데이터 평면 API에 추가된 범위는 애플리케이션 ID
871c010f-5e61-4fb1-83ac-98610a7e9110으로 Microsoft Power BI를 사전 인증해야 합니다.acquireAccessTokenJavaScript API가 반환하는 토큰에 포함됩니다.데이터 평면 API의 경우 이 탭을 사용하여 워크로드가 노출하는 각 API에 대한 세분화된 권한을 관리할 수 있습니다. 이상적으로는 워크로드 백 엔드가 노출하는 각 API에 대한 범위 집합을 추가하고 클라이언트에서 해당 API가 호출될 때 수신된 토큰에 해당 범위가 포함되어 있는지 확인해야 합니다. 예를 들어:
- 워크로드는 클라이언트에
ReadData및WriteData두 개의 API를 노출합니다. - 워크로드는
data.read및data.write두 개의 데이터 평면 범위를 노출합니다. -
ReadDataAPI에서 워크로드는 흐름이 계속되기 전에data.read범위가 토큰에 포함되어 있는지 확인합니다.WriteData에도 동일하게 적용됩니다.
- 워크로드는 클라이언트에
Microsoft Entra ID의 워크로드 애플리케이션에 대한 API 권한 탭
API 권한 탭에서 워크로드가 토큰을 교환하는 데 필요한 모든 범위를 추가해야 합니다. 필수적으로 추가해야 하는 범위는 Power BI 서비스의 Fabric.Extend입니다. 이 범위가 없으면 Fabric에 대한 요청이 실패할 수 있습니다.
토큰 및 동의 작업
데이터 평면 API를 사용하는 경우 워크로드 프런트 엔드는 워크로드 백 엔드 호출에 대한 토큰을 획득해야 합니다.
다음 섹션에서는 워크로드 프런트 엔드가 JavaScript API 사용하고 OBO(OBO) 흐름을 사용하여 워크로드 및 외부 서비스에 대한 토큰을 획득하고 동의를 얻는 방법을 설명합니다.
1단계: 토큰 획득
워크로드는 매개 변수를 제공하지 않고 JavaScript API를 사용하여 토큰을 요청하는 것으로 시작합니다. 이 호출로 인해 다음 두 가지 시나리오가 발생할 수 있습니다.
사용자에게 워크로드가 구성한 모든 정적 종속성(API 권한 탭에 구성된 항목)의 동의 창이 표시됩니다. 이 시나리오는 사용자가 애플리케이션의 홈 테넌트에 속하지 않고 사용자가 이전에 이 애플리케이션에 대한 Microsoft Graph에 동의를 부여하지 않은 경우에 발생합니다.
사용자에게 동의 창이 표시되지 않습니다. 이 시나리오는 사용자가 이미 이 애플리케이션에 대해 Microsoft Graph에 한 번 이상 동의했거나 사용자가 애플리케이션의 홈 테넌트의 일부인 경우에 발생합니다.
두 시나리오 모두에서 워크로드는 사용자가 모든 종속성에 대해 전체 동의를 했는지 여부를 신경 쓰지 않아야 합니다(이 시점에서는 알 수 없음). 수신된 토큰은 워크로드 백 엔드 대상 그룹을 가지고 있으며 워크로드 프런트 엔드에서 워크로드 백 엔드를 직접 호출하는 데 사용할 수 있습니다.
2단계: 외부 서비스에 액세스 시도
워크로드는 인증이 필요한 서비스에 액세스해야 할 수 있습니다. 그 액세스를 위해서는 클라이언트 또는 패브릭에서 받은 토큰을 다른 서비스로 교환하는 OBO 흐름를 수행해야 합니다. 동의가 부족하거나 워크로드가 토큰을 교환하려는 리소스에 구성된 일부 Microsoft Entra 조건부 액세스 정책으로 인해 토큰 교환이 실패할 수 있습니다.
이 문제를 해결하기 위해 프런트 엔드와 백 엔드 간의 직접 호출을 사용할 때 클라이언트에 오류를 전파하는 것은 워크로드의 책임입니다. 워크로드 통신 에 설명된 오류 전파를 사용하여 Fabric에서 호출을 처리할 때, 클라이언트에게 오류를 전달하는 것은 워크로드의 책임입니다.
워크로드가 오류를 전파한 후 acquireAccessToken JavaScript API를 호출하여 동의 또는 조건부 액세스 정책 문제를 해결하고 작업을 다시 시도할 수 있습니다.
데이터 평면 API 오류는 다단계 인증, 조건부 액세스 및 증분 동의처리를 참조하세요. 제어 평면 API 오류가 발생했을 때는 워크로드 통신을 참조하세요.
예제 시나리오
세 가지 패브릭 API에 액세스해야 하는 워크로드를 살펴보겠습니다.
작업 영역 나열:
GET https://api.fabric.microsoft.com/v1/workspaces웨어하우스 만들기:
POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/warehouses레이크하우스 파일에 쓰기:
PUT https://onelake.dfs.fabric.microsoft.com/{filePath}?resource=file
이러한 API로 작업하려면 워크로드 백 엔드가 다음 범위에 대한 토큰을 교환해야 합니다.
- 작업 영역을 나열하는 경우:
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 - 레이크하우스 파일에 쓰기:
https://storage.azure.com/user_impersonation
앞에서 언급한 범위는 API 권한워크로드 애플리케이션에서 구성해야 합니다.
워크로드가 발생할 수 있는 시나리오의 예를 살펴보겠습니다.
예 1
워크로드 백 엔드에 사용자의 작업 영역을 가져오고 클라이언트에 반환하는 데이터 평면 API가 있다고 가정해 보겠습니다.
워크로드 프런트 엔드는 JavaScript API를 사용하여 토큰을 요청합니다.
워크로드 프런트 엔드는 워크로드 백 엔드 API를 호출하여 사용자의 작업 영역을 가져오고 요청에 토큰을 연결합니다.
워크로드 백 엔드는 토큰의 유효성을 검사하고 필요한 범위로 교환하려고 시도합니다(가정
https://analysis.windows.net/powerbi/api/Workspace.Read.All해 보겠습니다).사용자가 애플리케이션이 이 리소스에 액세스하는 데 동의하지 않았기 때문에 워크로드가 지정된 리소스에 대한 토큰을 교환하지 못합니다(AADSTS 오류 코드참조).
워크로드 백 엔드는 해당 리소스에 대한 동의가 필요하도록 지정하여 오류를 워크로드 프런트 엔드에 전파합니다. 워크로드 프런트 엔드는
acquireAccessTokenJavaScript API를 호출하고additionalScopesToConsent제공합니다.workloadClient.auth.acquireAccessToken({additionalScopesToConsent: ["https://analysis.windows.net/powerbi/api/Workspace.Read.All"]})또는 워크로드가 애플리케이션에 구성된 모든 정적 종속성에 대한 동의를 요청할 수 있으며, 그 후 JavaScript API를 호출하여
promptFullConsent을 제공합니다.workloadClient.auth.acquireAccessToken({promptFullConsent: true}).
이 호출은 사용자가 일부 종속성에 동의했는지 여부에 관계없이 동의 창을 표시합니다. 그런 다음 워크로드 프런트 엔드가 작업을 다시 시도할 수 있습니다.
참고 항목
토큰 교환이 여전히 동의 오류로 실패하는 경우 사용자가 동의를 부여하지 않았음을 의미합니다. 워크로드는 이러한 시나리오를 처리해야 합니다. 예를 들어 이 API는 동의가 필요하고 동의 없이는 작동하지 않음을 사용자에게 알립니다.
예제 2
워크로드 백 엔드가 항목 만들기 API(패브릭에서 워크로드로 호출)의 OneLake에 액세스해야 한다고 가정해 보겠습니다.
워크로드 프런트 엔드는 Create Item JavaScript API를 호출합니다.
워크로드 백 엔드는 Fabric에서 호출을 받고 위임된 토큰을 추출하여 유효성을 검사합니다.
워크로드가
https://storage.azure.com/user_impersonation토큰을 교환하려고 시도하지만, 사용자 구성 다단계 인증의 테넌트 관리자가 관련되어 있어서 Azure Storage에 액세스하는 데 실패합니다(자세한 내용은 AADSTS 오류 코드참조).Microsoft Entra ID에서 클라이언트로 반환된 오류와 클레임을 함께 전파하기 위해 워크로드 통신에 설명된 오류 전파 방식이 워크로드에 의해 사용됩니다.
워크로드 프런트 엔드는
acquireAccessTokenJavaScript API를 호출하고claimsForConditionalAccessPolicy클레임을 제공합니다. 여기서claims워크로드 백 엔드에서 전파된 클레임을 참조합니다.workloadClient.auth.acquireAccessToken({claimsForConditionalAccessPolicy: claims})
그런 다음 워크로드가 작업을 다시 시도할 수 있습니다.
동의를 요청할 때 오류 처리
경우에 따라 사용자는 다양한 오류로 인해 동의를 부여할 수 없습니다. 동의 요청 후 응답이 리디렉션 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에서 오류 코드를 추출하고 그에 따라 처리할 수 있습니다.
참고 항목
두 시나리오(오류 및 성공)에서 워크로드는 항상 대기 시간 없이 창을 즉시 닫아야 합니다.