다음을 통해 공유

인증 API

  • 아티클

인증 API를 사용하면 시각적 개체가 로그인한 사용자에 대한 Microsoft Entra ID(이전의 Azure AD) 액세스 토큰을 가져올 수 있어 Single Sign-On 인증이 용이해집니다.

Power BI 관리자는 전역 스위치를 통해 API를 사용하거나 사용하지 않도록 설정할 수 있습니다. 기본 설정은 API를 차단(사용하지 않도록 설정)합니다.

API는 AppSource 시각적 개체에만 적용 가능하며 프라이빗 시각적 개체에는 적용되지 않습니다. 개발 중인 시각적 개체는 게시되기 전에 디버그 모드에서 테스트할 수 있습니다.

지원되는 환경

다음 환경이 지원됩니다.

  • 웹
  • 바탕 화면
  • RS 데스크톱
  • 모바일

지원되지 않는 환경

다음 환경은 아직 지원되지 않습니다.

  • RS 서비스
  • 임베디드 분석
  • Teams

인증 API를 사용하는 방법

capability.json 파일에서 지원되는 각 클라우드에 대해 Microsoft Entra ID 등록 애플리케이션 URI와 함께 "AADAuthentication" 권한을 추가합니다. Fabric은 현재 클라우드에 구성된 대상 그룹에 따라 토큰을 생성하여 시각적 개체에 배달합니다.
그런 다음 시각적 개체는 토큰을 활용하여 백 엔드 서비스를 나타내는 각 대상 그룹에 대해 인증할 수 있습니다.

"privileges": [
    {
        "name": "AADAuthentication",
        "parameters": {
            "COM": "https://contoso.com",
            "CN": "https://contoso.cn"
        }
    }
]

pbiviz.json 파일에서 API 버전을 5.9.1 이상으로 설정합니다.

새로 노출된 AcquireAADTokenService에는 두 가지 메서드가 포함되어 있습니다.

  • acquireAADToken: 시각적 개체에 대해 AcquireAADTokenResult 형식의 인증 토큰 페이로드를 반환하거나, 가져올 수 없는 경우 null을 반환합니다.

     /**
 * Enum representing the various clouds supported by the Authentication API.
 */
export const enum CloudName {
    COM = "COM",         // Commercial Cloud
    CN = "CN",           // China Cloud
    GCC = "GCC",         // US Government Community Cloud
    GCCHIGH = "GCCHIGH", // US Government Community Cloud High
    DOD = "DOD",         // US Department of Defense Cloud
}

/**
 * Interface representing information about the user associated with the token.
 */
export interface AcquireAADTokenUserInfo {
    userId?: string;   // Unique identifier for the user
    tenantId?: string; // Unique identifier for the tenant
}

/**
 * Interface representing information about the fabric environment.
 */
export interface AcquireAADTokenFabricInfo {
    cloudName?: CloudName; // Name of the cloud environment
}

/**
 * Interface representing the result of acquiring a Microsoft Entra ID token.
 */
export interface AcquireAADTokenResult {
    accessToken?: string;       // Access token issued by Microsoft Entra ID
    expiresOn?: number;         // Expiration time of the access token
    userInfo?: AcquireAADTokenUserInfo;     // Information about the user associated with the token
    fabricInfo?: AcquireAADTokenFabricInfo; // Information about the fabric environment
}

  • acquireAADTokenstatus: 토큰 획득과 관련된 다음 권한 상태 중 하나를 반환합니다.

    • Allowed: 현재 환경에서 권한이 허용됩니다.
    • NotDeclared: 시각적 기능 섹션에 권한 선언이 누락되었습니다.
    • NotSupported: 현재 환경에서는 권한이 지원되지 않습니다.
    • DisabledByAdmin: Fabric 관리자가 권한 사용을 거부했습니다.

다음 샘플 코드는 API를 사용하여 Microsoft Entra ID 토큰을 획득하는 방법을 보여 줍니다.

    // Step 1: Check the status of AAD token acquisition 
    const acquireTokenStatus = await this.acquireAADTokenService.acquireAADTokenstatus(); 

    // Step 2: Verify if acquiring the token is allowed 
    if (acquireTokenStatus === PrivilegeStatus.Allowed) { 

       // Step 3: Acquire the Microsoft Entra ID token
       const acquireAADTokenResult: AcquireAADTokenResult = await this.acquireAADTokenService.acquireAADToken(); 

       // Step 4: Confirm successful acquisition of the access token
       if (acquireAADTokenResult.accessToken) { 

            // Step 5: Call your backend API with the obtained token 
        } 
    } 

    // Step 6: Handle unsuccessful AAD token acquisition

고려 사항 및 제한 사항

다음 조건 중 하나라도 해당되면 토큰 획득이 차단됩니다.​

  • 테넌트 스위치가 꺼져 있습니다.

  • 사용자가 로그인되어 있지 않습니다(데스크톱).

  • ISV가 Power BI 애플리케이션을 사전 권한 부여하지 않았습니다.

  • AADAuthentication 권한 매개 변수의 형식이 잘못되었습니다.

  • 시각적 개체가 공개적으로 승인되지 않았거나 디버그 시각적 개체가 아닙니다.

  • 시각적 개체에 의해 대상 그룹으로 구성된 시각적 개체의 백 엔드 서비스는 시각적 개체를 사용하는 소비자 테넌트의 Graph API에 대한 적절한 동의가 없습니다. 동의에 대한 자세한 내용은 테넌트 관리자 동의를 참조하세요.

관련 콘텐츠

Microsoft Entra ID 애플리케이션 설정