Atualização das permissões solicitadas de um aplicativo no Microsoft Entra ID

Ao configurar um aplicativo do Microsoft Entra ID, os desenvolvedores podem solicitar acesso a dados de outros aplicativos e serviços usando permissões. Eles podem solicitar permissões adicionando permissões estáticas ao manifesto do aplicativo ou solicitando permissões dinamicamente em runtime. Os usuários ou administradores podem então optar por conceder permissões de acesso durante o consentimento, permitindo que o aplicativo acesse os dados de que precisa.

À medida que a funcionalidade de um aplicativo evolui, os recursos aos quais ele requer acesso também são alterados. Essas alterações podem envolver a habilitação de novos recursos, a eliminação de acessos desnecessários ou a substituição de permissões altamente privilegiadas por outras menos privilegiadas. Este artigo explica como atualizar as permissões de acesso que seu aplicativo solicita usando o centro de administração do Microsoft Entra e as chamadas à API do Microsoft Graph.

Atualizar as permissões de acesso do seu aplicativo não é apenas uma melhor prática de segurança, mas também uma forma de melhorar a experiência e a adoção do usuário do seu aplicativo. A seção a seguir descreve alguns dos benefícios de atualizar as permissões de acesso ao seu aplicativo:

• Se seu aplicativo tiver uma nova funcionalidade, você poderá solicitar mais permissões que habilitem o aplicativo a acessar os recursos extras necessários.
• É mais provável que os clientes adotem seu aplicativo se ele solicitar apenas as permissões de acesso menos privilegiadas necessárias para funcionar. Isso mostra que seu aplicativo respeita a privacidade e a proteção de dados do cliente e não acessa mais recursos do que o necessário.
• Além disso, se seu aplicativo estiver comprometido, o raio de explosão será menor se ele tiver menos permissões ou permissões menos privilegiadas. Isso significa que o invasor tem menos acesso aos dados e recursos do cliente e, portanto, o potencial de dano é reduzido.
• Ao atualizar as permissões do seu aplicativo, é possível melhorar a segurança, a usabilidade e a conformidade do aplicativo, além de criar uma relação de confiança com seus clientes.

Pré-requisitos

Para atualizar as permissões solicitadas de acesso de um aplicativo, você precisará:

• Uma conta de usuário do Microsoft Entra. Caso ainda não tenha, Crie uma conta gratuita.
• Uma das seguintes funções: Administrador de Aplicativos, Administrador de Aplicativos na Nuvem. Um proprietário de aplicativo que não seja um administrador pode atualizar as permissões de acesso solicitadas de um aplicativo.

Cenários para a atualização das permissões de acesso

A seção a seguir lista os três principais cenários em que é necessário atualizar as permissões de acesso solicitadas pelo aplicativo:

• Adicionar permissões de acesso a um aplicativo
• Remover as permissões de acesso não utilizadas de um aplicativo
• Substituir uma permissão

Observação

As atualizações das permissões solicitadas para o seu aplicativo não concedem ou revogam automaticamente acesso aos recursos protegidos. Seus clientes, ou os administradores da sua organização, precisam dar consentimento às novas permissões adicionadas ou revogar manualmente as permissões.

Adicionar permissões de acesso a um aplicativo

Você pode adicionar uma permissão se seu aplicativo tiver uma nova funcionalidade que precise de uma permissão que não precisava antes.

A melhor prática é solicitar acesso apenas às permissões mínimas de que seu aplicativo precisa para funcionar. Se precisar adicionar uma nova permissão para dar suporte a uma nova funcionalidade no seu aplicativo, solicite apenas a permissão com privilégio mínimo para esse recurso. Por exemplo, para adicionar um recurso de notificação por email ao seu aplicativo, ele precisa acessar os emails dos usuários. Para isso, você precisaria solicitar acesso para a permissão Mail.ReadWrite.

Adicionar permissões de acesso ao consentimento estático

