Microsoft Fabric 확장성 도구 키트에 대한 인증 지침

이 문서에서는 Microsoft Fabric 확장성 도구 키트 워크로드를 빌드할 때 인증을 사용하는 방법에 대한 지침을 제공합니다. 여기에는 토큰 작업, 동의 및 프런트 엔드 애플리케이션에서 다양한 서비스에 액세스하는 방법에 대한 정보가 포함됩니다.

시작하기 전에 인증 개요의 개념에 대해 잘 알고 있는지 확인합니다.

프런트 엔드 전용 인증 모델

확장성 도구 키트는 기존 워크로드에 비해 인증을 간소화하는 프런트 엔드 전용 아키텍처를 사용합니다.

• 직접 API 호출: 프런트 엔드는 패브릭 API, Azure 서비스 및 외부 애플리케이션을 직접 호출합니다.
• 토큰 재사용: 단일 토큰을 사용하여 여러 Entra 보안 서비스에 대해 인증할 수 있습니다.
• 간소화된 동의: 자동 프롬프트를 사용하여 플랫폼에서 동의 관리를 처리합니다.

Microsoft Entra 애플리케이션 구성

API 탭 노출

워크로드 애플리케이션에 대한 범위를 구성합니다.

• 패브릭 통합 범위: 애플리케이션 ID를 사용하여 Microsoft Power BI 사전 인증 871c010f-5e61-4fb1-83ac-98610a7e9110
• 사용자 지정 API 범위: 워크로드가 노출하는 사용자 지정 API에 대한 범위 추가
• 세분화된 권한: 읽기 및 쓰기 작업에 다른 범위 사용

예를 들어 워크로드가 데이터 API를 노출하는 경우:

• 읽기 작업에 대한 범위 추가 data.read
• 쓰기 작업에 대한 범위 추가 data.write
• API 처리기에서 적절한 범위 유효성 검사

API 권한 탭

워크로드에서 액세스해야 하는 외부 서비스에 대한 사용 권한을 구성합니다.

• 필수: Fabric.Extend Power BI 서비스(패브릭 통합에 필수)
• Azure 서비스: 다음과 같은 Azure 서비스에 대한 범위 추가 https://storage.azure.com/user_impersonation
• 사용자 지정 애플리케이션: 고유한 Entra 보안 애플리케이션에 대한 범위 추가
• 타사 서비스: Entra 인증을 지원하는 외부 서비스 포함

토큰 사용 패턴

여러 서비스에 토큰 사용

확장성 도구 키트를 통해 획득한 프런트 엔드 토큰을 사용하여 다음을 인증할 수 있습니다.

패브릭 API

// Token automatically includes required Fabric scopes
const response = await fetch('https://api.fabric.microsoft.com/v1/workspaces', {
  headers: {
    'Authorization': `Bearer ${token.accessToken}`
  }
});

Azure 서비스

// Same token works for Azure services
const response = await fetch('https://management.azure.com/subscriptions', {
  headers: {
    'Authorization': `Bearer ${token.accessToken}`
  }
});

사용자 지정 애플리케이션

// Token works for your own Entra-secured applications
const response = await fetch('https://myapp.contoso.com/api/data', {
  headers: {
    'Authorization': `Bearer ${token.accessToken}`
  }
});

범위 관리

확장성 도구 키트는 일반적인 시나리오에 대한 범위 관리를 추상화합니다.

• 패브릭 클라이언트 라이브러리: 필요한 패브릭 범위를 자동으로 포함
• Azure 클라이언트 라이브러리: Azure 서비스 범위를 투명하게 처리
• 사용자 지정 범위: 필요한 경우 추가 범위 지정

동의 관리

초기 토큰 획득

먼저 토큰을 획득하여 인증 컨텍스트를 설정합니다.

const token = await workloadClient.auth.acquireFrontendAccessToken({ scopes: [] });

이 호출로 인해 다음이 발생할 수 있습니다.

• 동의 프롬프트: 사용자가 애플리케이션에 동의하지 않은 경우
• 무음 획득: 동의가 이전에 부여된 경우

추가 서비스 액세스 처리

워크로드가 추가 서비스에 액세스해야 하는 경우 필요한 범위를 지정합니다.

try {
  // Request token with specific scopes for Azure Storage
  const token = await workloadClient.auth.acquireFrontendAccessToken({
    scopes: ['https://storage.azure.com/user_impersonation']
  });
  
  // Use token to access Azure Storage
  const response = await fetch('https://mystorageaccount.blob.core.windows.net/', {
    headers: { 'Authorization': `Bearer ${token.token}` }
  });
} catch (error) {
  // Handle authentication or authorization errors
  console.error('Access failed:', error.message);
}

