Guia de início rápido: configurar um aplicativo para expor uma API da Web

  • Artigo

Neste início rápido, você registrará uma API da Web com a plataforma de identidade da Microsoft e a exporá aos aplicativos cliente adicionando um escopo. Ao registrar sua API da 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 sua API.

Pré-requisitos

Registrar a API da Web

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.

Para fornecer acesso com escopo aos recursos em sua API da Web, primeiro você precisa registrar a API na plataforma de identidade da Microsoft.

Execute as etapas na seção Registrar um aplicativo do Guia de início rápido: registrar um aplicativo com a plataforma de identidade da Microsoft.

Ignore a seção Redirecionar URI (opcional). Não é necessário configurar um URI de redirecionamento para uma API da Web, pois nenhum usuário está conectado interativamente.

Atribuir proprietário do aplicativo

  1. No registo da sua aplicação, em Gerir, selecione Proprietários e Adicionar proprietários.
  2. Na nova janela, localize e selecione o(s) proprietário(s) que deseja atribuir ao aplicativo. Os proprietários selecionados aparecem no painel direito. Uma vez feito, confirme com Selecionar. O(s) proprietário(s) da aplicação aparecerá(ão) na lista de proprietários.

Nota

Certifique-se de que o aplicativo de API e o aplicativo que você deseja adicionar permissões a ambos tenham 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 registo da aplicação, em Gerir, selecione Funções da aplicação e Criar função da aplicação.

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

    Campo Description Exemplo
    Nome a apresentar O nome da função do aplicativo Registros de funcionários
    Tipos de membros permitidos Especifica se a função do aplicativo pode ser atribuída a usuários/grupos e/ou aplicativos Aplicações
    Valor O valor exibido na declaração "roles" de um token Employee.Records
    Descrição Uma descrição mais detalhada da função do 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.

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

Adicionar um âmbito

Gorjeta

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

O código em um aplicativo cliente solicita permissão para executar operações definidas pela API da Web, passando um token de acesso junto com suas solicitações para o recurso protegido (a API da Web). Em seguida, a API da Web executa 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 um administrador de aplicativos na nuvem.

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

  3. Navegue até Registros do aplicativo Identity>Applications>e selecione o registro do aplicativo da API.

  4. Selecione Expor uma API

  5. Selecione Adicionar ao lado de URI da ID do aplicativo, se ainda não tiver configurado um.

    Você pode usar o valor padrão ou outro padrão de URI de ID de api://<application-client-id> aplicativo suportado. O URI da ID do aplicativo atua como o prefixo para os escopos aos quais 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 os seus.

    Campo Description Exemplo
    Nome do âmbito 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 pelos usuários ou se o consentimento do administrador é necessário. Selecione Apenas administradores para permissões com mais privilégios. Administradores e utilizadores
    Nome a apresentar do consentimento do administrador Uma breve descrição da finalidade do escopo que apenas 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 apenas os administradores verão. Allow the application to have read-only access to all Employee data.
    Nome a apresentar do consentimento do utilizador Uma breve descrição da finalidade do âmbito de aplicação. Mostrado aos usuários somente se você definir Quem pode consentir com administradores e usuários. Read-only access to your Employee records
    Descrição do consentimento do utilizador Uma descrição mais detalhada da permissão concedida pelo escopo. Mostrado aos usuários somente se você definir Quem pode consentir com 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 definidos, você pode pré-autorizar o aplicativo cliente a acessar sua API da Web. Pré-autorize apenas os aplicativos cliente em que você confia, pois seus usuários não terão a oportunidade de recusar o consentimento.

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

    Se você seguiu essa etapa opcional, o aplicativo cliente agora é um aplicativo cliente pré-autorizado (PCA) e os usuários não serão solicitados a dar seu 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 geralmente são usados para fornecer acesso a operações com privilégios mais altos e, muitas vezes, por aplicativos cliente que são executados como serviços de back-end ou daemons que não entram em um usuário interativamente.

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

Campo Valor de exemplo
Nome do âmbito Employees.Write.All
Quem pode consentir Apenas administradores
Nome a apresentar do 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 a apresentar do consentimento do utilizador Nenhum (deixar vazio)
Descrição do consentimento do utilizador Nenhum (deixar vazio)

Defina o Estado como Habilitado e selecione Adicionar escopo.

Verificar os escopos expostos

Se você adicionou com êxito os dois escopos de exemplo descritos nas seções anteriores, eles aparecerão no painel Expor uma API do registro do aplicativo da API da Web, semelhante à imagem a seguir:

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 de ID do aplicativo da API da Web e o nome do escopo do escopo.

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

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

Usando os escopos expostos

No próximo artigo desta série, você configura o registro de um aplicativo cliente com acesso à sua API da Web e os escopos definidos seguindo as etapas neste artigo.

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

Se necessário, pode expor âmbitos adicionais mais tarde. Considere que sua API da Web pode expor vários escopos associados a várias operações. Seu recurso pode controlar o acesso à API da Web em tempo de execução avaliando as declarações de escopo (scp) no token de acesso OAuth 2.0 que recebe.

Próximos passos

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

Configurar um registro de aplicativo para acesso à API da Web