O consentimento estático é uma maneira de solicitar permissões de acesso de usuários ou administradores no momento do registro de um aplicativo, ao invés de em runtime. O consentimento estático requer que o aplicativo declare todas as permissões de que precisa no painel Registros de aplicativo no centro de administração do Microsoft Entra. Usando o centro de administração do Microsoft Entra, você só pode atualizar permissões de acesso para consentimento estático. Para obter mais informações sobre os diferentes tipos de consentimento, confira Tipos de consentimento. Para saber como atualizar as permissões de acesso para o consentimento dinâmico, confira a guia Microsoft Graph deste artigo.

Nesta seção, saiba como adicionar permissões de acesso ao consentimento estático.

Você pode adicionar permissões de acesso ao consentimento estático de duas maneiras diferentes no centro de administração do Microsoft Entra:

Opção 1: adicionar permissões no painel de permissões de API

1. Conecte-se ao centro de administração do Microsoft Entra como, no mínimo, Administrador de Aplicativos de Nuvem ou proprietário do aplicativo.
2. Navegue até Identidade>Aplicativos>Registros de aplicativo>Todos os aplicativos.
3. Encontre o registro do aplicativo ao qual deseja adicionar as permissões de acesso e selecione-o. Você pode adicionar permissões de acesso de duas maneiras diferentes:
4. Adicione permissões no painel permissões de API.

   1. Localize o painel permissões de API e selecione Adicionar uma permissão.

   2. Selecione a API que deseja acessar e a permissão que deseja solicitar na lista de opções disponíveis e selecione Adicionar permissões.

      

Opção 2: adicionar permissões de acesso ao manifesto do aplicativo

1. No painel de navegação esquerdo, no grupo de gerenciamento Gerenciar, selecione Manifesto. A seleção abre um editor que permite editar diretamente os atributos do objeto de registro do aplicativo.
2. Edite cuidadosamente a propriedade requiredResourceAccess no arquivo de manifesto do aplicativo.
3. Adicione a propriedade resourceAppId e a propriedade resourceAccess e atribua as permissões de acesso necessárias.
4. Salve suas alterações.

Para executar as etapas seguintes de adição de permissões de acesso, você precisará dos seguintes recursos e privilégios:

• Execute as solicitações HTTP em uma ferramenta de sua escolha, por exemplo, em seu aplicativo ou por meio do Explorador do Graph.
• Execute as APIs como um usuário com pelo menos Administrador de Aplicativo de Nuvem, ou como proprietário do registro do aplicativo de destino.
• O aplicativo utilizado para fazer essas alterações deve receber a permissão Application.ReadWrite.All.

1. Identifique as permissões que seu aplicativo requer, suas IDs de permissão e se são funções de aplicativo (permissões de aplicativo) ou permissões delegadas. Por exemplo, se desejar solicitar permissões do Microsoft Graph, confira Permissões do Microsoft Graph para obter uma lista de permissões e suas IDs.

2. Adicione as permissões necessárias do Microsoft Graph no seu aplicativo. O exemplo a seguir chama a API de Atualização de Aplicativo para adicionar as permissões de acesso necessárias do Microsoft Graph a um registro de aplicativo identificado pela ID de objeto aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb. Este exemplo usa a permissão delegada Analytics.Read e Application.Read.All e a permissão do aplicativo. O Microsoft Graph é identificado como um objeto ServicePrincipal com 00000003-0000-0000-c000-000000000000 como seu AppId globalmente exclusivo.

   PATCH https://graph.microsoft.com/v1.0/applications/aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb
   Content-Type: application/json
    {
        "requiredResourceAccess": [
            {
                "resourceAppId": "00000003-0000-0000-c000-000000000000",
                "resourceAccess": [
                    {
                        "id": "e03cf23f-8056-446a-8994-7d93dfc8b50e",
                        "type": "Scope"
                    },
                    {
                        "id": "9a5d68dd-52b0-4cc2-bd40-abcf44ac3a30",
                        "type": "Role"
                    }
                ]
            }
        ]
    }
   

Adicionar permissões de acesso ao consentimento dinâmico

