API de autenticação

  • Artigo

A API de Autenticação permite que os visuais obtenham tokens de acesso do Microsoft Entra ID (anteriormente conhecido como Azure AD) para usuários conectados, facilitando a autenticação de logon único.

Os administradores do Power BI podem habilitar ou desabilitar a API por meio de um switch global. A configuração padrão bloqueia (desabilita) a API.

A API é aplicável apenas para visuais do AppSource, e não para visuais privados. Os elementos visuais que estão em desenvolvimento podem ser testados no modo de depuração antes de serem publicados.

Ambientes suportados

Os seguintes ambientes são suportados:

  • Web
  • Ambiente de Trabalho
  • Área de trabalho RS
  • Móvel

Ambientes sem suporte

Os seguintes ambientes ainda não são suportados:

  • Serviço RS
  • Análise incorporada
  • Teams

Como usar a API de autenticação

No arquivo capabilities.json, adicione o privilégio "AADAuthentication" com um URI de aplicativo registrado no Microsoft Entra ID para cada nuvem suportada. O Fabric gera um token de acordo com o público configurado para a nuvem atual e o entrega para o visual.
O visual pode então utilizar o token para autenticar contra o respetivo público, representando seu serviço de back-end:

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

No arquivo pbiviz.json, defina a versão da API como 5.9.1 ou superior:

O recém-exposto AcquireAADTokenService contém dois métodos:

  • acquireAADToken: retorna uma carga de token de autenticação do tipo AcquireAADTokenResult visual ou null se não puder ser buscada.

     /**
 * 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: retorna um dos seguintes status de privilégio associados à aquisição do token.

    • Permitido: o privilégio é permitido no ambiente atual.
    • NotDeclared: A declaração de privilégio está ausente na seção de recursos visuais.
    • NotSupported: O privilégio não é suportado no ambiente atual.
    • DisabledByAdmin: O administrador da malha negou o uso de privilégios.

O código de exemplo a seguir demonstra como adquirir um token de ID do Microsoft Entra usando a API:

    // 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

Considerações e limitações

A aquisição de tokens é bloqueada se qualquer uma das seguintes condições se aplicar:

  • O interruptor do inquilino está desligado.

  • O usuário não está conectado (na área de trabalho).

  • O ISV não pré-autorizou o aplicativo Power BI.

  • O formato do parâmetro AADAuthentication privilege é inválido.

  • O visual não é aprovado publicamente ou não é um visual de depuração.

  • O serviço de back-end do visual, configurado como o público pelo visual, não tem consentimentos apropriados para a API do Graph no locatário consumidor que usa o visual. Para obter mais informações sobre consentimento, consulte Consentimento do administrador do locatário.

Conteúdos relacionados

Configuração do aplicativo Microsoft Entra ID