Aquisição e utilização de um token de acesso

Antes de adquirir um token de acesso, certifique-se de que compreende como inicializar o objeto da aplicação. É também crucial compreender a relação entre os tokens de acesso e os recursos.

No MSAL, pode obter tokens de acesso para as APIs que a sua aplicação precisa de invocar usando os acquireToken* métodos fornecidos pela biblioteca. Os acquireToken* métodos abstraem os 2 passos envolvidos na aquisição de tokens com o fluxo de código de autorização OAuth 2.0:

  1. faça um pedido ao Microsoft Entra ID para obter umauthorization code
  2. Troque esse código por um token de acesso contendo os escopos consentidos pelo utilizador

Aquisição de um Token de Acesso

Escolha um tipo de interação

Veja aqui se tiver dúvidas sobre as diferenças entre acquireTokenRedirect e acquireTokenPopup.

Preparar o objeto de pedido

Tem de passar um objeto de solicitação para as APIs acquireToken*. Este objeto permite-lhe usar diferentes parâmetros no pedido. Veja aqui para mais informações sobre os parâmetros do objeto de pedido. São necessárias telescópias para todas acquireToken* as chamadas.

Verifica a cache

O MSAL utiliza uma cache para armazenar tokens com base em parâmetros específicos, incluindo escopos, recursos e autoridade, e recupera o token da cache quando necessário. Também pode realizar a renovação silenciosa desses tokens quando estes expiraram. O MSAL expõe esta funcionalidade através do acquireTokenSilent método.

Depois de iniciar sessão com uma das APIs ssoSilent ou login*, a memória cache conterá um conjunto de tokens de ID, de acesso e de atualização. Sempre que precisares de um token de acesso deves ligar acquireTokenSilent e, se falhar, chamar uma API interativa em vez disso. acquireTokenSilent Vou procurar um token válido na cache e, se estiver perto de expirar ou não existir, tentará atualizá-lo automaticamente para ti usando o token de atualização em cache. Pode ler mais sobre o uso acquireTokenSilentaqui.

var request = {
    scopes: ["User.Read"],
};

msalInstance.acquireTokenSilent(request).then(tokenResponse => {
    // Do something with the tokenResponse
}).catch(async (error) => {
    if (error instanceof InteractionRequiredAuthError) {
        // fallback to interaction when silent call fails
        return msalInstance.acquireTokenPopup(request);
    }

    // handle other errors
})

Redirect

var request = {
    scopes: ["User.Read"],
};

msalInstance.acquireTokenSilent(request).then(tokenResponse => {
    // Do something with the tokenResponse
}).catch(error => {
    if (error instanceof InteractionRequiredAuthError) {
        // fallback to interaction when silent call fails
        return msalInstance.acquireTokenRedirect(request)
    }

    // handle other errors
});

Utilização do Token de Acesso

Depois de obter o token de acesso, deve incluí-lo no cabeçalho Authorization como um bearer token no pedido ao recurso para o qual obteve o token, conforme mostrado abaixo:

var headers = new Headers();
var bearer = "Bearer " + tokenResponse.accessToken;
headers.append("Authorization", bearer);
var options = {
        method: "GET",
        headers: headers
};
var graphEndpoint = "https://graph.microsoft.com/v1.0/me";

fetch(graphEndpoint, options)
    .then(resp => {
        //do something with response
    });

Melhores práticas para aquisição de tokens MSAL

Seguem-se as melhores práticas para adquirir tokens com MSAL para evitar erros, impactos de desempenho e problemas de usabilidade. Certos cenários podem oferecer exceções a estes.

Usar uma única instância PublicClientApplication

Instaure uma PublicClientApplication por aplicação e use a mesma instância em toda a sua aplicação. Isto garante que existe uma única fonte de verdade sobre o que o MSAL está a executar em qualquer momento (ver: eventos MSAL) e elimina a possibilidade de objetos distintos da aplicação fazerem pedidos interativos paralelos ou potenciais conflitos de cache, que podem quebrar as aplicações, reduzir o desempenho ou prejudicar a experiência do utilizador.

Espera sempre que as promessas se resolvam

Todos os MSAL acquireToken* e login* APIs realizam operações assíncronas e promessas de devolução. Deve sempre esperar que estas promessas se resolvam antes de realizar quaisquer outras tarefas que dependam do estado de autenticação ou de tokens, como renderizar informação do utilizador, chamar uma API protegida ou chamar outras APIs MSAL.

Tente primeiro o pedido silencioso, depois o interativo

Ao solicitar tokens, utilize sempre primeiro acquireTokenSilent, recorrendo à obtenção interativa de tokens, se necessário (por exemplo, quando for gerada a exceção InteractionRequiredAuthError).

São permitidas solicitações silenciosas em simultâneo. Se dois ou mais pedidos silenciosos forem feitos em simultâneo, apenas um irá para a rede (se necessário), mas todos receberão a resposta, desde que esses pedidos sejam para os mesmos parâmetros de pedido (por exemplo, escopos).

Não são permitidos pedidos interativos simultâneos. Se dois ou mais pedidos interativos forem feitos em simultâneo, apenas o primeiro iniciará uma interação, enquanto os restantes falharão com interaction_in_progress erro. Recomendamos familiarizar-se com este erro e com possíveis soluções para evitar que o encontre nas suas aplicações.

Faça um pedido de token por recurso

Só pode pedir tokens de acesso para um recurso de cada vez (ver recursos e escopos). Se necessário, pode pedir consentimento do utilizador para os escopos (permissões) exigidos por mais do que um recurso usando o extraScopesToConsent parâmetro no objeto de pedido. Os tokens de acesso para escopos previamente consentidos podem ser adquiridos silenciosamente.

Próximas Etapas

  • Last updated on