API JavaScript de autenticação

Artigo
11/11/2024

O front-end do Fabric oferece uma API JavaScript para cargas de trabalho do Fabric para adquirir um token para seu aplicativo no Microsoft Entra ID. Este artigo descreve esta 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 Frontend, crie um item de exemplo e, em seguida, role para baixo e selecione Navegar até a página Autenticação. A partir daí, você pode 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 o consentimento do usuário e do administrador no Microsoft Entra ID.

Nota

São necessários consentimentos para que o CRUD/Jobs funcione e adquira tokens entre locatários.

Como funcionam os consentimentos em cargas de trabalho do Fabric?

Para conceder um consentimento para um aplicativo específico, o Fabric FE cria uma instância MSAL configurada com o 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.

No nosso caso, ele não está no mesmo domínio, já que 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 nosso 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 Permissões necessárias.

Outra forma de conceder consentimentos no inquilino da casa (opcional)

Para obter um consentimento no inquilino inicial da aplicação, pode pedir ao administrador do inquilino que conceda um consentimento para todo o inquilino utilizando um URL no seguinte formato (insira o seu próprio ID de inquilino e o 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 os quais solicitar um consentimento, por exemplo, cenários de reconsentimento.
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 completo das dependências estáticas do aplicativo de cargas de trabalho.

adicionalEscoposToConsentimento

Se o front-end da carga de trabalho estiver solicitando um token a ser usado para chamadas para o back-end da 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 falta de consentimento, nesse caso, o back-end da carga de trabalho precisará propagar o erro para o frontend da carga de trabalho e fornecer esse parâmetro.

claimsForConditionalAccessPolicy

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

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

Consulte o uso de AuthenticationService AddBearerClaimToResponse no exemplo BE para ver exemplos de respostas quando as operações OBO falham devido a políticas de consentimento ausente ou de acesso condicional.

Para saber mais sobre esse adicionalScopesToConsent e claimsForConditionalAccessPolicy e ver exemplos de uso, consulte Diretrizes de autenticação de carga de trabalho & deep dive.

promptConsentimento Completo

Quando passado como verdadeiro, um consentimento total das dependências estáticas aparecerá para o usuário, independentemente de ele ter fornecido um consentimento anteriormente ou não. Um exemplo de uso para esse parâmetro é adicionar um botão à experiência do usuário onde o usuário pode usá-lo para conceder consentimento total à carga de trabalho.

Partilhar via