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

Neste guia de início rápido, você vai registrar uma API Web na plataforma de identidade da Microsoft e expô-la aos aplicativos cliente adicionando um escopo. Ao registrar sua API Web e expô-la por meio de escopos, atribuindo um proprietário e uma função de aplicativo, você pode fornecer acesso baseado em permissões aos seus recursos para usuários autorizados e aplicativos cliente que acessam a API.

Pré-requisitos

• Uma conta do Azure com uma assinatura ativa – criar uma conta gratuitamente
• Conclusão do Início Rápido: Configurar um locatário

Registrar a API Web

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.

Para fornecer acesso com escopo aos recursos em sua API Web, primeiro registre a API com a plataforma de identidade da Microsoft.

Execute as etapas na seção Registrar um aplicativo do Início Rápido: Registre um aplicativo na plataforma de identidade da Microsoft.

Ignore a seção URI de redirecionamento (opcional). Você não precisa configurar um URI de redirecionamento para uma API Web, pois nenhum usuário está conectado interativamente.

Atribuir proprietário do aplicativo

1. No registro do aplicativo, em Gerenciar, selecione Proprietários e Adicionar proprietários.
2. Na nova janela, localize e selecione os proprietários que você quer atribuir ao aplicativo. Os proprietários selecionados aparecem no painel direito. Depois de concluído, confirme com Selecionar. Os proprietários de aplicativos agora aparecerão na lista de proprietários.

Atribuir função de aplicativo

1. No registro do aplicativo, em Gerenciar, selecione Funções de aplicativo e Criar função de aplicativo.

2. Em seguida, especifique os atributos da função do aplicativo no painel Criar função de aplicativo. Para este passo a passo, você pode usar os valores de exemplo ou especificar o seu próprio valor.

   Campo	Description	Exemplo
   Nome de exibição	O nome da função de aplicativo	Registros de Funcionários
   Tipos de membro permitidos	Especifica se a função do aplicativo pode ser atribuída a usuários/grupos e/ou aplicativos	Aplicativos
   Valor	O valor exibido na declaração “funções” de um token	Employee.Records
   Descrição	Uma descrição mais detalhada da função de aplicativo	Os aplicativos têm acesso aos registros dos funcionários

3. Marque a caixa de seleção para habilitar a função de aplicativo.

Com a API Web registrada, atribuída a uma função de aplicativo e a um proprietário, você pode adicionar escopos ao código da API para que ela possa fornecer permissão granular aos consumidores.

Adicionar um escopo

O código em um aplicativo cliente solicita permissão para executar operações definidas por sua API Web passando um token de acesso junto com suas solicitações para o recurso protegido (a API Web). A API Web executará a operação solicitada somente se o token de acesso recebido contiver os escopos necessários para a operação.

Primeiro, siga estas etapas para criar um escopo de exemplo chamado Employees.Read.All:

1. Entre no Centro de administração do Microsoft Entra como pelo menos Administrador de Aplicativo de nuvem.

2. Se você tem 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 de aplicativo do menu Diretórios + assinaturas.

3. Navegue até Identidade>Aplicativos>Registros de aplicativo e, em seguida, selecione o registro do aplicativo de API.

4. Selecione Expor uma API

5. Selecione Adicionar ao lado deURI da ID do Aplicativo se ainda não houver configurado uma.

   Você pode usar o valor padrão de api://<application-client-id> ou outro padrão de URI de ID de aplicativo com suporte. O URI da ID do aplicativo atua como o prefixo dos escopos que você fará referência no código da API e deve ser globalmente exclusivo.

6. Selecione Adicionar um escopo:

   

