Chamar uma API Web ASP.NET Core com o cURL

  • Artigo

Este artigo mostra como chamar uma API Web ASP.NET Core protegida usando a URL do cliente (cURL). O cURL é uma ferramenta de linha de comando que os desenvolvedores usam para transferir dados de um servidor ou para ele. 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, você usará o token para fazer uma chamada autorizada à API Web usando o cURL.

Este artigo mostra como chamar uma API Web ASP.NET Core protegida usando a URL do cliente (cURL). O cURL é uma ferramenta de linha de comando que os desenvolvedores usam para transferir dados de um servidor ou para ele. 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, você usará o token para fazer uma chamada autorizada à API usando o cURL.

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 aplicativos
    • Administrador de Aplicativos de Nuvem
  • Baixar e instalar o cURL no computador da estação de trabalho.
  • Um requisito mínimo do SDK 6.0 do .NET.

Registrar um aplicativo na plataforma de identidade da Microsoft

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. O painel Visão geral do aplicativo é exibido quando o registro é concluído. Registre a ID do Diretório (locatário) e a ID do aplicativo (cliente) a ser usada no código-fonte do aplicativo.

    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 será listado 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

Ter uma API Web não é por si só suficiente, pois um aplicativo Web também é necessário para obter um token de acesso para acessar a API Web que você criou.

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.

Quando o registro é concluído, o registro do aplicativo é exibido no painel Visão geral. 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.

Adicionar permissões de aplicativo para permitir o acesso a uma API Web

Ao especificar os escopos de uma API Web no registro do aplicativo 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 aplicativo Web para a API Web:

  1. No painel Visão geral do aplicativo Web (web-app-that-calls-web-api), em Gerenciar, selecione Permissões de API>Adicionar uma permissão>Minhas APIs.
  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

  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é a pasta ms-identity-docs-code-dotnet/web-api e abra o arquivo ./appsettings.json, substitua e o {APPLICATION_CLIENT_ID} e {DIRECTORY_TENANT_ID} por:

    • {APPLICATION_CLIENT_ID} é a ID do Aplicativo (cliente) da API Web no painel Visão GeralRegistros de aplicativo do aplicativo.
    • {DIRECTORY_TENANT_ID} é a ID do Diretório (locatário) da API Web no painel Visão GeralRegistros de aplicativo 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

  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

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

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

Solicitar um código de autorização

O fluxo do código de autorização começa com o cliente direcionando o usuário para o ponto de extremidade /authorize . Nessa solicitação, o cliente solicita as permissão Forecast.Read do usuário.

https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/authorize?client_id={web-app-calls-web-api_application_client_id}&response_type=code&redirect_uri=http://localhost&response_mode=query&scope=api://{web_API_application_client_id}/Forecast.Read

  1. Copie a URL, substitua os seguintes parâmetros e cole-a no navegador:

    • {tenant_id} é a ID do diretório (locatário) do aplicativo Web.
    • {web-app-calls-web-api_application_client_id} é a ID do Aplicativo (cliente) do aplicativo Web (web-app-calls-web-api) no painel Visão Geral.
    • {web_API_application_client_id} é a ID do Aplicativo (cliente) da API Web (NewWebAPI1) no painel Visão Geral.

  2. Entre como um usuário no locatário do Microsoft Entra no qual os aplicativos estão registrados. Dê o consentimento para quaisquer solicitações de acesso, se necessário.

  3. Você será redirecionado para http://localhost/. Consulte a barra de navegação do navegador e copie o {authorization_code} para usar nas etapas a seguir. A URL assume a forma do seguinte snippet:

    http://localhost/?code={authorization_code}

Usar um código de autorização e um comando cURL para obter um token de acesso

O cURL agora pode ser usado para solicitar um token de acesso do plataforma de identidade da Microsoft.

  1. Copie o comando cURL no snippet a seguir. Substitua os valores entre parênteses pelos seguintes parâmetros para o terminal. Remova os parênteses:

    curl -X POST https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/token \
-d 'client_id={web-app-calls-web-api_application_client_id}' \
-d 'api://{web_API_application_client_id}/Forecast.Read' \
-d 'code={authorization_code}&session_state={web-app-calls-web-api_application_client_id}' \
-d 'redirect_uri=http://localhost' \
-d 'grant_type=authorization_code' \
-d 'client_secret={client_secret}'
    • {tenant_id} é a ID do diretório (locatário) do aplicativo Web.
    • client_id={web-app-calls-web-api_application_client_id} e session_state={web-app-calls-web-api_application_client_id} é a ID do Aplicativo (cliente) do aplicativo Web (web-app-calls-web-api) no painel Visão Geral.
    • api://{web_API_application_client_id}/Forecast.Read é a ID do Aplicativo (cliente) da API Web (NewWebAPI1) no painel Visão Geral.
    • code={authorization_code} é o código de autorização recebido após Solicitar um código de autorização. Isso permite que a ferramenta cURL solicite um token de acesso.
    • client_secret={client_secret} é o Valor do segredo do cliente registrado em Adicionar um segredo do cliente.

  2. Execute o comando cURL e, se inserido corretamente, você deverá receber uma resposta JSON semelhante à seguinte saída:

    {
   "token_type": "Bearer",
   "scope": "api://{web_API_application_client_id}/Forecast.Read",
   "expires_in": 3600,
   "ext_expires_in": 3600,
   "access_token": "{access_token}"
}

Chamar uma API Web com um token de acesso

Ao executar o comando cURL anterior, a plataforma de identidade da Microsoft forneceu um token de acesso. O token adquirido agora pode ser usado como portador em uma solicitação HTTP para chamar a API Web.

  1. Para chamar a API Web, copie o seguinte comando cURL, substitua os seguintes valores entre parênteses e cole-os no terminal:

    curl -X GET https://localhost:{port}/weatherforecast -ki \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer {access_token}"
    • {access_token} o valor do token de acesso registrado a partir da saída JSON na seção anterior.
    • {port} o número da porta da API Web registrada ao executar a API no termina. Verifique se é o número da porta https.

  2. Com um token de acesso válido incluído na solicitação, a resposta esperada é HTTP/2 200 com uma saída semelhante à seguinte saída:

    HTTP/2 200
content-type: application/json; charset=utf-8
date: Day, DD Month YYYY HH:MM:SS
server: Kestrel
[{"date":"YYYY-MM-DDTHH:MM:SS","temperatureC":36,"summary":"Hot","temperatureF":96},{"date":"YYYY-MM-DDTHH:MM:SS","temperatureC":43,"summary":"Warm","temperatureF":109},{"date":"YYYY-MM-DDTHH:MM:SS","temperatureC":18,"summary":"Warm","temperatureF":64},{"date":"YYYY-MM-DDTHH:MM:SS","temperatureC":50,"summary":"Chilly","temperatureF":121},{"date":"YYYY-MM-DDTHH:MM:SS","temperatureC":3,"summary":"Bracing","temperatureF":37}]

Próximas etapas

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