Guia de início rápido: configurar um aplicativo cliente para acessar uma API da Web

Neste início rápido, vai permitir o acesso baseado em permissões e com âmbito de uma aplicação cliente registada na plataforma de identidades da Microsoft à sua própria API Web. Também vai permitir que a aplicação cliente aceda ao Microsoft Graph.

Ao especificar os escopos de uma API da Web no registro do aplicativo cliente, o aplicativo cliente pode obter um token de acesso contendo esses escopos da plataforma de identidade da Microsoft. Dentro de seu código, a API da Web pode fornecer acesso baseado em permissão aos seus recursos com base nos escopos encontrados no token de acesso.

Pré-requisitos

• Uma conta do Azure com uma subscrição ativa. Crie uma conta gratuitamente.
• Conclusão do Guia de início rápido: registrar um aplicativo
• Conclusão do Guia de início rápido: configurar um aplicativo para expor uma API da Web

Adicionar permissões para acessar sua API da Web

O acesso às APIs requer a configuração de escopos e funções de acesso. Se quiser expor as APIs da Web do aplicativo de recursos para aplicativos cliente, você pode configurar escopos de acesso e funções para a API. Se quiser que um aplicativo cliente acesse uma API da Web, configure as permissões para acessar a API no registro do aplicativo.

Para conceder a um aplicativo cliente acesso à sua própria API da Web, você precisa ter dois registros de aplicativo;

• Um registro de aplicativo cliente
• Um registro de API da Web com escopos expostos

O diagrama mostra como os dois registros de aplicativo se relacionam entre si, onde o aplicativo cliente tem diferentes tipos de permissão e a API da Web tem escopos diferentes que o aplicativo cliente pode acessar. Nesta seção, você adiciona permissões ao registro do aplicativo cliente.

Depois de registrar seu aplicativo cliente e a API da Web e expor a API criando escopos, você pode configurar as permissões do cliente para a API seguindo estas etapas:

1. Entre no centro de administração do Microsoft Entra como pelo menos um administrador de aplicativos na nuvem.

2. Se você tiver acesso a vários locatários, use o ícone Configurações no menu superior para alternar para o locatário que contém o registro do aplicativo no menu Diretórios + assinaturas.

3. Navegue até Registros do aplicativo Identity>Applications>e selecione seu aplicativo cliente (não sua API da Web).

4. Selecione Permissões de API e, em seguida , Adicionar uma permissão e selecione Minhas APIs na barra lateral.

5. Selecione a API da Web que você registrou como parte dos pré-requisitos e selecione Permissões delegadas.

   • As permissões delegadas são apropriadas para aplicativos cliente que acessam uma API da Web como o usuário conectado e cujo acesso deve ser restrito às permissões selecionadas na próxima etapa. Deixe Permissões delegadas selecionadas para este exemplo.

   • As permissões de aplicativo são para aplicativos do tipo serviço ou daemon que precisam acessar uma API da Web como eles mesmos, sem interação do usuário para entrar ou consentimento. A menos que você tenha definido funções de aplicativo para sua API da Web, essa opção será desabilitada.

6. Em Selecionar permissões, expanda o recurso cujos escopos você definiu para sua API da Web e selecione as permissões que o aplicativo cliente deve ter em nome do usuário conectado.

   • Se você usou os nomes de escopo de exemplo especificados no início rápido anterior, deverá ver Employees.Read.All e Employees.Write.All.

7. Selecione a permissão que você criou ao preencher os pré-requisitos, por exemplo, Employees.Read.All.

8. Selecione Adicionar permissões para concluir o processo.

Depois de adicionar permissões à sua API, você verá as permissões selecionadas em Permissões configuradas. A imagem a seguir mostra o exemplo de permissão delegada Employees.Read.All adicionada ao registro do aplicativo cliente.

Você também pode notar a permissão User.Read para a API do Microsoft Graph. Essa permissão é adicionada automaticamente quando você registra um aplicativo no portal do Azure.

Adicionar permissões para aceder ao Microsoft Graph

Além de acessar sua própria API da Web em nome do usuário conectado, seu aplicativo também pode precisar acessar ou modificar os dados do usuário (ou outros) armazenados no Microsoft Graph. Ou você pode ter um aplicativo de serviço ou daemon que precisa acessar o Microsoft Graph como ele mesmo, executando operações sem qualquer interação do usuário.

Permissão delegada ao Microsoft Graph

Configure a permissão delegada ao Microsoft Graph para permitir que seu aplicativo cliente execute operações em nome do usuário conectado, por exemplo, lendo seu email ou modificando seu perfil. Por padrão, os usuários do seu aplicativo cliente são solicitados quando entram para consentir com as permissões delegadas que você configurou para ele.

1. Na página Visão geral do seu aplicativo cliente, selecione Permissões>de API Adicionar uma permissão>Microsoft Graph

2. Selecione Permissões delegadas. O Microsoft Graph expõe muitas permissões, com as mais usadas mostradas no topo da lista.

3. Em Selecionar permissões, selecione as seguintes permissões:

   Permissão	Description
   email	Ver o endereço de e-mail dos utilizadores
   offline_access	Manter acesso aos dados a que tenha dado acesso
   openid	Iniciar sessão de utilizadores
   profile	Ver o perfil básico dos utilizadores

4. Selecione Adicionar permissões para concluir o processo.

