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 – criar 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 exigem configuração de escopos de acesso e funções. Se você quiser expor suas APIs web do aplicativo de recursos para aplicativos cliente, configure escopos de acesso e funções da API. Se desejar que um aplicativo cliente acesse uma API web, configure permissões para acessar a API no registro de aplicativo.
No primeiro cenário, você concede a um aplicativo cliente acesso à sua própria API Web, que você deve ter registrado como parte dos pré-requisitos. Se você ainda não tem um aplicativo cliente e uma API Web registrados, conclua as etapas nos dois artigos de Pré-requisitos.
Este diagrama mostra a relação entre os dois registros de aplicativo. 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:
Entre no Centro de administração do Microsoft Entra como pelo menos Administrador de Aplicativo de nuvem.
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.Navegue até Identidade>Aplicativos>Registros de aplicativo, e selecione o seu aplicativo cliente (não sua API Web).
Selecione Permissões de API>Adicionar uma permissão>Minhas APIs.
Selecione a API Web que você registrou como parte dos pré-requisitos.
Permissões delegadas é selecionado por padrão. 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.
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. Selecione Employees.Read.All ou outra permissão que você tenha criado ao concluir os pré-requisitos.
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.
Entre no Centro de administração do Microsoft Entra como pelo menos Administrador de Aplicativo de nuvem.
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.Navegue até Identidade>Aplicativos>Registros de aplicativo, e selecione seu aplicativo cliente.
Selecione Permissões de API>Adicionar uma permissão>Microsoft Graph
Selecione Permissões delegadas. O Microsoft Graph expõe muitas permissões, sendo a mais usada mostrada no topo da lista.
Em Selecionar permissões, selecione as seguintes permissões:
Permissão Descrição emailExibir o endereço de email dos usuários offline_accessManter o acesso aos dados aos quais você lhe deu acesso openidEntrada de usuários profileExibir o perfil básico dos usuários 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.
Entre no Centro de administração do Microsoft Entra como pelo menos Administrador de Aplicativo de nuvem.
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.Navegue até Identidade>Aplicativos>Registros de aplicativo, e selecione seu aplicativo cliente.
Selecione Permissões de API>Adicionar uma permissão>Microsoft Graph>Permissões de aplicativo.
Todas as permissões expostas pelo Microsoft Graph são mostradas em Selecionar permissões.
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.
Escolha Adicionar permissões.
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 uma tabela Permissões configuradas e também podem conter uma tabela Outras permissões concedidas. As tabelas e o botão Consentimento do administrador sã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 nessa tabela usando as etapas descritas acima ou em Outras permissões concedidas (descrito na próxima seção). 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.
Outras permissões concedidas
Você também pode ver uma tabela chamada Outras permissões concedidas para {your tenant} no painel Permissões de API. A tabela Outras permissões concedidas para {your tenant} mostra as permissões concedidas para todo o locatário que não foram explicitamente configurados no objeto do aplicativo. Essas permissões foram solicitadas e consentidas dinamicamente por um administrador, em nome de todos os usuários. Essa seção será exibida apenas se houver pelo menos uma permissão aplicável.
Você pode adicionar o conjunto completo de permissões de uma API ou permissões individuais que aparecem nesta tabela à tabela Permissões configuradas. Como administrador, você pode revogar o consentimento do administrador para APIs ou permissões individuais nesta seção.
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.
Próximas etapas
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).