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 comutador global. A configuração padrão bloqueia (desabilita) a API.

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

Ambientes compatíveis

Os ambientes a seguir são suportados:

  • Web
  • Área de trabalho
  • Desktop do RS
  • Dispositivos móveis

Ambientes sem suporte

Os seguintes ambientes ainda não têm suporte:

  • Nuvens soberanas
  • Serviço do RS
  • Análise integrada
  • Teams

Como usar a API de Autenticação

No arquivo capabilities.json, adicione o privilégio "AADAuthentication" com o URI do aplicativo registrado do Microsoft Entra ID. O Fabric gerará um token com esse público-alvo e o entregará ao visual.
Em seguida, o visual pode utilizar o token para autenticar-se no público-alvo https://contoso.com, representando seu serviço de back-end:

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

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

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

  • acquireAADToken: retorna um conteúdo de token de autenticação do tipo AcquireAADTokenResult para o visual ou nulo se não puder ser buscado.

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

  • acquireAADTokenstatus: retorna um dos seguintes status de privilégio associados à aquisição do token.

    • Allowed: 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 tem suporte no ambiente atual.
    • DisabledByAdmin: o administrador do Fabric negou o uso de privilégios.

O código de exemplo a seguir demonstra como adquirir um token do Microsoft Entra ID 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 token será bloqueada se qualquer uma das seguintes condições se aplicar

  • O comutador do locatário está desativado.

  • O usuário não está conectado (no desktop).

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

  • O formato do parâmetro de privilégio AADAuthentication é 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-alvo pelo visual, não tem consentimentos apropriados para a API do Graph no locatário do consumidor usando o visual. Para obter mais informações sobre consentimentos, consulte consentimento do administrador do locatário.

Conteúdo relacionado

Configuração do aplicativo Microsoft Entra ID