Sempre que você configura permissões, os usuários do seu aplicativo são solicitados no início de sessão para permitir que seu aplicativo acesse a API de recursos em seu nome.

Como administrador, você também pode conceder consentimento em nome de todos os usuários para que eles não sejam solicitados a fazê-lo. O consentimento do administrador é discutido mais adiante na seção Mais sobre permissões de API e consentimento de administrador deste artigo.

Permissão de aplicativo para o Microsoft Graph

Configure permissões de aplicativo para um aplicativo que precisa se autenticar como ele mesmo sem interação ou consentimento do usuário. As permissões de aplicativo são normalmente usadas por serviços em segundo plano ou aplicativos daemon que acessam uma API de maneira "sem cabeça" e por APIs da Web que acessam outra API (downstream).

Nas etapas a seguir, você concede permissão para a permissão Files.Read.All do Microsoft Graph como um exemplo.

1. Entre no centro de administração do Microsoft Entra como pelo menos um administrador de aplicativos na nuvem.
2. Se você tiver acesso a vários locatários, use o ícone Configurações no menu superior para alternar para o locatário que contém o registro do aplicativo no menu Diretórios + assinaturas.
3. Navegue até Registros do aplicativo Identity>Applications>e selecione seu aplicativo cliente.
4. Selecione permissões>de API Adicione uma permissão>Permissões do Aplicativo Microsoft Graph.>
5. Todas as permissões expostas pelo Microsoft Graph são mostradas em Selecionar permissões.
6. Selecione a permissão ou permissões que você deseja conceder ao seu aplicativo. Como exemplo, você pode ter um aplicativo daemon que verifica arquivos em sua organização, alertando sobre um tipo de arquivo ou nome específico. Em Selecionar permissões, expanda Arquivos e selecione a Files.Read.All permissão.
7. Selecione Adicionar permissões.
8. Algumas permissões, como a permissão Files.Read.All do Microsoft Graph, exigem o consentimento do administrador. Você concede consentimento de administrador selecionando o botão Conceder consentimento de administrador, discutido posteriormente na seção Botão de consentimento de administrador.

Configurar credenciais de cliente

Os aplicativos que usam permissões de aplicativo são autenticados como eles mesmos usando suas próprias credenciais, sem exigir qualquer interação do usuário. Antes que seu aplicativo (ou API) possa acessar o Microsoft Graph, sua própria API da Web ou outra API usando permissões de aplicativo, você deve configurar as credenciais desse aplicativo cliente.

Para obter mais informações sobre como configurar as credenciais de um aplicativo, consulte a seção Adicionar credenciais de Guia de início rápido: registrar um aplicativo com a plataforma de identidade da Microsoft.

Saiba mais sobre permissões de API e consentimento de administrador

O painel de permissões da API de um registro de aplicativo contém a tabela Permissões configuradas e o botão Consentimento do administrador, que são descritos nas seções a seguir.

Permissões configuradas

A tabela Permissões configuradas no painel de permissões da API mostra a lista de permissões que seu aplicativo requer para a operação básica - a lista RRA (acesso a recursos necessários). Os usuários, ou seus administradores, precisarão consentir essas permissões antes de usar seu aplicativo. Outras permissões opcionais podem ser solicitadas posteriormente em tempo de execução (usando consentimento dinâmico).

Esta é a lista mínima de permissões que as pessoas terão de consentir para a sua aplicação. Poderia haver mais, mas estes serão sempre necessários. Por motivos de segurança e para ajudar os utilizadores e administradores a sentirem-se mais confortáveis a utilizar a sua aplicação, nunca peça nada de que não precise.

Você pode adicionar ou remover as permissões que aparecem nesta tabela usando as etapas descritas acima. Como administrador, você pode conceder consentimento de administrador para o conjunto completo de permissões de uma API que aparecem na tabela e revogar o consentimento para permissões individuais.

Botão de consentimento do administrador

O botão Conceder consentimento de administrador para {seu locatário} permite que um administrador conceda consentimento de administrador para as permissões configuradas para o aplicativo. Quando você seleciona o botão, uma caixa de diálogo é exibida solicitando que você confirme a ação de consentimento.

Depois de conceder o consentimento, as permissões que exigiam o consentimento do administrador são mostradas como tendo o consentimento concedido:

O botão Conceder consentimento de administrador será desativado se você não for um administrador ou se nenhuma permissão tiver sido configurada para o aplicativo. Se tiver permissões concedidas mas ainda não configuradas, o botão de consentimento do administrador pedirá para tratar destas permissões. Pode adicioná-las às permissões configuradas ou removê-las.

Remover permissões de aplicativo

É importante não dar a um aplicativo muitas permissões do que o necessário. Para revogar o consentimento do administrador para uma permissão em seu aplicativo;

1. Navegue até seu aplicativo e selecione permissões de API.
2. Em Permissões configuradas, selecione os três pontos ao lado da permissão que deseja remover e selecione Remover permissão
3. No pop-up exibido, selecione Sim, remover para revogar o consentimento de administrador para a permissão.

Conteúdos relacionados

Avance para o próximo início rápido da série para saber como configurar quais tipos de conta podem acessar seu aplicativo. Por exemplo, talvez você queira limitar o acesso apenas aos usuários em sua organização (locatário único) ou permitir usuários em outros locatários do Microsoft Entra (multilocatário) e aqueles com contas pessoais da Microsoft (MSA).