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

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

Dica

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

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:

    An app registration's Expose an API pane in the Azure portal

  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.

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:

Campo Valor de exemplo
Nome do Escopo Employees.Write.All
Quem pode consentir Somente administradores
Nome de exibição de consentimento do administrador Write access to Employee records
Descrição do consentimento do administrador Allow the application to have write access to all Employee data.
Nome para exibição do consentimento do usuário Nenhum (deixe em branco)
Descrição de consentimento do usuário Nenhum (deixe em branco)

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:

Screenshot of the Expose an API pane showing two exposed scopes.

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.

Configurar um registro de aplicativo para acesso à API Web