Recursos e âmbito

A plataforma de identidade da Microsoft utiliza um modelo centrado nos âmbitos para aceder aos recursos. Aqui, um recurso refere-se a qualquer aplicação que possa ser destinatária de um Access Token (como a MS Graph API ou a sua própria web API), e um scope (também conhecido como "permissão") refere-se a qualquer aspeto de um recurso a que um Access Token conceda direitos.

Os pedidos de Token de Acesso em MSAL.js foram concebidos para ser por recurso e por âmbito(s). Isto significa que um token de acesso solicitado para o recurso A com o âmbito scp1:

  • não pode ser usado para aceder ao recurso A com âmbito scp2, e,
  • não pode ser usado para aceder ao recurso B de qualquer escopo.

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

Miras padrão

Por defeito, o MSAL.js adiciona os âmbitos openid, profile e offline_access a cada pedido. Estes escopos são necessários para receber um token de atualização e as reivindicações do id token são usadas para preencher o objeto da conta com a informação do utilizador.

Trabalhar com múltiplos recursos

Quando tiver de aceder a múltiplos recursos, inicie um pedido de token separado 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 pode pedir múltiplos escopos para o mesmo recurso (por exemplo, User.Read, User.Write e Calendar.Read para o MS Graph API).

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

Caso passe erroneamente vários recursos no seu pedido de token, o token que 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" ]
});

No Microsoft Entra ID, os scopes (permissões) definidos diretamente no registo da aplicação são chamados de scopes estáticos. Outros escopos que só são definidos dentro do código são chamados escopos dinâmicos. Isto tem implicações nos métodos de 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 excerto de código acima, o utilizador será solicitado a dar consentimento assim que se autenticar e receber um ID Token e um Access Token com o âmbito User.Read. Mais tarde, se solicitarem um Access Token para User.Read, não lhes será pedido novamente consentimento (ou seja, podem adquirir um token silenciosamente).

Por outro lado, o utilizador não consentiu em Mail.Read na fase de autenticação e, por isso, ser-lhe-á pedido o consentimento ao solicitar um Access Token para o âmbito 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 excerto de código acima, embora o utilizador dê o seu consentimento para ambos os âmbitos User.Read e api://<myCustomApiClientId>/My.Scope, só receberá um token de acesso para a API do Microsoft Graph, de acordo com o princípio de um âmbito por recurso. No entanto, como já deram o seu consentimento para api://<myCustomApiClientId>/My.Scope, podem obter um Access Token para esse recurso/âmbito de forma silenciosa mais tarde.

No Microsoft Entra ID, o consentimento existe para além da duração da aplicação. Isto significa que, quando solicita um Access Token para um recurso, serão devolvidos todos os âmbitos aos quais deu previamente o seu consentimento para esse recurso, independentemente do âmbito que tiver sido solicitado nesse momento. Ou seja, se consentir com User.Read e Mail.Read hoje e executar uma nova instância da sua aplicação amanhã solicitando apenas um Access TokenUser.Read, continuará a receber um token emitido para ambosUser.Read e Mail.Read. Para mais informações, consulte Permissões e Consentimento.

  • Last updated on