Compartilhar via

Chamar uma API Web do ASP.NET Core com o Insomnia

  • Artigo

Este artigo mostra como chamar uma API Web ASP.NET Core protegida usando o Insomnia. O Insomnia é um aplicativo que permite enviar solicitações HTTP a uma API Web para testar suas políticas de autorização e controle de acesso (autenticação). Neste artigo, você registrará 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, use o token para fazer uma chamada autorizada para a API Web usando o Insomnia.

Este artigo mostra como chamar uma API Web ASP.NET Core protegida usando o Insomnia. O Insomnia é um aplicativo que permite enviar solicitações HTTP a uma API Web para testar suas políticas de autorização e controle de acesso (autenticação). Continuando após o Tutorial: Implementar um ponto de extremidade protegido na sua API, em que você criou uma API protegida, será necessário registrar um aplicativo Web na plataforma de identidade da Microsoft para gerar um token de acesso. Em seguida, use o token para fazer uma chamada autorizada para a API usando o Insomnia.

Pré-requisitos

  • Uma conta do Azure com uma assinatura 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 de aplicativos
    • Desenvolvedor de Aplicativo
    • Administrador de Aplicativos de Nuvem
  • Baixar e instalar o Insomnia. Use o Insomnia para obter um token de acesso para suas solicitações de API.
  • Requisito mínimo de SDK do .NET 8.0.

Registrar um aplicativo

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 de aplicativo permite que você especifique o nome e o tipo do aplicativo e o público-alvo de entrada. O público-alvo de entrada especifica quais tipos de contas de usuário têm permissão para entrar em um determinado aplicativo.

Registrar a API Web

Dica

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

Siga estas etapas para criar o registro da API Web:

  1. Faça login 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 de 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é Identidade>Aplicativos>Registros do aplicativo.

  4. Selecione Novo registro.

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

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

  7. Selecione Registrar.

    Captura de tela que mostra como inserir um nome e selecionar o tipo de conta.

  8. Você poderá ver o painel Visão Geral do aplicativo quando o registro for concluído. Registre a ID do Diretório (locatário) e a ID do aplicativo (cliente) a ser usada em etapas futuras.

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

Observação

Os Tipos de conta com suporte podem ser alterados referindo-se a 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 Web protegida. A API Web executará a operação solicitada somente se o token de acesso recebido for válido.

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

    1. Para Nome do escopo, insira Forecast.Read.
    2. Para Quem pode consentir, verifique se a opção Administradores e usuários está selecionada.
    3. Na caixa Nome de exibição do consentimento do administrador, insira Read forecast data.
    4. Na caixa Descrição do consentimento do administrador, insira Allows the application to read weather forecast data.
    5. Na caixa Nome de exibição do consentimento do usuário, insira Read forecast data.
    6. Na caixa Descrição do consentimento do usuário, insira 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.

Registrar o aplicativo Web

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

Siga estas etapas para criar o registro do aplicativo Web:

  1. Selecione Página Inicial para voltar à página inicial. Navegue até Identidade>Aplicativos>Registros do aplicativo.
  2. Selecione Novo registro.
  3. Insira um Nome para o aplicativo, como web-app-calls-web-api.
  4. Para Tipos de contas com suporte, selecione Contas somente neste diretório organizacional. Para obter informações sobre diferentes tipos de conta, selecione a opção Ajudar-me a escolher.
  5. Em URI de Redirecionamento (opcional), selecione Web e, em seguida, insira http://localhost na caixa de texto da URL.
  6. Selecione Registrar.
  1. Faça login 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 de 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é Identidade>Aplicativos>Registros do aplicativo.
  4. Selecione Novo registro.
  5. Insira um Nome para o aplicativo, como web-app-calls-web-api.
  6. Para Tipos de contas com suporte, selecione Contas somente neste diretório organizacional. Para obter informações sobre diferentes tipos de conta, selecione a opção Ajudar-me a escolher.
  7. Em URI de Redirecionamento (opcional), selecione Web e, em seguida, insira http://localhost na caixa de texto da URL.
  8. Selecione Registrar.

Você poderá ver o painel Visão Geral do aplicativo quando o registro for concluído. Registre a ID do Diretório (locatário) e a ID do aplicativo (cliente) a ser usada em etapas futuras.

Adicionar um segredo do 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 e 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 data de expiração para o segredo ou especifique um tempo de vida personalizado.

    • O tempo de vida do segredo do cliente é limitado a dois anos (24 meses) ou menos. Você não pode especificar um tempo de vida personalizado por mais de 24 meses.
    • A Microsoft recomenda definir um valor de expiração inferior a 12 meses.

  4. Selecione Adicionar.

  5. Registre o Valor do segredo do cliente. Esse valor secreto nunca será exibido novamente depois que você sair dessa página.

Para obter mais informações sobre como armazenar com segurança o segredo do cliente, consulte Melhores práticas para o gerenciamento de segredos no Key Vault.

Adicionar permissões para acessar sua API Web

Ao especificar os escopos de uma API Web, o aplicativo Web pode obter um token de acesso que contém os escopos fornecidos pela plataforma de identidade da Microsoft. Dentro do código, a API Web pode fornecer acesso baseado em permissão a seus recursos com base nos escopos encontrados no token de acesso.

Siga estas etapas para configurar as permissões do cliente para a API 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 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 permissões à sua API, você deverá ver as permissões selecionadas em Permissões configuradas.

Você também poderá 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 Web

Para garantir que sua API esteja operacional e pronta para processar 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 {APPLICATION_CLIENT_ID} e {DIRECTORY_TENANT_ID} pelos seguintes valores:

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

  3. Execute o comando a seguir para iniciar o aplicativo:

    dotnet run

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

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

Testar a API Web

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

  1. Navegue até a API Web que foi criada no Tutorial : criar um projeto de ASP.NET Core e configurar a API, por exemplo, NewWebAPILocal e abra a pasta.

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

    1. Execute o comando a seguir para iniciar o aplicativo:

      dotnet run

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

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

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

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

  1. Inicie o aplicativo Insomnia.

  2. Selecione Nova Solicitação HTTP ou use Ctrl + N para criar uma solicitação HTTP.

  3. No modal Nova Solicitação, selecione um método GET na lista suspensa.

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

  5. Na lista suspensa Auth, selecione OAuth 2.0. Isso exibe o formulário OAuth 2.0.

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

    Configuração Valor
    TIPO DE CONCESSÃO Selecione Código de Autorização
    URL DE AUTORIZAÇÃO https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/authorize
    Substitua {tenantId} pela ID do Diretório (locatário)
    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
    SECRETO DO CLIENTE O Valor do segredo do cliente do registro do seu aplicativo Web
    URL DE REDIRECIONAMENTO Insira http://localhost, que define a URL de REDIRECIONAMENTO para o URI de Redirecionamento registrado no Microsoft Entra ID.
    Opções Avançadas>ESCOPO api://{application_client_id}/Forecast.Read
    Navegue até o registro do aplicativo Web, em Gerenciar, selecione Permissões de API e, em seguida, selecione Forecast.Read
    Copie o valor na caixa de texto, que contém o valor Escopo

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

  1. Depois que esses valores forem inseridos, selecione Buscar Tokens no final do formulário. Isso abre uma janela do navegador do Insomnia na qual você se autentica com as suas credenciais de usuário. Certifique-se de permitir pop-ups do aplicativo da Insomnia no navegador.
  2. Após a autenticação, selecione Enviar para enviar a solicitação ao ponto de extremidade protegido da API Web.

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údo relacionado

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