Compartilhar via

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

  • Artigo

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

Registrar a API Web

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

  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. Siga as etapas em registrar um aplicativo e pule para 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.

Observação

Verifique se o aplicativo de API e o aplicativo ao qual você quer adicionar permissões têm um proprietário; caso contrário, a API não será listada ao solicitar permissões de API.

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 Descrição 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 do aplicativo e, em seguida, selecione Aplicar.

Adicionar um escopo

Dica

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

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.

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. Selecione Expor uma API.

  2. Na parte superior da página, selecione Adicionar ao lado de URI de ID do Aplicativo. O padrão é api://<application-client-id>. 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. Selecione Salvar.

  3. Selecione Adicionar um escopo:

    Um registro de aplicativo expõe um painel de API no portal do Azure

  4. 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 Descrição 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. Use Apenas administradores para permissões com privilégios mais altos. 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. Acesso somente leitura aos registros de funcionários
    Descrição do consentimento do administrador Uma descrição mais detalhada da permissão concedida pelo escopo que somente os administradores verão. Permitir que o aplicativo tenha acesso somente leitura a todos os dados de funcionários.
    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. Acesso somente leitura aos seus registros de funcionário
    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. Permitir que o aplicativo tenha acesso somente leitura aos seus dados de funcionário.
    State Se o escopo está habilitado ou desabilitado. Enabled

  5. Selecione Adicionar escopo.

  6. (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.

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. Selecione Adicionar escopo quando terminar:

Campo Valor de exemplo
Nome do Escopo Employees.Write.All
Quem pode consentir Somente administradores
Nome de exibição de consentimento do administrador Acesso para gravação aos registros de funcionários
Descrição do consentimento do administrador Permitir que o aplicativo tenha acesso para gravação a todos os dados de funcionários.
Nome para exibição do consentimento do usuário Nenhum (deixe em branco)
Descrição de consentimento do usuário Nenhum (deixe em branco)
State Enabled

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:

Captura de tela do painel Expor uma API mostrando dois escopos expostos.

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óxima etapa

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

Configurar um registro de aplicativo para acesso à API Web