Llamada a una API en una aplicación demonio de Node.js de ejemplo

Artículo
10/25/2023

En esta guía, se usa una aplicación demonio de Node.js de ejemplo para mostrar cómo una aplicación demonio adquiere un token para llamar a una API web. Microsoft Entra protege la API web.

Una aplicación demonio adquiere un token en su propio nombre (no en nombre de un usuario). Los usuarios no pueden interactuar con una aplicación de demonio porque requiere su propia identidad. Este tipo de aplicación solicita un token de acceso mediante su identidad de aplicación y presenta el identificador de aplicación, las credenciales (contraseña o certificado) y el URI del identificador de aplicación al External ID.

Una aplicación demonio usa la concesión de credenciales del cliente OAuth 2.0 estándar. Para simplificar el proceso de adquisición del token, el ejemplo que se utiliza en este artículo usa la Biblioteca de autenticación de Microsoft para Node (MSAL Node).

Requisitos previos

Visual Studio Code u otro editor de código.
Node.js.
.NET 7.0 o posterior
Un inquilino externo. Si no tiene uno ya, suscríbase para obtener una prueba gratuita.

Registro de una aplicación demonio y una API web

En este paso, creará los registros de aplicación de la API web y el demonio, y especificará los ámbitos de la API web.

Registro de una aplicación de API web

Inicie sesión en el Centro de administración de Microsoft Entra al menos como Desarrollador de aplicaciones.
Si tiene acceso a varios inquilinos, use el icono Configuración en el menú superior para cambiar al inquilino externo desde el menú Directorios y suscripciones.
Vaya aIdentidad>Aplicaciones>Registros de aplicaciones.
Seleccione + Nuevo registro.
En la página Registrar una aplicación que aparece, escriba la información de registro de la aplicación:
1. En la sección Nombre, escriba un nombre significativo para la aplicación, que se mostrará a los usuarios de la aplicación, por ejemplo, ciam-ToDoList-api.
2. En Tipos de cuenta admitidos, seleccione Solo las cuentas de este directorio organizativo.
Seleccione Registrar para crear la aplicación.
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.

Configuración de roles de aplicación

Una API debe publicar al menos un rol de aplicación, también conocido como permiso de aplicación, para que las aplicaciones cliente obtengan un token de acceso en su propio nombre. Los permisos de aplicación son el tipo de permisos que las API deben publicar cuando quieran permitir que las aplicaciones cliente se autentiquen correctamente como ellas mismas y no necesiten registrar a los usuarios. Para publicar un permiso de aplicación, siga estos pasos:

En la página Registros de aplicaciones, seleccione la aplicación que creó (como ciam-ToDoList-api) para abrir la página Información general.
En Administrar, seleccione Roles de aplicación.

Seleccione Crear rol de aplicación, introduzca los siguientes valores y seleccione Aplicar para guardar los cambios:

Propiedad	Value
Nombre para mostrar	ToDoList.Read.All
Tipos de miembros permitido	Aplicaciones
Value	ToDoList.Read.All
Descripción	Permitir que la aplicación lea la lista de tareas pendientes de cada usuario utilizando ''TodoListApi''

Vuelva a seleccionar Crear rol de aplicación, introduzca los siguientes valores para el segundo rol de aplicación y seleccione Aplicar para guardar los cambios:

Propiedad	Value
Nombre para mostrar	ToDoList.ReadWrite.All
Tipos de miembros permitido	Aplicaciones
Value	ToDoList.ReadWrite.All
Descripción	Permitir que la aplicación lea y escriba cada lista de tareas pendientes de los usuarios mediante "ToDoListApi"

Configuración de notificaciones opcionales

Los tokens devueltos por la identidad de Microsoft se mantienen más pequeños para garantizar un rendimiento óptimo por parte de los clientes que los solicitan. Como resultado, varias notificaciones ya no están presentes en el token de manera predeterminada y deben solicitarse específicamente en cada solicitud. Para esta aplicación, se incluye la notificación opcional idtyp para ayudar a la API web a determinar si un token es un token de aplicación o un token de aplicación+usuario. Aunque es posible usar una combinación de notificaciones de scp y roles con el mismo propósito, el uso de la notificación idtyp es la manera más fácil de distinguir un token de aplicación de un token de aplicación+usuario. Por ejemplo, el valor de esta notificación es app cuando el token es un token solo para aplicaciones.