O consentimento dinâmico é uma forma de solicitar permissões de acesso de usuários ou administradores em runtime, ao invés de declará-las estaticamente no painel Registros de aplicativo. O consentimento dinâmico permite que o aplicativo solicite apenas as permissões de acesso necessárias para uma funcionalidade específica e obtenha o consentimento do usuário ou do administrador quando necessário. O consentimento dinâmico pode ser usado com permissões delegadas e pode ser combinado com o escopo /.default para solicitar o consentimento do administrador para todas as permissões.

Para adicionar as permissões de acesso ao consentimento dinâmico:

• Use o Microsoft Graph: adicione as permissões necessárias do Microsoft Graph a um registro de aplicativo. Este exemplo usa a permissão delegada Analytics.Read e Application.Read.All e a permissão do aplicativo. Substitua os valores em `escopos` pelos valores de quaisquer permissões delegadas do Microsoft Graph que você deseja configurar para o aplicativo.

  A solicitação deve ser como o exemplo a seguir:

  https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id=00001111-aaaa-2222-bbbb-3333cccc4444&response_type=code&scope=Analytics.Read+Application.Read

• Usar o MSAL.js: substitua os valores em `escopos` pelos valores de quaisquer permissões delegadas do Microsoft Graph que deseja configurar para o aplicativo.

    const Request = {
        scopes: ["openid", "profile"],
        loginHint: "example@domain.net"
    };
  
    myMSALObj.ssoSilent(Request)
        .then((response) => {
            // your logic
        }).catch(error => {
            console.error("Silent Error: " + error);
            if (error instanceof msal.InteractionRequiredAuthError) {
                myMSALObj.loginRedirect(loginRequest);
            }
    });
  

Dê consentimento para as permissões de acesso adicionadas ao aplicativo empresarial

Após as permissões serem adicionadas ao seu aplicativo, os usuários ou administradores precisam dar o consentimento de acesso às novas permissões. Os usuários não administradores veem um prompt de consentimento quando entram no seu aplicativo. Os usuários administradores, por outro lado, podem dar o consentimento de acesso às novas permissões em nome de todos os usuários da sua organização quando entrarem pela primeira vez no seu aplicativo ou no centro de administração do Microsoft Entra.

Quando as permissões de acesso adicionadas exigem o consentimento do administrador, as ações necessárias variam com base no tipo de aplicativo:

• Aplicativo de locatário único e aplicativo multilocatário no locatário inicial: o usuário deve entrar como pelo menos uma função de Administrador de Funções Com Privilégios e conceder consentimento em todo o locatário.
• Aplicativos de vários locatários nos locatários do cliente: o usuário vê novos prompts de consentimento na sua próxima tentativa de entrar. Se as permissões de acesso exigirem somente o consentimento do usuário, o usuário poderá dar o consentimento. Se as permissões de acesso exigirem consentimento do administrador, o usuário deverá entrar em contato com o administrador para dar o consentimento.

Interromper a solicitação de permissões de acesso não utilizadas

A remoção de permissões de acesso pode reduzir o risco de exposição de dados confidenciais ou comprometer a segurança e simplificar o processo de consentimento para seus usuários ou administradores. Se seu aplicativo não precisar mais de uma permissão, você deve impedir que ele a solicite isso removendo a permissão do código e do acesso aos recursos necessários do registro do aplicativo. Por exemplo, um aplicativo que não envia mais notificações de acesso por email pode remover a permissão Mail.ReadWrite.

Importante

A remoção de uma permissão do registro do seu aplicativo não revoga automaticamente as permissões de acesso já concedidas ao aplicativo. Você precisa revogar as permissões de acesso manualmente. Para obter mais informações, confira a seção Revogar consentimento das permissões de acesso removidas para o aplicativo empresarial deste artigo.

Pare de solicitar permissões de acesso para consentimento estático

Para parar de solicitar permissões que requerem consentimento estático, é necessário remover a permissão do painel Registros de aplicativo. Um administrador do locatário também precisa revogar a permissão no painel Aplicativos empresariais. Para obter mais informações sobre como revogar as permissões concedidas a um aplicativo empresarial, confira Revogar as permissões de acesso de um aplicativo empresarial.

Nesta seção, você aprenderá como parar de solicitar permissões de acesso para o consentimento estático.

Você pode remover as permissões de acesso de consentimento estático de duas maneiras diferentes no centro de administração do Microsoft Entra:

Opção 1: no painel permissões de API

1. Conecte-se ao centro de administração do Microsoft Entra como, no mínimo, Administrador de Aplicativos de Nuvem ou proprietário do aplicativo.
2. Navegue até Identidade>Aplicativos>Registros de aplicativo>Todos os aplicativos.
3. Encontre o registro do aplicativo do qual deseja remover as permissões e selecione-o.
4. Remover as permissões do painel de permissões de API:

   1. Localize o painel permissões de API e encontre as permissões de acesso que deseja remover.

   2. Selecione a API que deseja remover e selecione Revogar consentimento do administrador primeiro e remover permissão em seguida. Isso garante que a permissão concedida seja removida do seu locatário.

      

Opção 2: a partir do manifesto do aplicativo

1. No painel de navegação esquerdo, no grupo de gerenciamento Gerenciar, selecione Manifesto. É aberto um editor que permite editar diretamente os atributos do objeto de registro do aplicativo.
2. Edite cuidadosamente a propriedade requiredResourceAccess no arquivo de manifesto do aplicativo.
3. Remova as permissões de acesso desnecessárias da propriedade resourceAppId e da propriedade resourceAccess.
4. Salve suas alterações.

Para executar as etapas seguintes de remoção de permissões de acesso, você precisará dos seguintes recursos e privilégios:

• Execute as solicitações HTTP em uma ferramenta de sua escolha, por exemplo, em seu aplicativo ou por meio do Explorador do Graph.
• Chame as APIs como, pelo menos, um Administrador de Aplicativos de Nuvem, ou como proprietário do registro do aplicativo de destino.
• O aplicativo utilizado para fazer essas alterações deve receber a permissão Application.ReadWrite.All.

1. Identifique as permissões de acesso para seu aplicativo.

2. Por exemplo, para impedir que seu aplicativo solicite permissões do Microsoft Graph, identifique as permissões do Microsoft Graph do seu aplicativo, suas IDs de permissão e se elas são funções de aplicativo (permissões de aplicativo) ou permissões de delegadas.

3. Remova as permissões indesejadas do Microsoft Graph do seu aplicativo. O exemplo a seguir chama a API de Atualização do Aplicativo para remover as permissões indesejadas do Microsoft Graph de um registro de aplicativo identificado pela ID do cliente de exemplo 00001111-aaaa-2222-bbbb-3333cccc4444. Neste exemplo, o aplicativo tem Analytics.Read, User.Read e Application.Read.All. Precisamos remover a permissão delegada Analytics.Read e Application.Read.All e a permissão de aplicativo. O Microsoft Graph é identificado como um objeto ServicePrincipal com 00000003-0000-0000-c000-000000000000 como seu AppId globalmente exclusivo e o Microsoft Graph como seu DisplayName e AppDisplayName.

   PATCH https://graph.microsoft.com/v1.0/applications/00001111-aaaa-2222-bbbb-3333cccc4444
   Content-Type: application/json
   {
       "requiredResourceAccess": [
           {
               "resourceAppId": "00000003-0000-0000-c000-000000000000",
               "resourceAccess": [
                   {
                       "id": "311a71cc-e848-46a1-bdf8-97ff7156d8e6 ",
                       "type": "Scope"
                   }
               ]
           }
       ]
   }
   

Pare de solicitar permissões de acesso com consentimento dinâmico

Quando precisar remover permissões delegadas de representantes da solicitação de consentimento dinâmico, especifique o parâmetro de escopo, deixando de fora as permissões que deseja remover. A remoção das permissões garante que o aplicativo não chame a API correspondente.

