Partilhar via

Chame uma API da Web do ASP.NET Core com o Insomnia

  • Artigo

Este artigo mostra como chamar uma API da Web protegida do ASP.NET Core usando o Insomnia. Insomnia é um aplicativo que permite enviar solicitações HTTP para uma API da Web para testar suas políticas de autorização e controle de acesso (autenticação). Neste artigo, você registra um aplicativo Web e uma API Web em um locatário. O aplicativo Web é usado para obter um token de acesso gerado pela plataforma de identidade da Microsoft. Em seguida, você usa o token para fazer uma chamada autorizada para a API da Web usando o Insomnia.

Este artigo mostra como chamar uma API da Web protegida do ASP.NET Core usando o Insomnia. Insomnia é um aplicativo que permite enviar solicitações HTTP para uma API da Web para testar suas políticas de autorização e controle de acesso (autenticação). Na sequência do Tutorial: Implementar um ponto de extremidade protegido em sua API, onde você criou uma API protegida, você precisa registrar um aplicativo Web com a plataforma de identidade da Microsoft para gerar um token de acesso. Em seguida, você usa o token para fazer uma chamada autorizada para a API usando o Insomnia.

Pré-requisitos

  • Uma conta do Azure com uma subscrição ativa. Crie uma conta gratuitamente.
  • Essa conta do Azure deve ter permissões para gerenciar aplicativos. Qualquer uma das seguintes funções do Microsoft Entra inclui as permissões necessárias:
    • Administrador da Aplicação
    • Programador de Aplicações
    • Administrador de Aplicações na Cloud
  • Baixe e instale o Insomnia. Você usa o Insomnia para obter um token de acesso para suas solicitações de API.
  • Um requisito mínimo do SDK do .NET 8.0.

Registar uma aplicação

A plataforma de identidade da Microsoft exige que seu aplicativo seja registrado antes de fornecer serviços de gerenciamento de identidade e acesso. O registro do aplicativo permite que você especifique o nome e o tipo do aplicativo e o público de login. O público de entrada especifica quais tipos de contas de usuário podem entrar em um determinado aplicativo.

Registrar a API da Web

Gorjeta

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

Siga estas etapas para criar o registro da API da Web:

  1. Entre no centro de administração do Microsoft Entra como pelo menos um desenvolvedor de aplicativos.

  2. Se você tiver acesso a vários locatários, use o ícone Configurações no menu superior para alternar para o locatário no qual deseja registrar o aplicativo no menu Diretórios + assinaturas.

  3. Navegue até Registros do aplicativo Identity>Applications>.

  4. Selecione Novo registo.

  5. Insira um Nome para o aplicativo, como NewWebAPI1.

  6. Em Tipos de conta suportados, selecione Contas somente neste diretório organizacional. Para obter informações sobre diferentes tipos de conta, selecione Ajude-me a escolher a opção.

  7. Selecione Registar.

    Captura de ecrã que mostra como introduzir um nome e selecionar o tipo de conta.

  8. Você pode ver o painel Visão geral do aplicativo quando o registro for concluído. Registre o ID do diretório (locatário) e o ID do aplicativo (cliente) a serem usados em etapas posteriores.

    Captura de tela que mostra os valores de identificador na página de visão geral.

Nota

Os tipos de conta suportados podem ser alterados consultando Modificar as contas suportadas por um aplicativo.

Expor a API