Siga estos pasos para configurar la notificación opcional idtyp:

En la página Registros de aplicaciones, para la que desea configurar una notificación opcional, como ciam-client-app, para abrir la página Información general.
En Administrar, seleccione Configuración del token.
Seleccione Agregar notificación opcional.
En Tipo de token, elija Acceso.
Seleccione la notificación opcional idtyp.
Haga clic en Agregar para guardar los cambios.

Registro de la aplicación demonio

Para permitir que su aplicación inicie la sesión de los usuarios con Microsoft Entra, la id. externa de Microsoft Entra debe tener en cuenta la aplicación que haya creado. El registro de la aplicación establece una relación de confianza entre la aplicación y Microsoft Entra. Al registrar una aplicación, External ID genera un identificador único conocido como Id. de aplicación (cliente), un valor que se usa para identificar la aplicación al crear solicitudes de autenticación.

En los pasos siguientes, se muestra cómo registrar una aplicación en el centro de administración de Microsoft Entra:

Inicie sesión en el Centro de administración de Microsoft Entra al menos como Desarrollador de aplicaciones.
Si tiene acceso a varios inquilinos, use el icono Configuración en el menú superior para cambiar al inquilino externo desde el menú Directorios y suscripciones.
Vaya aIdentidad>Aplicaciones>Registros de aplicaciones.
Seleccione + Nuevo registro.
En la página Registrar una aplicación que aparece;
1. Introduzca un Nombre de aplicación significativo que se muestre a los usuarios de la aplicación, por ejemplo ciam-client-app.
2. En Tipos de cuenta admitidos, seleccione Solo las cuentas de este directorio organizativo.
Seleccione Registrar.
Se muestra el panel Información general de la aplicación tras registrarse correctamente. Registre el Id. de la aplicación (cliente) que se usará en el código fuente de la aplicación.

Creación de un secreto de cliente

Cree un secreto de cliente para la aplicación registrada. La aplicación usa el secreto de cliente para demostrar su identidad al solicitar tokens.

En la página Registros de aplicaciones, seleccione la aplicación que creó (como ciam-client-app) para abrir la página Información general.
En Administrar, seleccione Certificados y secretos.
Seleccione Nuevo secreto de cliente.
Escriba una descripción para el secreto de cliente en el cuadro Descripción (por ejemplo, secreto de cliente de ciam app).
En Expira, seleccione el tiempo durante el cual es válido el secreto (según las reglas de seguridad de su organización) y, a continuación, elija Agregar.
Registre el Valor del secreto. Este valor se usará para la configuración en un paso posterior. El valor del secreto no se volverá a mostrar y no se podrá recuperar por ningún medio, después de salir del Certificados y secretos. Asegúrese de grabarlo.

Concesión de permisos de API a la aplicación demonio

En la página Registros de aplicaciones, seleccione la aplicación que creó (como ciam-client-app).
En Administrar, seleccione Permisos de API.
En Permisos configurados, seleccione Agregar un permiso.
Seleccione la pestaña API usadas en mi organización.
En la lista de API, seleccione la API como ciam-ToDoList-api.
Seleccione la opción Permisos de aplicación. Se selecciona esta opción porque la aplicación se registra como tal, no como usuario.
En la lista de permisos, seleccione TodoList.Read.All, ToDoList.ReadWrite.All (use el cuadro de búsqueda si es necesario).
Seleccione el botón Agregar permisos.
En este momento, ha asignado los permisos correctamente. Sin embargo, dado que la aplicación demonio no permite a los usuarios interactuar con ella, los propios usuarios no pueden dar su consentimiento a estos permisos. Para solucionar este problema, como administrador debe consentir estos permisos en nombre de todos los usuarios del inquilino:
1. Seleccione Conceder consentimiento del administrador para el <nombre del inquilino> y, a continuación, pulse Sí.
2. Seleccione Actualizar, luego compruebe que aparece Concedido para <el nombre de inquilino> en Estado para ambos permisos.

Clonación o descarga de una aplicación demonio y API web de ejemplo

Para obtener la aplicación de ejemplo, puede clonarla desde GitHub o descargarla como archivo .zip.

Para clonar la muestra, abra un símbolo del sistema y navegue hasta donde desea crear el proyecto, e introduzca el siguiente comando:
```
git clone https://github.com/Azure-Samples/ms-identity-ciam-javascript-tutorial.git
```
Descargue el archivo .zip. Extráigalo en una ruta de acceso de archivo donde la longitud del nombre sea inferior a 260 caracteres.

