Adquirir e usar um token de acesso

Antes de adquirir um token de acesso, certifique-se de entender como inicializar o objeto do aplicativo. Também é crucial entender a relação entre tokens de acesso e recursos.

Na MSAL, você pode obter tokens de acesso para as APIs que seu aplicativo precisa chamar usando os acquireToken* métodos fornecidos pela biblioteca. Os acquireToken* métodos abstraem as 2 etapas envolvidas na aquisição de tokens com o fluxo de código de autorização do OAuth 2.0:

  1. fazer uma solicitação para o Microsoft Entra ID para obter um authorization code
  2. trocar esse código por um token de acesso que contém os escopos consentidos pelo usuário

Adquirindo um token de acesso

Escolher um tipo de interação

Veja aqui se você está incerto sobre as diferenças entre acquireTokenRedirect e acquireTokenPopup.

Preparar o objeto de solicitação

Você deve passar um objeto de solicitação para as acquireToken* APIs. Esse objeto permite que você use parâmetros diferentes na solicitação. Veja aqui mais informações sobre os parâmetros de objeto de solicitação. Escopos são necessários em todas as chamadas acquireToken*.

Verificar o cache

A MSAL usa um cache para armazenar tokens com base em parâmetros específicos, incluindo escopos, recurso e autoridade, e recuperará o token do cache quando necessário. Ele também pode executar a renovação silenciosa desses tokens quando eles expirarem. A MSAL expõe essa funcionalidade por meio do acquireTokenSilent método.

Depois de fazer login com uma das APIs ssoSilent ou login*, o cache conterá um conjunto de tokens de ID, acesso e renovação. Sempre que você precisar de um token de acesso, você deve chamar acquireTokenSilent e, se isso falhar, chame uma API interativa. acquireTokenSilent procurará um token válido no cache e, se ele estiver perto de expirar ou não existir, tentará atualizá-lo automaticamente para você usando o token de atualização armazenado em cache. Você pode ler mais sobre como usar 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
})

Redirecionar

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
});

Usando o Token de Acesso

Depois de recuperar o token de acesso, você deve incluí-lo no cabeçalho Authorization como um token do portador na solicitação ao recurso para o qual você 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
    });

Práticas recomendadas de aquisição de token MSAL

A seguir estão as práticas recomendadas para adquirir tokens com o MSAL, evitando erros, impactos no desempenho e problemas de usabilidade. Determinados cenários podem fornecer exceções a esses cenários.

Usar uma única instância de PublicClientApplication

Instancie um PublicClientApplication por aplicativo e use a mesma instância em todo o aplicativo. Isso garante que haja uma única fonte de verdade para o que a MSAL está executando a qualquer momento (veja: eventos MSAL) e elimina a chance de objetos de aplicativo distintos fazerem solicitações interativas paralelas ou possíveis conflitos de cache, o que pode interromper aplicativos, reduzir o desempenho ou dificultar a experiência do usuário.

Sempre aguarde até que as promessas sejam resolvidas

Todas as APIs MSAL acquireToken*, bem como as APIs login*, executam operações assíncronas e retornam promessas. Você sempre deve esperar que essas promessas sejam resolvidas antes de realizar outras tarefas que dependam do estado de autenticação ou tokens, como renderizar informações do usuário, chamar uma API protegida ou chamar outras APIs MSAL.

Tente a solicitação silenciosa primeiro e, em seguida, interativa

Ao solicitar tokens, sempre use acquireTokenSilent primeiro, voltando à aquisição interativa de token, se necessário (por exemplo, quando ele InteractionRequiredAuthError é lançado).

Solicitações silenciosas simultâneas são permitidas. Se duas ou mais solicitações silenciosas forem feitas simultaneamente, apenas uma iria para a rede (se necessário), mas todas receberiam a resposta, desde que essas solicitações sejam para os mesmos parâmetros de solicitação (por exemplo, escopos).

Solicitações interativas simultâneas não são permitidas. Se duas ou mais solicitações interativas forem feitas simultaneamente, somente a primeira iniciará uma interação, enquanto o restante falhará com interaction_in_progress erro. Recomendamos que você se familiarize com esse erro e com as possíveis formas de corrigi-lo para evitar se deparar com ele em seus aplicativos.

Fazer uma solicitação de token por recurso

Você só pode solicitar tokens de acesso para um recurso por vez (consulte recursos e escopos). Se necessário, você pode solicitar consentimento do usuário para escopos (permissões) exigidos por mais de um recurso usando o extraScopesToConsent parâmetro no objeto de solicitação. Os tokens de acesso para escopos consentidos anteriormente podem ser adquiridos silenciosamente.

Próximas etapas

  • Last updated on