Início Rápido: Configurar um aplicativo cliente para acessar uma API Web

Neste guia de início rápido, você fornece um aplicativo cliente registrado com a plataforma de identidade da Microsoft com acesso baseado em permissões no escopo à sua própria API Web. Você também fornece acesso ao aplicativo cliente para o Microsoft Graph.

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

Pré-requisitos

• Uma conta do Azure com uma assinatura ativa. Crie uma conta gratuitamente.
• Conclusão do Início Rápido: Registrar um aplicativo
• Conclusão do Início Rápido: Configurar um aplicativo para expor uma API Web

Adicionar permissões para acessar sua API Web

Dica

As etapas neste artigo podem variar ligeiramente com base no portal do qual você começa.

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

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

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

O diagrama mostra como os dois registros de aplicativo se relacionam entre si, em que o aplicativo cliente tem tipos de permissão diferentes e a API 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 o aplicativo cliente e a API 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 Administrador de Aplicativo de 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é Identidade>Aplicativos>Registros de aplicativo, e selecione o seu aplicativo cliente (não sua API 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 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 Web como o usuário conectado e cujo acesso deve ser restrito às permissões selecionadas na próxima etapa. Deixe Permissões delegadas selecionado para este exemplo.

   • As Permissões de aplicativo são para aplicativos do tipo serviço ou daemon que precisam acessar uma API Web por conta própria, sem interação com o usuário para conexão ou consentimento. A menos que você tenha definido funções de aplicativo para sua API Web, essa opção estará desabilitada.

6. Em Selecionar permissões, expanda o recurso cujos escopos você definiu para sua API 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, verá Employees.Read.All e Employees.Write.All.

7. Selecione a permissão que você criou ao concluir 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ê deverá 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 observar 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 acessar o Microsoft Graph

Além de acessar sua própria API 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. Você também pode ter um aplicativo de serviço ou daemon que precise acessar o Microsoft Graph em próprio nome, executando operações sem nenhuma interação com o usuário.

Permissão delegada para o Microsoft Graph

Configure a permissão delegada para o Microsoft Graph para permitir que o aplicativo cliente execute operações em nome do usuário conectado, por exemplo, ler o email ou modificar o perfil dele. Por padrão, os usuários do seu aplicativo cliente são solicitados a entrar para dar consentimento às permissões delegadas que você configurou para ele.

1. Na página Visão geral do 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, sendo a mais usada mostrada no topo da lista.

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

   Permissão	Descrição
   email	Exibir o endereço de email dos usuários
   offline_access	Manter o acesso aos dados aos quais você lhe deu acesso
   openid	Entrada de usuários
   profile	Exibir o perfil básico dos usuários

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

Sempre que você configurar permissões, os usuários do seu aplicativo serão solicitados a conectarem-se para dar consentimento para seu aplicativo acessar a API de recurso 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 fazer isso. O consentimento do administrador é discutido posteriormente na seção Mais sobre permissões de API e consentimento do administrador deste artigo.

Permissão de aplicativo para o Microsoft Graph

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

Nas etapas a seguir, você concede 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 Administrador de Aplicativo de 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é Identidade>Aplicativos>Registros de aplicativo, e selecione seu aplicativo cliente.
4. Selecione Permissões de API>Adicionar uma permissão>Microsoft Graph>Permissões de aplicativo.
5. Todas as permissões expostas pelo Microsoft Graph são mostradas em Selecionar permissões.
6. Selecione uma ou mais permissões que você deseja conceder ao seu aplicativo. Por exemplo, você pode ter um aplicativo daemon que examina arquivos em sua organização, alertando sobre um nome ou tipo de arquivo específico. Em Selecionar permissões, expanda Arquivos e selecione a permissão Files.Read.All.
7. Escolha Adicionar permissões.
8. Algumas permissões, como Files.Read.All do Microsoft Graph, exigem consentimento do administrador. Dê consentimento do administrador selecionando o botão Dar consentimento do administrador, discutido posteriormente na seção Botão Consentimento do administrador.

Configurar as credenciais do cliente

Aplicativos que usam permissões de aplicativo autenticam-se como eles próprios usando suas respectivas credenciais sem necessidade de nenhuma interação com o usuário. Para que o aplicativo (ou a API) possa acessar o Microsoft Graph, sua API Web ou outra API usando permissões de aplicativo, você precisa configurar as credenciais do aplicativo cliente.

Para obter mais informações sobre como configurar as credenciais de um aplicativo, confira a seção Adicionar credenciais do Início Rápido: Registrar um aplicativo na plataforma de identidade da Microsoft.

Mais sobre permissões de API e consentimento do administrador

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

Permissões configuradas

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

Esta é a lista mínima de permissões que as pessoas precisarão dar consentimento para seu aplicativo. Pode haver mais, mas estas sempre serão necessárias. Para segurança e ajudar os usuários e administradores a se sentirem mais confortáveis com o uso do seu aplicativo, nunca peça nada de que você não precise.

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

Botão de consentimento do administrador

O botão Dar consentimento do administrador para {seu locatário} permite que um administrador dê consentimento do administrador às permissões configuradas para o aplicativo. Quando você seleciona o botão, uma caixa de diálogo solicita que você confirme a ação de consentimento.

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

O botão Dar consentimento do administrador é desabilitado se você não é um administrador ou se nenhuma permissão foi configurada para o aplicativo. Se você tiver permissões que foram concedidas, mas ainda não foram configuradas, o botão de consentimento do administrador solicitará que você lide com essas permissões. Você pode adicioná-las a permissões configuradas ou removê-las.

Remover permissões de aplicativo

É importante não conceder a um aplicativo mais 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 você deseja remover e selecione Remover permissão
3. No pop-up exibido, selecione Sim, remova para revogar o consentimento do administrador para a permissão.

Conteúdo relacionado

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).

Modificar as contas que têm suporte por um aplicativo