Instalación de dependencias del proyecto

Abra una ventana de consola y cambie al directorio que contiene la aplicación Node.js de ejemplo:
```
cd 2-Authorization\3-call-api-node-daemon\App
```
Ejecute los siguientes comandos para instalar las dependencias de la aplicación:
```
npm install && npm update
```

Configuración de la aplicación demonio y API de ejemplo

Para usar el registro de la aplicación en el ejemplo de aplicación web cliente:

En el editor de código, abra el archivo App\authConfig.js.
Busque el marcador de posición:
- Enter_the_Application_Id_Here y reemplácelo por el identificador de aplicación (cliente) de la aplicación demonio que registró anteriormente.
- Enter_the_Tenant_Subdomain_Here y reemplácelo por el subdominio del directorio (inquilino). Por ejemplo, si el dominio principal del inquilino es contoso.onmicrosoft.com, use contoso. Si no tiene el nombre del inquilino, aprenda a leer los detalles del inquilino.
- Enter_the_Client_Secret_Here y reemplácelo por el valor secreto de aplicación demonio que copió anteriormente.
- Enter_the_Web_Api_Application_Id_Here y reemplácelo por el id. de aplicación (cliente) de la API web que copió anteriormente.

Para usar el registro de la aplicación en el ejemplo de API web:

En el editor de código, abra el archivo API\ToDoListAPI\appsettings.json.
Busque el marcador de posición:
- Enter_the_Application_Id_Here y reemplácelo por el id. de aplicación (cliente) de la API web que copió.
- Enter_the_Tenant_Id_Here y reemplácelo por el identificador de directorio (inquilino) que copió anteriormente.
- Enter_the_Tenant_Subdomain_Here y reemplácelo por el subdominio del directorio (inquilino). Por ejemplo, si el dominio principal del inquilino es contoso.onmicrosoft.com, use contoso. Si no tiene el nombre del inquilino, aprenda a leer los detalles del inquilino.

Ejecución y prueba de la aplicación demonio y API de ejemplo

Abra una ventana de consola y ejecute la API web mediante los siguientes comandos:
```
cd 2-Authorization\3-call-api-node-daemon\API\ToDoListAPI
dotnet run
```
Ejecute el cliente de la aplicación web mediante los siguientes comandos:
```
2-Authorization\3-call-api-node-daemon\App
node . --op getToDos
```

Si la aplicación demonio y la API web se ejecutan correctamente, debería ver algo similar a la matriz JSON siguiente en la ventana de la consola.

{
    "id": 1,
    "owner": "3e8....-db63-43a2-a767-5d7db...",
    "description": "Pick up grocery"
},
{
    "id": 2,
    "owner": "c3cc....-c4ec-4531-a197-cb919ed.....",
    "description": "Finish invoice report"
},
{
    "id": 3,
    "owner": "a35e....-3b8a-4632-8c4f-ffb840d.....",
    "description": "Water plants"
}

Funcionamiento

La aplicación Node.js usa la concesión de credenciales de cliente OAuth 2.0 para adquirir un token de acceso para sí mismo y no para el usuario. El token de acceso que la aplicación solicita contiene los permisos representados como roles. El flujo de credenciales de cliente usa este conjunto de permisos en lugar de ámbitos de usuario para tokens de aplicación. Ha expuesto estos permisos de aplicación en la API web anteriormente, por lo que los ha concedido a la aplicación demonio.

Por parte de la API, la API web debe comprobar que el token de acceso tiene los permisos necesarios (permisos de aplicación). La API web no puede aceptar un token de acceso que no tenga los permisos necesarios.

Acceso a datos

Un punto de conexión de API web debe estar preparado para aceptar llamadas de usuarios y aplicaciones. Por lo tanto, debe tener una manera de responder a cada solicitud según corresponda. Por ejemplo, una llamada de un usuario a través de permisos o ámbitos delegados recibe la lista de tareas pendientes de datos del usuario. Por otro lado, una llamada desde una aplicación a través de permisos o roles de aplicación puede recibir toda la lista de tareas pendientes. Sin embargo, en este artículo solo hacemos una llamada a la aplicación, por lo que no es necesario configurar los permisos o ámbitos delegados.