7. Em seguida, especifique os atributos do escopo no painel Adicionar um escopo. Para este passo a passo, você pode usar os valores de exemplo ou especificar o seu próprio valor.

   Campo	Description	Exemplo
   Nome do Escopo	O nome do seu escopo. Uma convenção de nomenclatura de escopo comum é resource.operation.constraint.	Employees.Read.All
   Quem pode consentir	Se esse escopo pode ser consentido por usuários ou se é necessário ter o consentimento do administrador. Selecione Somente administradores para permissões com privilégios mais elevados.	Administradores e usuários
   Nome de exibição de consentimento do administrador	Uma breve descrição da finalidade do escopo que somente os administradores verão.	Read-only access to Employee records
   Descrição do consentimento do administrador	Uma descrição mais detalhada da permissão concedida pelo escopo que somente os administradores verão.	Allow the application to have read-only access to all Employee data.
   Nome para exibição do consentimento do usuário	Uma breve descrição da finalidade do escopo. Mostrado para os usuários somente se você definir Quem pode consentir como Administradores e usuários.	Read-only access to your Employee records
   Descrição de consentimento do usuário	Uma descrição mais detalhada da permissão concedida pelo escopo. Mostrado para os usuários somente se você definir Quem pode consentir como Administradores e usuários.	Allow the application to have read-only access to your Employee data.

8. Defina o Estado como Habilitado e selecione Adicionar escopo.

9. (Opcional) Para suprimir a solicitação de consentimento dos usuários do seu aplicativo para os escopos que você definiu, você pode pré-autorizar o aplicativo cliente a acessar sua API Web. Pré-autorize apenas aplicativos cliente confiáveis, pois os usuários não terão a oportunidade de recusar o consentimento.

   1. Em Aplicativos cliente autorizados, selecione Adicionar um aplicativo cliente
   2. Insira a ID do Aplicativo (cliente) do aplicativo cliente que deseja pré-autorizar. Por exemplo, aquela de um aplicativo Web que você já registrou.
   3. Em Escopos autorizados, selecione os escopos para os quais deseja suprimir a solicitação de consentimento e escolha Adicionar aplicativo.

   Se você seguiu essa etapa opcional, o aplicativo cliente agora é um PCA (aplicativo cliente pré-autorizado), e os usuários não serão solicitados a dar consentimento ao entrar nele.

Adicionar um escopo que requer o consentimento do administrador

Em seguida, adicione outro escopo de exemplo chamado Employees.Write.All que apenas os administradores podem consentir. Os escopos que exigem consentimento do administrador normalmente são usados para da acesso a operações com maior privilégio e, muitas vezes, por aplicativos cliente executados como serviços de back-end ou daemons que não conectam um usuário interativamente.

Para adicionar o exemplo de escopo Employees.Write.All, siga as etapas na seção Adicionar um escopo e especifique esses valores no painel Adicionar um escopo:

Defina o Estado como Habilitado e selecione Adicionar escopo.

Verificar os escopos expostos

Se você tiver adicionado com sucesso os dois exemplos de escopos descritos nas seções anteriores, eles serão exibidos no painel Expor uma API do registro de aplicativo da API Web, semelhante à seguinte imagem:

Conforme mostrado na imagem, a cadeia de caracteres completa de um escopo é a concatenação do URI da ID do Aplicativo da sua API Web e o Nome do escopo.

Por exemplo, se o URI da ID do aplicativo da sua API Web for https://contoso.com/api e o nome do escopo for Employees.Read.All, o escopo completo será:

https://contoso.com/api/Employees.Read.All

Como usar os escopos expostos

No próximo artigo desta série, você vai configurar o registro de um aplicativo cliente com acesso à API Web e os escopos que você definiu seguindo as etapas do artigo.

Depois que um registro de aplicativo cliente recebe permissão para acessar sua API Web, o cliente pode receber um token de acesso OAuth 2.0 pela plataforma de identidade. Quando o cliente chama a API Web, ele apresenta um token de acesso cuja declaração de escopo (scp) é definida como as permissões que você especificou no registro de aplicativo do cliente.

É possível expor escopos adicionais posteriormente conforme a necessidade. Considere que sua API Web pode expor vários escopos associados a diversas operações. O recurso pode controlar o acesso à API Web em runtime avaliando as declarações de escopo (scp) no token de acesso OAuth 2.0 recebido.

Próximas etapas

Agora que você expôs sua API Web configurando seus escopos, configure o registro do aplicativo cliente com permissão para acessar esses escopos.