예제 시나리오

시나리오 1: 패브릭 및 Azure 서비스 액세스

워크로드는 다음을 수행해야 합니다.

• 패브릭 작업 영역 나열
• Azure Storage에서 읽기
• Azure Key Vault에 쓰기

구현:

1. 필요한 서비스에 대한 API 권한 구성
2. 초기 토큰 획득
3. 모든 서비스 호출에 토큰 사용
4. 필요에 따라 동의 프롬프트 처리

시나리오 2: 사용자 지정 애플리케이션 통합

워크로드는 사용자 고유의 백 엔드 서비스와 통합됩니다.

1. 백 엔드 구성: Entra 토큰을 허용하는지 확인
2. API 권한 추가: 워크로드 애플리케이션에 백 엔드의 범위 포함
3. 표준 인증 사용: 사용자 지정 서비스에 대해 동일한 토큰 패턴이 작동합니다.

시나리오 3: 타사 서비스 통합

외부 Entra 사용 서비스와 통합:

1. 서비스 등록: 타사 서비스에 워크로드 등록
2. 범위 구성: API 권한에 서비스의 범위 추가
3. 토큰 사용: 외부 서비스에 대해 동일한 인증 패턴 사용

오류 처리 및 문제 해결

일반적인 인증 오류

• 동의 필요: 사용자가 특정 범위에 대한 권한을 부여하지 않았습니다.
• 조건부 액세스: 추가 인증 요구 사항(예: MFA)
• 토큰 만료: 토큰이 만료되었으며 새로 고쳐야 합니다.
• 잘못된 범위: 요청된 범위가 구성되지 않았거나 사용할 수 없음

오류 처리 패턴

async function handleAuthenticatedRequest(url: string, requiredScopes: string[] = []) {
  try {
    const token = await workloadClient.auth.acquireFrontendAccessToken({ 
      scopes: requiredScopes 
    });
    return await makeRequest(url, token);
  } catch (error) {
    if (error.code === 'consent_required') {
      // User needs to grant consent for the requested scopes
      console.error('Consent required for scopes:', requiredScopes);
    }
    throw error;
  }
}

리디렉션 URI 처리

확장성 도구 키트에는 인증 동의 팝업에 대한 기본 제공 리디렉션 URI 처리가 포함됩니다. 이는 주 index.ts 파일에서 구현되며 동의 리디렉션을 자동으로 처리합니다.

도구 키트는 다음을 처리합니다.

• 자동 창 닫기: 사용자 상호 작용 후 동의 팝업이 자동으로 닫힙니다.
• 오류 처리: 특정 오류 코드가 검색되고 적절하게 처리됨
• 오류 표시: 실패한 동의 시도에서 사용자에게 친숙한 오류 메시지를 표시합니다.

도구 키트의 현재 구현:

const redirectUriPath = '/close';
const url = new URL(window.location.href);
if (url.pathname?.startsWith(redirectUriPath)) {
  // Handle errors
  if (url?.hash?.includes("error")) {
    if (url.hash.includes("AADSTS650052")) {
      // Handle missing service principal error
      printFormattedAADErrorMessage(url?.hash);
    } else if (url.hash.includes("AADSTS65004")) {
      // Handle user declined consent error
      printFormattedAADErrorMessage(url?.hash);
    } else {
      window.close();
    }
  } else {
    // Close window on successful consent
    window.close();
  }
}

모범 사례

토큰 관리

• 캐시 토큰: 만료될 때까지 토큰 다시 사용
• 새로 고침 처리: 자동 토큰 새로 고침 논리 구현
• 보안 스토리지: 브라우저 메모리에 안전하게 토큰 저장

동의 관리

• 최소 권한: 실제로 필요한 범위만 요청
• 점진적 동의: 기능이 사용됨에 따라 추가 권한 요청
• 메시지 지우기: 사용자에게 권한이 필요한 이유 설명

오류 처리

• 우아한 성능 저하: 가능한 경우 대체 기능 제공
• 사용자 피드백: 인증 요구 사항을 명확하게 전달
• 재시도 논리: 과도 장애에 대해 적절한 재시도 메커니즘을 구현합니다

관련 콘텐츠

• 인증 개요
• 인증 JavaScript API