Compartir vía

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

  • Artículo

En este artículo se muestra cómo llamar a una API web de ASP.NET Core protegida mediante Insomnia. Insomnia es una aplicación que permite enviar solicitudes HTTP a una API web para probar sus directivas de autorización y control de acceso (autenticación). 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 Insomnia.

En este artículo se muestra cómo llamar a una API web de ASP.NET Core protegida mediante Insomnia. Insomnia es una aplicación que permite enviar solicitudes HTTP a una API web para probar sus directivas de autorización y control de acceso (autenticación). 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 Insomnia.

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
  • Descargar e instalar Insomnia. Use Insomnia para obtener un token de acceso para las solicitudes de API.
  • Se necesita como mínimo el SDK de NET 8.0.

Registrar una aplicación

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. Puede ver el panel Información general de la aplicación cuando se completa el registro. Registre el id. de directorio (inquilino) y el id. de aplicación (cliente) que se usará en los pasos siguientes.

    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 introducido correctamente, aparece 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

No es suficiente tener una API web, también necesita una aplicación web para obtener un token de acceso para acceder a la API web.

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. Introduzca 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. Introduzca 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.

Puede ver el panel Información general de la aplicación cuando se completa el registro. 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.

Para obtener más información sobre cómo almacenar de forma segura el secreto de cliente, consulte Procedimientos recomendados para la administración de secretos en Key Vault.

Incorporación de permisos para acceder a la API web

Al especificar los ámbitos de una API 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 del cliente en la API web:

  1. En el panel Información general de la aplicación, en Administrar, seleccione Permisos de API>Agregar un permiso>API que mi organización usa.
  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

Para asegurarse de que la API está operativa y lista para controlar las solicitudes, siga estos pasos:

  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 ms-identity-docs-code-dotnet/web-api y abra appsettings.json, reemplace el {APPLICATION_CLIENT_ID} y {DIRECTORY_TENANT_ID} por los valores siguientes:

    • {APPLICATION_CLIENT_ID} es el id. de aplicación (cliente) de la API web ubicado en el panel Información general de la aplicación.
    • {DIRECTORY_TENANT_ID} es el id. de directorio (inquilino) de la API web ubicado en el 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

Para asegurarse de que la API está operativa y lista para controlar las solicitudes, siga estos pasos:

  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

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

Configuración de una solicitud autorizada a la API web en Insomnia

Para obtener un token de acceso para las solicitudes de API, siga estos pasos:

  1. Inicie la aplicación Insomnia.

  2. Seleccione Nueva solicitud HTTP o puede usar Ctrl + N para crear una nueva solicitud HTTP.

  3. En el modal Nueva solicitud, seleccione un método GET en la lista desplegable.

  4. En la dirección URL de la solicitud, escriba la URL del punto de conexión expuesto por la API web https://localhost:{port}/weatherforecast.

  5. En el menú desplegable Autenticación, seleccione OAuth 2.0. Esto muestra el formulario OAuth 2.0.

  6. Introduzca los valores siguientes en el formulario OAuth 2.0:

    Configuración Valor
    TIPO DE CONCESIÓN Seleccione Código de autorización
    DIRECCIÓN URL DE AUTORIZACIÓN https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/authorize
    Reemplace {tenantId} por el id. de directorio (inquilino)
    DIRECCIÓN URL DE TOKEN DE ACCESO https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token
    Reemplace {tenantId} por el id. de directorio (inquilino)
    IDENTIFICADOR DEL CLIENTE El valor del id. de aplicación (cliente) del registro de la aplicación web
    SECRETO DEL CLIENTE El valor del secreto de cliente del registro de la aplicación web
    DIRECCIÓN URL DE REDIRECCIONAMIENTO Introduzca http://localhost, que establece la dirección URL de REDIRECCIONAMIENTO en el URI de redireccionamiento registrado con Microsoft Entra ID.
    Opciones avanzadas>ÁMBITO api://{application_client_id}/Forecast.Read
    Vaya al registro de la aplicación web, en Administrar, seleccione Permisos de API y, después, seleccione Forecast.Read.
    Copie el valor en el cuadro de texto, que contiene el valor Ámbito

Obtención de un token de acceso y envío de una solicitud a la API web

  1. Una vez especificados estos valores, seleccione Capturar tokens al final del formulario. Esto inicia una ventana del explorador de Insomnia en la que se autentica con las credenciales de usuario. Asegúrese de permitir elementos emergentes de la aplicación Insomnia en el explorador.
  2. Después de autenticarse, seleccione Enviar para enviar la solicitud al punto de conexión de la API web protegida.

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

[
  {
    "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
  }
]

Contenido relacionado

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: