Llamada a una API web de ASP.NET Core con cURL

  • Artículo

Este artículo muestra cómo llamar a una API web de ASP.NET Core protegida mediante la dirección URL del cliente (cURL). cURL es una herramienta de línea de comandos que los desarrolladores usan para transferir datos hacia y desde un servidor. En este artículo, registrará una aplicación web y una API web en un inquilino. La aplicación web se usa para obtener un token de acceso generado por la plataforma de identidad de Microsoft. A continuación, use el token para hacer una llamada autorizada a la API web mediante cURL.

Este artículo muestra cómo llamar a una API web de ASP.NET Core protegida mediante la dirección URL del cliente (cURL). cURL es una herramienta de línea de comandos que los desarrolladores usan para transferir datos hacia y desde un servidor. A continuación, en el Tutorial: Implementación de un punto de conexión protegido en la API, donde creó una API protegida, debe registrar una aplicación web con la plataforma de identidad de Microsoft para generar un token de acceso. A continuación, use el token para hacer una llamada autorizada a la API mediante cURL.

Requisitos previos

  • Una cuenta de Azure con una suscripción activa. Cree una cuenta gratuita.
  • Esta cuenta de Azure debe tener permisos para administrar aplicaciones. Cualquiera de los siguientes roles de Microsoft Entra incluye los permisos necesarios:
    • Administrador de aplicaciones
    • Desarrollador de aplicaciones
    • Administrador de aplicaciones en la nube
  • Descargue e instale cURL en el equipo de la estación de trabajo.
  • Se requiere como mínimo el SDK de NET 6.0.

Registro de una aplicación en la plataforma de identidad de Microsoft

En la plataforma de identidad de Microsoft es necesario que la aplicación se registre para poder proporcionar servicios de administración de identidades y acceso. El registro de la aplicación permite indicar su nombre y su tipo de la aplicación y el público de inicio de sesión. El público de inicio de sesión especifica qué tipos de cuentas de usuario pueden iniciar sesión en una aplicación determinada.

Registro de la API web

Sugerencia

Los pasos de este artículo pueden variar ligeramente en función del portal desde donde comienza.

Siga estos pasos para crear el registro de la API web:

  1. Inicie sesión en el Centro de administración de Microsoft Entra al menos como Desarrollador de aplicaciones.

  2. Si tiene acceso a varios inquilinos, use el icono Configuración del menú superior para cambiar al inquilino en el que desea registrar la aplicación desde el menú Directorios y suscripciones.

  3. Vaya aIdentidad>Aplicaciones>Registros de aplicaciones.

  4. Seleccione Nuevo registro.

  5. Ponle un Nombre a la aplicación, como NewWebAPI1.

  6. Para la opción Tipos de cuenta admitidos, seleccione Solo las cuentas de este directorio organizativo. Para obtener información sobre los distintos tipos de cuenta, selecciona la opción Ayudarme a elegir.

  7. Seleccione Registrar.

    Captura de pantalla en la que se muestra cómo ingresar un nombre y seleccionar el tipo de cuenta.

  8. El panel Información general de la aplicación se muestra cuando se completa el registro. Registrar el id. de directorio (inquilino) y el id. de aplicación (cliente) que se usará en el código fuente de la aplicación.

    Captura de pantalla en la que se muestran los valores de identificador en la página de información general.

Nota

Los tipos de cuenta admitidos pueden modificarse consultando Modificar las cuentas que admite una aplicación.

Exposición de la API

Una vez registrada la API, para configurar su permiso, defina los ámbitos que la API expone a las aplicaciones cliente. Las aplicaciones cliente solicitan permiso para realizar operaciones mediante el paso de un token de acceso junto con sus solicitudes a la API web protegida. A continuación, la API web realiza la operación solicitada solo si el token de acceso que recibe es válido.

  1. En Administrar, seleccione Exponer una API > Agregar un ámbito. Seleccione Guardar y continuar para aceptar el URI de identificador de aplicación propuesto(api://{clientId}). {clientId} es el valor registrado en la página Información general. A continuación, escriba la siguiente información:

    1. Para Scope name (Nombre de ámbito), escriba Forecast.Read.
    2. Para Who can consent (Quién puede dar el consentimiento), asegúrese de que la opción Admins and users (Administradores y usuarios) está seleccionada.
    3. En el cuadro Admin consent display name (Nombre para mostrar del consentimiento del administrador), escriba Read forecast data (Acceder a TodoListService como usuario).
    4. En el cuadro Admin consent description (Descripción del consentimiento del administrador), escriba Allows the application to read weather forecast data (Accede a la API web TodoListService como usuario).
    5. En el cuadro User consent display name (Nombre para mostrar del consentimiento del usuario), escriba Read forecast data (Acceder a TodoListService como usuario).
    6. En el cuadro User consent description (Descripción del consentimiento del usuario), escriba Allows the application to read weather forecast data (Accede a la API web TodoListService como usuario).
    7. Asegúrate de que el Estado esté establecido en Habilitado.

  2. Seleccione la opción Agregar un ámbito. Si el ámbito se ha escrito correctamente, se mostrará en el panel Exponer una API.

    Captura de pantalla que muestra los valores de campo al agregar el ámbito a una API.

Registro de la aplicación web

Sin embargo, tener una API web no es suficiente, ya que también se necesita una aplicación web para obtener un token de acceso para acceder a la API web que ha creado.

Siga estos pasos para crear el registro de la aplicación de la aplicación web:

  1. Seleccione Inicio, para volver a la página principal. Vaya aIdentidad>Aplicaciones>Registros de aplicaciones.
  2. Seleccione Nuevo registro.
  3. Escriba un nombre para la aplicación, como web-app-calls-web-api.
  4. Para la opción Tipos de cuenta admitidos, seleccione Solo las cuentas de este directorio organizativo. Para obtener información sobre los distintos tipos de cuenta, selecciona la opción Ayudarme a elegir.
  5. En URI de redirección (opcional), seleccione Web y escriba http://localhost en el cuadro de texto.
  6. Seleccione Registrar.
  1. Inicie sesión en el Centro de administración de Microsoft Entra al menos como Desarrollador de aplicaciones.
  2. Si tiene acceso a varios inquilinos, use el icono Configuración del menú superior para cambiar al inquilino en el que desea registrar la aplicación desde el menú Directorios y suscripciones.
  3. Vaya aIdentidad>Aplicaciones>Registros de aplicaciones.
  4. Seleccione Nuevo registro.
  5. Escriba un nombre para la aplicación, como web-app-calls-web-api.
  6. Para la opción Tipos de cuenta admitidos, seleccione Solo las cuentas de este directorio organizativo. Para obtener información sobre los distintos tipos de cuenta, selecciona la opción Ayudarme a elegir.
  7. En URI de redirección (opcional), seleccione Web y escriba http://localhost en el cuadro de texto.
  8. Seleccione Registrar.

Después de completar el registro, el registro de aplicación se muestra en el panel Información general. Registre el id. de directorio (inquilino) y el id. de aplicación (cliente) que se usará en los pasos siguientes.

Agregar un secreto de cliente

Un secreto de cliente es un valor de cadena que la aplicación puede utilizar para la identidad propia y a veces se conoce como contraseña de aplicación. La aplicación web usa el secreto de cliente para demostrar su identidad al solicitar tokens.

Siga estos pasos para configurar un secreto de cliente:

  1. En el panel Información general, en Administrar, seleccione Certificados y secretos>Secretos de cliente>Nuevo secreto de cliente.

  2. Agregue una descripción para el secreto de cliente, por ejemplo, Mi secreto de cliente.

  3. Seleccione una expiración para el secreto o especifique una duración personalizada.

    • La duración de un secreto de cliente se limita a dos años (24 meses) o menos. No se puede especificar una duración personalizada superior a 24 meses.
    • Microsoft recomienda establecer un valor de expiración de menos de 12 meses.

  4. Seleccione Agregar.

  5. Asegúrese de registrar el valor del secreto de cliente. Este valor secreto no se volverá a mostrar una vez que abandone esta página.

Adición de permisos de aplicación para permitir el acceso a una API web

Al especificar los ámbitos de una API web en el registro de aplicación web, la aplicación web puede obtener un token de acceso que contenga esos ámbitos proporcionados por la plataforma de identidad de Microsoft. En el código, la API web puede proporcionar acceso basado en permisos a sus recursos en función de los ámbitos que se encuentran en el token de acceso.

Siga estos pasos para configurar los permisos de la aplicación web en la API web:

  1. En el panel Información general de la aplicación web (web-app-that-calls-web-api), en Administrar, seleccione Permisos de API>Agregar un permiso>Mis API.
  2. Seleccione NewWebAPI1 o la API a la que desea agregar permisos.
  3. En Seleccionar permisos, active la casilla situada junto a Forecast.Read. Es posible que tenga que expandir la lista Permisos. Esto selecciona los permisos que la aplicación cliente debe tener en nombre del usuario que ha iniciado sesión.
  4. Seleccione Agregar permisos para completar el proceso.

Después de agregar los permisos a la API, debería ver los permisos seleccionados en Permisos configurados.

También puede observar el permiso User.Read para Microsoft Graph API. Este permiso se agrega automáticamente al registrar una aplicación.

Prueba de la API web

  1. Clone el repositorio ms-identity-docs-code-dotnet.

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

  2. Vaya a la carpeta ms-identity-docs-code-dotnet/web-api y abra el archivo ./appsettings.json, reemplace {APPLICATION_CLIENT_ID} y {DIRECTORY_TENANT_ID} por:

    • {APPLICATION_CLIENT_ID} es el id. de aplicación (cliente) de la API web ubicado en Registros de aplicaciones del panel Información general de la aplicación.
    • {DIRECTORY_TENANT_ID} es el id. de directorio (inquilino) de la API web ubicado en Registros de aplicaciones del panel Información general de la aplicación.

  3. Ejecute el siguiente comando para iniciar la aplicación:

    dotnet run

  4. Obtendrá una salida similar a la siguiente. Registre el número de puerto en la dirección URL https://localhost:{port}.

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

Prueba de la API web

  1. Vaya a la API web que se creó en Tutorial: Creación de un proyecto de ASP.NET Core y configuración de la API, por ejemplo, NewWebAPILocal, y abra la carpeta.

  2. Abra una nueva ventana de terminal y vaya a la carpeta donde se ubica el proyecto de la API web.

  1. Ejecute el siguiente comando para iniciar la aplicación:

    dotnet run

  1. Obtendrá una salida similar a la siguiente. Registre el número de puerto en la dirección URL https://localhost:{port}.

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

Solicitud de un código de autorización

El flujo del código de autorización comienza con el cliente dirigiendo al usuario al punto de conexión /authorize . En esta solicitud, el cliente solicita el permiso Forecast.Read del usuario.

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 la dirección URL, reemplace los parámetros siguientes y péguela en el explorador:

    • {tenant_id} es el identificador de directorio (inquilino) de aplicación web.
    • {web-app-calls-web-api_application_client_id} es el id. de aplicación (cliente) del panel Información general de la aplicación web (web-app-calls-web-api).
    • {web_API_application_client_id} es el id. de aplicación (cliente) en el panel Información general de la API web (NewWebAPI1).

  2. Inicie sesión como usuario en el inquilino de Microsoft Entra en el que se registran las aplicaciones. Dé su consentimiento a las solicitudes de acceso, si es necesario.

  3. Se redirigirá el explorador a http://localhost/. Consulte la barra de navegación del explorador y copie {authorization_code} para usarlo en los pasos siguientes. La dirección URL tiene la forma del siguiente fragmento de código:

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

Uso de un código de autorización y cURL para obtener un token de acceso

cURL ahora se puede usar para solicitar un token de acceso desde la Plataforma de identidad de Microsoft.

  1. Copie el comando cURL en el siguiente fragmento de código. Reemplace los valores entre paréntesis por los parámetros siguientes en el terminal. Asegúrese de quitar los paréntesis:

    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} es el identificador de directorio (inquilino) de aplicación web.
    • client_id={web-app-calls-web-api_application_client_id} y session_state={web-app-calls-web-api_application_client_id} es el id. de aplicación (cliente) del panel Información general de la aplicación web web-app-calls-web-api.
    • api://{web_API_application_client_id}/Forecast.Read es el id. de aplicación (cliente) en el panel Información general de la API web (NewWebAPI1).
    • code={authorization_code} es el código de autorización que se ha recibido en Solicitar un código de autorización. Esto permite que la herramienta cURL solicite un token de acceso.
    • client_secret={client_secret} es el valor del secreto de cliente registrado en Agregar un secreto de cliente.

  2. Ejecute el comando cURL y, si se ha escrito correctamente, debe recibir una respuesta JSON similar a la siguiente salida:

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

Llamar a la API web con el token de acceso

Al ejecutar el comando cURL anterior, la Plataforma de identidad de Microsoft ha proporcionado un token de acceso. El token adquirido ahora se puede usar como portador en una solicitud HTTP para llamar a la API web.

  1. Para llamar a la API web, copie el siguiente comando cURL, reemplace los valores siguientes entre paréntesis y péguelos en el terminal:

    curl -X GET https://localhost:{port}/weatherforecast -ki \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer {access_token}"
    • {access_token} el valor del token de acceso registrado en la salida JSON de la sección anterior.
    • {port} el número de puerto de la API web registrada al ejecutar la API en el terminal. Asegúrese de que es el número de puerto https.

  2. Con un token de acceso válido incluido en la solicitud, la respuesta esperada es HTTP/2 200 con una salida similar a la siguiente:

    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}]

Pasos siguientes

Para más información sobre el flujo de código de autorización de OAuth 2.0 y los tipos de aplicación, consulte: