인증 JavaScript API 참조

Fabric 확장 툴킷은 Fabric API, Azure 서비스, 그리고 Entra 보안 애플리케이션에 접근할 수 있는 인증 토큰을 획득하기 위한 JavaScript API를 제공합니다. 이 글은 포괄적인 API 참고 및 사용 사례를 제공합니다.

팁 (조언)

빠른 시작 가이드는 Microsoft Entra 토큰 획득을 참조하세요.

API 참고 자료

acquireFrontendAccessToken(params: AcquireFrontendAccessTokenParams): Promise<AccessToken>;

export interface AcquireFrontendAccessTokenParams {
    scopes: string[];
}

export interface AccessToken {
    token: string;
}

비고

현재의 확장 도구 키트 구현은 스코프를 포함한 기본 토큰 획득을 지원합니다. 완전 동의 프롬프트와 조건부 접근 처리 같은 고급 기능은 아직 제공되지 않았으나 향후 버전에서 추가될 수 있습니다.

API는 다음을 포함하는 객체를 AccessToken 반환합니다:

토큰: 인증 헤더에 사용할 JWT 토큰 문자열

기본 사용법

간단한 토큰 획득

// Acquire a token with default Fabric permissions
const token = await workloadClient.auth.acquireFrontendAccessToken({ scopes: [] });

// Use the token in API calls
const response = await fetch('https://api.fabric.microsoft.com/v1/workspaces', {
  headers: {
    'Authorization': `Bearer ${token.token}`,
    'Content-Type': 'application/json'
  }
});

특정 범위가 있는 토큰

// Request specific scopes for Azure Storage
const token = await workloadClient.auth.acquireFrontendAccessToken({
  scopes: ['https://storage.azure.com/user_impersonation']
});

토큰 사용 예시

패브릭 API 접근

토큰은 Fabric REST API와 직접 사용할 수 있습니다:

async function listWorkspaces() {
  const token = await workloadClient.auth.acquireFrontendAccessToken({ scopes: [] });
  
  const response = await fetch('https://api.fabric.microsoft.com/v1/workspaces', {
    headers: {
      'Authorization': `Bearer ${token.token}`
    }
  });
  
  return await response.json();
}

Azure service access

접근 필요한 Azure 서비스를 지정하려면 범위를 사용하세요:

async function readFromStorage(accountName, containerName, blobName) {
  const token = await workloadClient.auth.acquireFrontendAccessToken({
    scopes: ['https://storage.azure.com/user_impersonation']
  });
  
  const url = `https://${accountName}.blob.core.windows.net/${containerName}/${blobName}`;
  const response = await fetch(url, {
    headers: {
      'Authorization': `Bearer ${token.token}`,
      'x-ms-version': '2021-12-02'
    }
  });
  
  return await response.text();
}

사용자 지정 애플리케이션 접근

여러분의 Entra 보안 애플리케이션에 접근하세요:

async function callCustomAPI() {
  const token = await workloadClient.auth.acquireFrontendAccessToken({
    scopes: ['https://myapp.contoso.com/data.read']
  });
  
  const response = await fetch('https://myapp.contoso.com/api/data', {
    headers: {
      'Authorization': `Bearer ${token.token}`
    }
  });
  
  return await response.json();
}

매개 변수 참조

scopes

토큰에 필요한 권한을 지정하는 범위 문자열 배열입니다.

Common Azure 서비스 범위:

https://storage.azure.com/user_impersonation - Azure 스토리지
https://vault.azure.net/user_impersonation - Azure Key Vault
https://management.azure.com/user_impersonation - Azure 리소스 매니저
https://graph.microsoft.com/User.Read - 마이크로소프트 그래프

사용 예제:

const token = await workloadClient.auth.acquireFrontendAccessToken({
  scopes: [
    'https://storage.azure.com/user_impersonation'
  ]
});

빈 스코프 배열: 기본 Fabric 권한이 있는 토큰을 얻기 위해 빈 배열을 사용하세요:

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

확장 툴킷은 동의 워크플로우를 자동으로 처리합니다:

