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
Gorjeta
As etapas neste artigo podem variar ligeiramente com base no portal a partir do qual você começou.
O acesso às APIs requer a configuração de escopos e funções de acesso. Se você quiser expor suas APIs da Web de aplicativo de recursos para aplicativos cliente, configure escopos de acesso e funções para a API. Se você quiser que um aplicativo cliente acesse uma API da Web, configure as permissões para acessar a API no registro do aplicativo.
No primeiro cenário, você concede a um aplicativo cliente acesso à sua própria API da Web, ambos os quais você deve ter registrado como parte dos pré-requisitos. Se você ainda não tiver um aplicativo cliente e uma API da Web registrados, conclua as etapas nos dois artigos Pré-requisitos .
Este diagrama mostra como os dois registros de aplicativo se relacionam entre si. 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:
Entre no centro de administração do Microsoft Entra como pelo menos um administrador de aplicativos na 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é Registros do aplicativo Identity>Applications>e selecione seu aplicativo cliente (não sua API da Web).
Selecione Permissões>de API Adicionar uma permissão>Minhas APIs.
Selecione a API da Web que você registrou como parte dos pré-requisitos.
As permissões delegadas são selecionadas por padrão. 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.
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. Selecione Employees.Read.All ou outra permissão que você possa ter criado ao concluir os pré-requisitos.
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.
Entre no centro de administração do Microsoft Entra como pelo menos um administrador de aplicativos na 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é Registros do aplicativo Identity>Applications>e selecione seu aplicativo cliente.
Selecionar permissões>de API Adicionar uma permissão>Microsoft Graph
Selecione Permissões delegadas. O Microsoft Graph expõe muitas permissões, com as mais usadas mostradas no topo da lista.
Em Selecionar permissões, selecione as seguintes permissões:
Permissão Description emailVer o endereço de e-mail dos utilizadores offline_accessManter acesso aos dados a que tenha dado acesso openidIniciar sessão de utilizadores profileVer o perfil básico dos utilizadores 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.
Entre no centro de administração do Microsoft Entra como pelo menos um administrador de aplicativos na 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é Registros do aplicativo Identity>Applications>e selecione seu aplicativo cliente.
Selecione permissões>de API Adicione uma permissão>Permissões do Aplicativo Microsoft Graph.>
Todas as permissões expostas pelo Microsoft Graph são mostradas em Selecionar permissões.
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, em seguida, selecione a permissão Files.Read.All .
Selecione Adicionar permissões.
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 uma tabela de permissões Configuradas e também pode conter uma tabela Outras permissões concedidas. As tabelas e o botão de consentimento do administrador 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 ou em Outras permissões concedidas (descritas na próxima seção). 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.
Outras permissões concedidas
Você também pode ver uma tabela intitulada Outras permissões concedidas para {seu locatário} no painel de permissões da API. A tabela Outras permissões concedidas para {seu locatário} mostra as permissões concedidas em todo o locatário para o locatário que não foram configuradas explicitamente no objeto do aplicativo. Essas permissões foram solicitadas dinamicamente e consentidas por um administrador, em nome de todos os usuários. Esta seção aparece somente 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 na tabela Permissões configuradas. Como administrador, você pode revogar o consentimento de administrador para APIs ou permissões individuais nesta seção.
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.
Próximos passos
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).