Chamar uma API Web ASP.NET Core com cURL

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

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

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
• Transfira e instale o cURL no computador da estação de trabalho.
• Um requisito mínimo do SDK do .NET 6.0.

• 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
• Conclusão da série de tutoriais:
  • Tutorial: Registrar a API da Web com a plataforma de identidade da Microsoft.
  • Tutorial: Crie e configure um projeto ASP.NET Core para autenticação.
  • Tutorial: Implemente um ponto de extremidade protegido em sua API.
• Transfira e instale o cURL no computador da estação de trabalho.

Registar uma aplicação 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 do aplicativo permite que você especifique o nome, 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.

   

8. O painel Visão geral do aplicativo é exibido quando o registro é concluído. Registre o ID do diretório (locatário) e o ID do aplicativo (cliente) a serem usados no código-fonte do aplicativo.

   

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 será listado no painel Expor uma API .

   

Registar a aplicação Web

No entanto, ter uma API da Web não é suficiente, pois um aplicativo da Web também é necessário para obter um token de acesso para acessar a API da Web que você criou.

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.

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

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

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

1. No painel Visão geral do seu 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 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

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

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

3. Execute o seguinte comando para iniciar o aplicativo:

   .NET 6.0

   dotnet run
   

   .NET 7.0

   dotnet run --launch-profile https
   

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

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.

.NET 6.0

1. Execute o seguinte comando para iniciar o aplicativo:

   dotnet run
   

.NET 7.0

1. Execute o seguinte comando para iniciar o aplicativo no https perfil:

   dotnet run --launch-profile https
   

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

Solicitar um código de autorização

O fluxo de código de autorização começa com o cliente direcionando o usuário para o /authorize ponto de extremidade. Nesta solicitação, o cliente solicita a Forecast.Read permissão 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 o URL, substitua os seguintes parâmetros e cole-o no seu 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) no painel Visão geral do aplicativo Web (web-app-calls-web-api).
   • {web_API_application_client_id}é a ID do aplicativo (cliente) no painel Visão geral da API da Web (NewWebAPI1).

2. Entre como usuário no locatário do Microsoft Entra no qual os aplicativos estão registrados. Consentimento para quaisquer pedidos de acesso, se necessário.

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

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

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

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

1. Copie o comando cURL no trecho a seguir. Substitua os valores entre parênteses pelos seguintes parâmetros no seu terminal. Certifique-se de remover 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}session_state={web-app-calls-web-api_application_client_id} e é a ID do aplicativo (cliente) no painel Visão geral do aplicativo Web (web-app-calls-web-api).
   • api://{web_API_application_client_id}/Forecast.Readé a ID do aplicativo (cliente) no painel Visão geral da API da Web (NewWebAPI1).
   • code={authorization_code} é o código de autorização que foi recebido em Solicitar um código de autorização. Isso permite que a ferramenta cURL solicite um token de acesso.
   • client_secret={client_secret}é o valor secreto do cliente registrado em Adicionar um segredo do cliente.

2. Execute o comando cURL e, se inserido corretamente, você 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 API da Web com 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 da Web.

1. Para chamar a API da Web, copie o seguinte comando cURL, substitua os seguintes valores entre parênteses e cole-o 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 da Web gravado ao executar a API no terminal. Certifique-se de que é o número da https porta.

2. Com um token de acesso válido incluído na solicitação, a resposta esperada é HTTP/2 200 com 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óximos passos

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

• Plataforma de identidades da Microsoft e fluxo de código de autorização OAuth 2.0
• Tipos de aplicação para a plataforma de identidades da Microsoft