초기 요청: 동의가 없으면 팝업 창이 열립니다
사용자 상호작용: 사용자가 권한을 부여하거나 거부합니다
자동 종료: 사용자 행동 후 팝업이 자동으로 닫힙니다
토큰 전달: 성공하면 토큰이 애플리케이션으로 반환됩니다

툴킷은 동의 팝업을 자동으로 관리하지만, 리디렉션 URI 동작을 커스터마이즈할 수 있습니다. 동의 응답을 처리하는 리다이렉트 페이지를 만듭니다:

// redirect.js - Handle consent redirect
const redirectUriPath = '/close';
const url = new URL(window.location.href);

if (url.pathname?.startsWith(redirectUriPath)) {
  // Handle consent errors
  if (url?.hash?.includes("error")) {
    // Extract error information
    const errorMatch = url.hash.match(/error=([^&]+)/);
    const errorDescription = url.hash.match(/error_description=([^&]+)/);
    
    // Handle specific errors
    if (url.hash.includes("AADSTS650052")) {
      console.error("Service principal not configured");
    } else if (url.hash.includes("AADSTS65004")) {
      console.error("User declined consent");
    }
  }
  
  // Always close the popup immediately
  window.close();
}

서로 다른 테넌트 간 자원 접근을 위해:

// Request consent for cross-tenant access
const token = await workloadClient.auth.acquireAccessToken({
  additionalScopesToConsent: ['https://api.partner-app.com/data.read']
});

오류 처리

일반적인 오류 시나리오

async function robustTokenAcquisition() {
  try {
    return await workloadClient.auth.acquireAccessToken();
  } catch (error) {
    switch (error.code) {
      case 'user_cancelled':
        console.log('User cancelled the consent dialog');
        break;
      case 'consent_required':
        console.log('Additional consent required');
        break;
      case 'interaction_required':
        console.log('User interaction required');
        break;
      default:
        console.error('Authentication error:', error.message);
    }
    throw error;
  }
}

토큰 만료 처리

class TokenManager {
  private currentToken: AccessToken | null = null;
  
  async getValidToken(): Promise<AccessToken> {
    if (!this.currentToken || this.isTokenExpired(this.currentToken)) {
      this.currentToken = await workloadClient.auth.acquireAccessToken();
    }
    return this.currentToken;
  }
  
  private isTokenExpired(token: AccessToken): boolean {
    // Add buffer time to prevent requests with almost-expired tokens
    const bufferMinutes = 5;
    const expirationWithBuffer = new Date(token.expiresOn.getTime() - (bufferMinutes * 60 * 1000));
    return new Date() >= expirationWithBuffer;
  }
}

모범 사례

토큰 캐싱 및 재사용

캐시 토큰: 만료될 때까지 메모리에 토큰을 저장합니다
자동 갱신: 만료 전에 자동 토큰 갱신을 구현합니다
보안 저장소: 토큰을 로컬 저장소나 쿠키에 절대 영속화하지 마세요

범위 관리

최소 범위: 필요한 권한만 요청하세요
점진적 동의: 기능이 사용될 때마다 추가 범위를 요청합니다
범위 검증: API 호출 전에 필요한 범위 포함 토큰 검증

고급 오류 처리

그레이스풀 디그레이데이션: 인증이 실패했을 때 백업 기능을 제공합니다
사용자 메시지: 권한이 왜 필요한지 명확히 설명하세요
재시도 논리: 과도 장애에 대해 적절한 재시도 메커니즘을 구현합니다

성능 최적화

병렬 요청: 가능하면 여러 서비스의 토큰을 병렬로 획득합니다
배치 작업: 토큰 획득 오버헤드를 최소화하기 위한 API 그룹 호출
캐시 관리: 효율적인 토큰 캐싱 전략 구현

빠른 시작: Microsoft Entra 토큰 획득 - 간단한 시작 가이드
인증 개요 - 고수준 인증 개념
인증 지침 - 모범 사례 및 권고
액세스 패브릭 API - 미리 구축된 API 래퍼

피드백

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

Last updated on 2025-12-15