Recursos e escopos

A plataforma de identidade da Microsoft emprega um modelo centrado no escopo para acessar recursos. Aqui, um recurso refere-se a qualquer aplicativo que possa ser um destinatário de um Token de Acesso (como MS API do Graph ou sua própria API Web) e um escopo (também conhecido como "permissão") refere-se a qualquer aspecto de um recurso que um Token de Acesso concede direitos.

Solicitações de token de acesso em MSAL.js devem ser feitas por recurso e por escopo. Isso significa que um Token de Acesso solicitado para o recurso A com escopo scp1:

  • não pode ser usado para acessar o recurso A com escopo scp2e,
  • não pode ser usado para acessar o recurso B de qualquer escopo.

O destinatário pretendido de um Token de Acesso é representado pela aud declaração; caso o valor da aud declaração não corresponda ao URI da ID do APLICATIVO de recurso, o token deve ser considerado inválido. Da mesma forma, as permissões concedidas por um Token de Acesso são representadas pela declaração scp . Confira as declarações do Token de Acesso para obter mais informações.

Escopos padrão

Por padrão, o MSAL.js adicionará os escopos openid, profile e offline_access a cada solicitação. Esses escopos são necessários para receber um token de atualização e as declarações de token de ID usadas para preencher o objeto da conta com as informações do usuário.

Trabalhando com vários recursos

Quando você tiver que acessar vários recursos, inicie uma solicitação de token separada para cada um:

// "User.Read" stands as shorthand for "graph.microsoft.com/User.Read"
const graphToken = await msalInstance.acquireTokenSilent({
     scopes: [ "User.Read" ]
});
const customApiToken = await msalInstance.acquireTokenSilent({
     scopes: [ "api://<myCustomApiClientId>/My.Scope" ]
});

Tenha em mente que você pode solicitar vários escopos para o mesmo recurso (por exemploUser.Read, User.Write e Calendar.Read para ms API do Graph).

const graphToken = await msalInstance.acquireTokenSilent({
     scopes: [ "User.Read", "User.Write", "Calendar.Read" ] // all MS Graph API scopes
});

Caso você passe erroneamente vários recursos em sua solicitação de token, o token que você receberá será emitido apenas para o primeiro recurso.

// you will only receive a token for MS GRAPH API's "User.Read" scope here
const myToken = await msalInstance.acquireTokenSilent({
     scopes: [ "User.Read", "api://<myCustomApiClientId>/My.Scope" ]
});

Em Microsoft Entra ID, os escopos (permissões) definidos diretamente no registro do aplicativo são chamados de escopos estáticos. Outros escopos definidos somente dentro do código são chamados de escopos dinâmicos. Isso tem implicações nos métodos login (ou seja, loginPopup, loginRedirect) e acquireToken (ou seja, acquireTokenPopup, acquireTokenRedirect, acquireTokenSilent) de MSAL.js. Considere:

 const loginRequest = {
      scopes: [ "openid", "profile", "User.Read" ]
 };
 const tokenRequest = {
      scopes: [ "Mail.Read" ]
 };
 // will return an ID Token and an Access Token with scopes: "openid", "profile" and "User.Read"
 msalInstance.loginPopup(loginRequest);
 // will fail and fallback to an interactive method prompting a consent screen
 // after consent, the received token will be issued for "openid", "profile" ,"User.Read" and "Mail.Read" combined
 msalInstance.acquireTokenSilent(tokenRequest);

No snippet de código acima, o usuário será solicitado a dar seu consentimento assim que se autenticar e receber um token de ID e um token de acesso com o escopo User.Read. Posteriormente, se solicitarem um TokenUser.Readde Acesso, eles não serão solicitados a consentir novamente (em outras palavras, eles podem adquirir um token silenciosamente).

Por outro lado, o usuário não deu consentimento para Mail.Read na etapa de autenticação; portanto, será solicitado a fornecer consentimento ao solicitar um Token de Acesso para o escopo Mail.Read. O token recebido conterá todos os escopos previamente consentidos (para esse recurso específico), daí o termo consentimento incremental.

Considere um caso ligeiramente diferente:

 const loginRequest = {
      scopes: [ "openid", "profile", "User.Read" ],
      extraScopesToConsent: [ "api://<myCustomApiClientId>/My.Scope"]
 };
 const tokenRequest = {
      scopes: [ "Mail.Read" ]
 };
 const anotherTokenRequest = {
      scopes: [ "api://<myCustomApiClientId>/My.Scope" ]
 }
 // will return an ID Token and an Access Token with scopes: "openid", "profile" and "User.Read"
 msalInstance.loginPopup(loginRequest);
 // will fail with InteractionRequiredError due to lack of consent for "Mail.Read" scope. You should fallback to an interactive method in this case.
 msalInstance.acquireTokenSilent(tokenRequest);
 // will succeed and return an Access Token with scope "api://<myCustomApiClientId>/My.Scope"
 msalInstance.acquireTokenSilent(anotherTokenRequest);

No trecho de código acima, embora o usuário consinta com os escopos User.Read e api://<myCustomApiClientId>/My.Scope, ele receberá apenas um Token de Acesso para a API do MS Graph, de acordo com o princípio por recurso e por escopo. No entanto, como já deram consentimento a api://<myCustomApiClientId>/My.Scope, podem obter um Token de Acesso para esse recurso/escopo de forma silenciosa posteriormente.

Em Microsoft Entra ID, o consentimento vive além do tempo de vida do aplicativo. Isso significa que, quando você solicita um Token de Acesso para um recurso, todos os escopos que você consentiu anteriormente para esse recurso serão retornados, independentemente de qual escopo foi solicitado na época. Em outras palavras, se você consentir com User.Read e Mail.Read hoje e executar uma nova instância da sua aplicação amanhã, solicitando um token de acesso apenas para User.Read, você ainda receberá um token emitido para ambosUser.Read e Mail.Read. Para obter mais informações, consulte Permissões e Consentimento.

  • Last updated on