Esse método só funciona para permissões delegadas. As permissões de aplicativo são solicitadas e concedidas por um administrador por meio de consentimento estático e não são incluídas no parâmetro scope durante a solicitação de autorização do OAuth 2.0.

Para interromper a solicitação de permissões de acesso com consentimento dinâmico:

• Usando o Microsoft Graph: remova as permissões de acesso indesejadas do Microsoft Graph do parâmetro `escopo`. Neste exemplo, seu aplicativo está solicitando três permissões delegadas: Analytics.Read, User.Read e Application.Read. As permissões delegadas Analytics.Read e Application.Read não são mais necessárias para este aplicativo. Ele requer apenas User.Read.

A solicitação deve ser de modo semelhante ao exemplo a seguir:

https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id=00001111-aaaa-2222-bbbb-3333cccc4444&response_type=code&scope=User.Read

• usando o MSAL.js: remova as permissões de acesso indesejadas do Microsoft Graph em `escopos`.

      const Request = {
          scopes: ["openid", "profile"],
          loginHint: "example@domain.net"
      };
  
      myMSALObj.ssoSilent(Request)
          .then((response) => {
              // your logic
          }).catch(error => {
              console.error("Silent Error: " + error);
              if (error instanceof msal.InteractionRequiredAuthError) {
                  myMSALObj.loginRedirect(loginRequest);
              }
      });
  

Revogar o consentimento das permissões de acesso removidas do aplicativo empresarial

Após as permissões serem removidas do registro do aplicativo, um administrador no locatário também precisará revogar o consentimento para proteger os dados da sua organização. Quando a permissão removida requer o consentimento do administrador, as ações necessárias variam com base no tipo de aplicativo:

• Aplicativo de locatário único e aplicativo multilocatário no locatário principal: para um aplicativo de locatário único, entre em contato com o administrador do locatário para revogar as permissões de acesso já concedidas ao aplicativo. Para um aplicativo multilocatário, entre em contato com os administradores de todos os locatários em que residem as instâncias do seu aplicativo para revogar as permissões de acesso concedidas ao aplicativo empresarial. A revogação do consentimento para as permissões removidas garante que o aplicativo não mantenha o acesso através da permissão removida.
• Aplicativos multilocatários nos locatários dos clientes: Certifique-se de se comunicar com seus clientes para revogar permissões por meio de anúncios, blogs e quaisquer outros canais de comunicação.

Tanto para aplicativos de locatário único quanto para multilocatários, os usuários não administradores em locatários em que o consentimento do usuário está habilitado podem usar o portal MyApps para revogar o consentimento para permissões de acesso concedidas anteriormente. Para obter mais informações sobre como os usuários finais podem revogar permissões no portal MyApps, confira Revogar consentimento do usuário final.

Substituir uma permissão

Você deve substituir uma permissão altamente privilegiada quando uma permissão menos privilegiada for suficiente.

A substituição de permissões também pode reduzir o risco de expor dados confidenciais ou comprometer a segurança e, assim, melhorar a experiência do usuário e a relação de confiança. Se seu aplicativo estiver usando uma permissão altamente privilegiada, como Directory.ReadWrite.All, você deverá considerar se uma permissão menos privilegiada, como User.ReadWrite.All, seria suficiente para a funcionalidade do seu aplicativo.

Observação

Quando você modificar as permissões de acesso solicitadas de um aplicativo para o consentimento estático, o cliente precisará consentir novamente. O ato de conceder novamente revoga todas as permissões de acesso concedidas anteriormente e dá o consentimento para as novas. Quando você modifica as permissões solicitadas de um aplicativo para consentimento dinâmico, as permissões de acesso concedidas anteriormente não são revogadas. O cliente tem que revogar as permissões de acesso manualmente.

Para substituir uma permissão, você precisará remover a permissão desnecessária e adicionar a permissão alternativa. As etapas são semelhantes às descritas nas seções Parar de solicitar permissões não utilizadas e adicionar permissões deste artigo.