API JavaScript de autenticação

Artigo
11/11/2024

O front-end do Fabric oferece uma API JavaScript para as cargas de trabalho do Fabric, que visam adquirir um token para o aplicativo no Microsoft Entra ID. Este artigo descreve essa API.

API

acquireAccessToken(params: AcquireAccessTokenParams): Promise<AccessToken>;  
export interface AcquireAccessTokenParams {
    additionalScopesToConsent?: string[];  
    claimsForConditionalAccessPolicy?: string;
    promptFullConsent?: boolean;
}

A API retorna um objeto AccessToken que contém o próprio token e uma data de expiração para o token.

Para chamar a API no exemplo de Front-end, crie um item de amostra e, em seguida, role para baixo e selecione Navegar até a página de autenticação. A partir daí, você poderá selecionar Obter token de acesso para receber um token de volta.

Captura de tela mostrando a seção de autenticação.

Consentimentos

Para entender por que os consentimentos são necessários, consulte Consentimento do usuário e do administrador no Microsoft Entra ID.

Observação

Os consentimentos são necessários para que o CRUD/Jobs funcione e para adquirir tokens entre os locatários.

Como os consentimentos funcionam nas cargas de trabalho do Fabric?

Para conceder um consentimento para um aplicativo específico, o Fabric FE cria uma instância MSAL configurada com a ID do aplicativo da carga de trabalho e solicita um token para os escopos fornecidos (additionalScopesToConsent - consulte AcquireAccessTokenParams).

Ao solicitar um token com o aplicativo de carga de trabalho para um escopo específico, o Microsoft Entra ID exibe um consentimento pop-up caso ele esteja ausente e, em seguida, redireciona a janela pop-up para o URI de redirecionamento configurado no aplicativo.

Normalmente, o URI de redirecionamento está no mesmo domínio da página que solicitou o token, para que a página possa acessar o pop-up e fechá-lo.

Nesse caso, ele não está no mesmo domínio, pois o Fabric está solicitando o token, e o URI de redirecionamento da carga de trabalho não está no domínio do Fabric. Portanto, quando a caixa de diálogo de consentimento é aberta, ela precisa ser fechada manualmente após o redirecionamento. Não usamos o código retornado no redirectUri, portanto, apenas o fechamos automaticamente (quando o Microsoft Entra ID redireciona o pop-up para o URI de redirecionamento, ele simplesmente fecha).

Você pode ver o código/configuração do URI de redirecionamento no arquivo index.ts.

Aqui está um exemplo de um pop-up de consentimento para o aplicativo "meu aplicativo de carga de trabalho" e suas dependências (armazenamento e Power BI) que configuramos ao passar pela configuração de autenticação:

Captura de tela da caixa de diálogo das permissões necessárias.

Outra forma de conceder consentimentos no locatário inicial (opcional)

Para obter um consentimento no locatário inicial do aplicativo, peça ao administrador do locatário que conceda um consentimento para todo o locatário usando uma URL no seguinte formato (insira sua própria ID de locatário e a ID do cliente):

https://login.microsoftonline.com/{tenantId}/adminconsent?client_id={clientId}

AcquireAccessTokenParams

Ao chamar a API JS acquireAccessToken, podemos fornecer três parâmetros:

additionalScopesToConsent: outros escopos para solicitar um consentimento, por exemplo, cenários de novo consentimento.
claimsForConditionalAccessPolicy: declarações retornadas do Microsoft Entra ID quando os fluxos OBO falham, por exemplo, o OBO requer autenticação multifator.
promptFullConsent: solicita uma janela de consentimento total das dependências estáticas do aplicativo de cargas de trabalho.

additionalScopesToConsent

Se o front-end da carga de trabalho estiver solicitando que um token seja usado para chamadas para o back-end de carga de trabalho, esse parâmetro deverá ser nulo. O back-end da carga de trabalho pode falhar ao executar o OBO no token recebido devido a um erro de consentimento ausente, nesse caso, o back-end da carga de trabalho precisará propagar o erro para o front-end da carga de trabalho e fornecer esse parâmetro.

claimsForConditionalAccessPolicy

Esse parâmetro é usado quando ocorrerem falhas de OBO na carga de trabalho BE devido a alguma política de acesso condicional que tenha sido configurada no locatário.

O OBO falha devido a políticas de acesso condicional que retornam uma string chamada "claims". Essa cadeia de caracteres deve ser enviada para o FE da carga de trabalho, onde o FE deve solicitar um token e passar a declaração como claimsForConditionalAccessPolicy. Para obter mais informações, consulte Administrar a autenticação multifator (MFA), o acesso condicional e o consentimento incremental.

Consulte o uso do AddBearerClaimToResponse em AuthenticationService na amostra de BE para ver exemplos de respostas quando as operações OBO falharem devido a políticas de acesso condicional ou à ausência de consentimento.

Para saber mais sobre esse additionalScopesToConsent e claimsForConditionalAccessPolicy e ver exemplos de uso, consulte diretrizes de autenticação de carga de trabalho e aprofundamento.

promptFullConsent

Quando passado como true, um consentimento total das dependências estáticas será exibido para o usuário, independentemente de ele ter fornecido um consentimento anteriormente ou não. Um exemplo de uso para esse parâmetro é adicionar à UX um botão que o usuário pode usar para conceder consentimento total à carga de trabalho.

Compartilhar via