Depois que a API for registrada, você poderá configurar sua permissão definindo os escopos que a API expõe aos aplicativos cliente. Os aplicativos cliente solicitam permissão para executar operações passando um token de acesso junto com suas solicitações para a API da Web protegida. Em seguida, a API da Web executa a operação solicitada somente se o token de acesso que recebe for válido.

  1. Em Gerenciar, selecione Expor uma API > Adicionar um escopo. Aceite o URI (api://{clientId}) de ID do aplicativo proposto selecionando Salvar e continuar. O {clientId} é o valor registrado na página Visão geral . Em seguida, insira as seguintes informações:

    1. Em Nome do escopo, digite Forecast.Read.
    2. Para Quem pode consentir, verifique se a opção Administradores e usuários está selecionada.
    3. Na caixa Nome para exibição do consentimento do administrador, digite Read forecast data.
    4. Na caixa Descrição do consentimento do administrador, digite Allows the application to read weather forecast data.
    5. Na caixa Nome de exibição do consentimento do usuário, digite Read forecast data.
    6. Na caixa Descrição do consentimento do utilizador, introduza Allows the application to read weather forecast data.
    7. Verifique se o Estado está definido como Habilitado.

  2. Selecione Adicionar escopo. Se o escopo tiver sido inserido corretamente, ele aparecerá no painel Expor uma API .

    Captura de tela que mostra os valores de campo ao adicionar o escopo a uma API.

Registar a aplicação Web

Não basta ter uma API da Web, você também precisa de um aplicativo da Web para obter um token de acesso para acessar a API da Web.

Siga estas etapas para criar o registro do aplicativo Web:

  1. Selecione Início para voltar à página inicial. Navegue até Registros do aplicativo Identity>Applications>.
  2. Selecione Novo registo.
  3. Insira um Nome para o aplicativo, como web-app-calls-web-api.
  4. Em Tipos de conta suportados, selecione Contas somente neste diretório organizacional. Para obter informações sobre diferentes tipos de conta, selecione a opção Ajude-me a escolher .
  5. Em Redirecionar URI (opcional), selecione Web e digite http://localhost na caixa de texto URL.
  6. Selecione Registar.
  1. Entre no centro de administração do Microsoft Entra como pelo menos um desenvolvedor de aplicativos.
  2. Se você tiver acesso a vários locatários, use o ícone Configurações no menu superior para alternar para o locatário no qual deseja registrar o aplicativo no menu Diretórios + assinaturas.
  3. Navegue até Registros do aplicativo Identity>Applications>.
  4. Selecione Novo registo.
  5. Insira um Nome para o aplicativo, como web-app-calls-web-api.
  6. Em Tipos de conta suportados, selecione Contas somente neste diretório organizacional. Para obter informações sobre diferentes tipos de conta, selecione a opção Ajude-me a escolher .
  7. Em Redirecionar URI (opcional), selecione Web e digite http://localhost na caixa de texto URL.
  8. Selecione Registar.

Você pode ver o painel Visão geral do aplicativo quando o registro for concluído. Registre o ID do diretório (locatário) e o ID do aplicativo (cliente) a serem usados em etapas posteriores.

Adicionar um segredo de cliente

Um segredo do cliente é um valor de cadeia de caracteres que seu aplicativo pode usar para se identificar e, às vezes, é chamado de senha de aplicativo. O aplicativo Web usa o segredo do cliente para provar sua identidade quando solicita tokens.

Siga estas etapas para configurar um segredo do cliente:

  1. No painel Visão geral, em Gerenciar, selecione Certificados & segredos Segredos>do>cliente Novo segredo do cliente.

  2. Adicione uma descrição para o segredo do cliente, por exemplo , Meu segredo do cliente.

  3. Selecione uma expiração para o segredo ou especifique um tempo de vida personalizado.

    • A vida útil de um segredo do cliente é limitada a dois anos (24 meses) ou menos. Não é possível especificar um tempo de vida personalizado superior a 24 meses.
    • A Microsoft recomenda que você defina um valor de expiração inferior a 12 meses.

  4. Selecione Adicionar.

  5. Certifique-se de registrar o valor do segredo do cliente. Este valor secreto nunca mais é apresentado depois de sair desta página.

Para obter mais informações sobre como armazenar com segurança o segredo do cliente, consulte Práticas recomendadas para gerenciamento de segredos no Cofre de Chaves.

Adicionar permissões para acessar sua API da Web

Ao especificar os escopos de uma API Web, o aplicativo Web pode obter um token de acesso contendo os escopos fornecidos pela plataforma de identidade da Microsoft. Dentro do 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.

Siga estas etapas para configurar as permissões do cliente para a API da Web:

  1. No painel Visão geral do seu aplicativo, em Gerenciar, selecione Permissões>de API Adicionar uma permissão>APIs que minha organização usa.
  2. Selecione NewWebAPI1 ou a API à qual você deseja adicionar permissões.
  3. Em Selecionar permissões, marque a caixa ao lado de Forecast.Read. Talvez seja necessário expandir a lista de Permissões . Isso seleciona as permissões que o aplicativo cliente deve ter em nome do usuário conectado.
  4. Selecione Adicionar permissões para concluir o processo.

Depois de adicionar essas permissões à sua API, você verá as permissões selecionadas em Permissões configuradas.

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.

Testar a API da Web

Para garantir que sua API esteja operacional e pronta para lidar com solicitações, siga estas etapas:

  1. Clone o repositório ms-identity-docs-code-dotnet .

    git clone https://github.com/Azure-Samples/ms-identity-docs-code-dotnet.git

  2. Navegue até ms-identity-docs-code-dotnet/web-api e abra appsettings.json, substitua o {APPLICATION_CLIENT_ID} e {DIRECTORY_TENANT_ID} pelos seguintes valores:

    • {APPLICATION_CLIENT_ID}é o ID do Aplicativo de API da Web (cliente) no painel Visão geral do aplicativo.
    • {DIRECTORY_TENANT_ID}é o ID do diretório da API da Web (locatário) no painel Visão geral do aplicativo.

  3. Execute o seguinte comando para iniciar o aplicativo:

    dotnet run

  4. Será apresentada uma saída semelhante à seguinte. Registre o número da https://localhost:{port} porta no URL.

    ...
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: https://localhost:{port}
...

Testar a API da Web

Para garantir que sua API esteja operacional e pronta para lidar com solicitações, siga estas etapas:

  1. Navegue até a API da Web que foi criada em Tutorial: Criar um projeto ASP.NET Core e configure a API, por exemplo NewWebAPILocal, e abra a pasta.

  2. Abra uma nova janela do terminal e navegue até a pasta onde o projeto de API da Web está localizado.

    1. Execute o seguinte comando para iniciar o aplicativo:

      dotnet run

  3. Será apresentada uma saída semelhante à seguinte. Registre o número da https://localhost:{port} porta no URL.

    ...
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: https://localhost:{port}
...

Configurar uma solicitação autorizada para a API da Web no Insomnia

Para obter um token de acesso para suas solicitações de API, siga estas etapas:

  1. Inicie o aplicativo Insônia .

  2. Selecione Nova Solicitação HTTP ou você pode usar Ctrl + N para criar uma nova Solicitação HTTP.

  3. No modal New Request, selecione um método GET na lista suspensa.

  4. Para a URL de solicitação, insira a URL do ponto de extremidade exposto pela API da Web, https://localhost:{port}/weatherforecast.

  5. No menu suspenso Auth , selecione OAuth 2.0. Isso exibe o formulário OAuth 2.0 .

  6. Insira os seguintes valores no formulário OAuth 2.0 :

    Definição Value
    TIPO DE SUBVENÇÃO Selecione o código de autorização
    URL DE AUTORIZAÇÃO https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/authorize
    Substitua {tenantId} pelo Directory (tenant)ID
    URL DO TOKEN DE ACESSO https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token
    Substitua {tenantId} pela ID do diretório (locatário)
    ID DO CLIENTE O valor da ID do aplicativo (cliente) do registro do aplicativo Web
    SEGREDO DO CLIENTE O segredo do cliente Valor do registo da sua aplicação Web
    URL de REDIRECIONAMENTO Digite http://localhost, que define a URL de REDIRECIONAMENTO para o URI de Redirecionamento registrado com a ID do Microsoft Entra.
    Opções>Avançadas ÂMBITO api://{application_client_id}/Forecast.Read
    Navegue até o registro do aplicativo Web, em Gerenciar, selecione Permissões de API e, em seguida, selecione Previsão.Leia
    Copie o valor na caixa de texto, que contém o valor Scope

Obter um token de acesso e enviar uma solicitação para a API da Web

  1. Depois que esses valores forem inseridos, selecione Buscar tokens no final do formulário. Isso abre uma janela do navegador Insomnia onde você se autentica com suas credenciais de usuário. Certifique-se de permitir pop-ups do aplicativo Insônia no navegador.
  2. Depois de autenticar, selecione Enviar para enviar a solicitação para o ponto de extremidade da API da Web protegida.

Com um token de acesso válido incluído na solicitação, a resposta esperada é 200 OK com saída semelhante a:

[
  {
    "date": "YYYY-MM-DDTHH:MM:SS",
    "temperatureC": -16,
    "summary": "Scorching",
    "temperatureF": 4
  },
  {
    "date": "YYYY-MM-DDTHH:MM:SS",
    "temperatureC": 1,
    "summary": "Sweltering",
    "temperatureF": 33
  },
  {
    "date": "YYYY-MM-DDTHH:MM:SS",
    "temperatureC": 26,
    "summary": "Freezing",
    "temperatureF": 78
  },
  {
    "date": "YYYY-MM-DDTHH:MM:SS",
    "temperatureC": 54,
    "summary": "Mild",
    "temperatureF": 129
  },
  {
    "date": "YYYY-MM-DDTHH:MM:SS",
    "temperatureC": 11,
    "summary": "Bracing",
    "temperatureF": 51
  }
]

Conteúdos relacionados

Para obter mais informações sobre o fluxo de código de autorização do OAuth 2.0 e os tipos de aplicativo, consulte: