Inicio rápido: Adquisición de un token y llamada a Microsoft Graph desde una aplicación de consola de Node.js

Artículo
10/25/2023

En este inicio rápido descargará y ejecutará un código de ejemplo que muestra cómo puede obtener una aplicación de consola de Node.js un token de acceso mediante la identidad de la aplicación para llamar a Microsoft Graph API y mostrar una lista de usuarios en el directorio. En el ejemplo de código se muestra cómo se puede ejecutar un trabajo desatendido o un servicio de Windows con una identidad de aplicación, en lugar de la identidad de un usuario.

En este inicio rápido se usa la biblioteca de autenticación de Microsoft para Node.js (MSAL Node) con la concesión de credenciales de cliente.

Prerrequisitos

Node.js
Visual Studio Code u otro editor de código

Registro y descarga de la aplicación de ejemplo

Para comenzar, siga estos pasos.

Paso 1: Registro de la aplicación

Sugerencia

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

Para registrar la aplicación y agregar la información de registro de la aplicación a la solución de forma manual, siga estos pasos:

Inicie sesión en el Centro de administración de Microsoft Entra al menos como Administrador de aplicaciones.
Vaya aIdentidad>Aplicaciones>Registros de aplicaciones.
Seleccione Nuevo registro.
Escriba el Nombre de la aplicación, por ejemplo msal-node-cli. Los usuarios de la aplicación pueden ver este nombre, el cual se puede cambiar más tarde.
Seleccione Registrar.
En Administrar, seleccione Certificados y secretos.
En Secretos de cliente, seleccione Nuevo secreto de cliente, escriba un nombre y seleccione Agregar. Grabe el valor del secreto en una ubicación segura para usarlo en un paso posterior.
En Administrar, seleccione Permisos de API>Add a permission (Agregar un permiso). Seleccione Microsoft Graph.
Seleccione Permisos de aplicación.
En el nodo Usuario, seleccione User.Read.All y, luego, Agregar permisos.

Paso 2: Descarga del proyecto de ejemplo en Node.js

Descargar el código de ejemplo

Paso 3: Configuración del proyecto de ejemplo en Node.js

Extraiga el archivo ZIP en una carpeta local próxima a la raíz del disco, por ejemplo, C:\Azure-Samples.
Edite .env y sustituya los valores de los campos TENANT_ID, CLIENT_ID y CLIENT_SECRET por el siguiente fragmento de código:
```
"TENANT_ID": "Enter_the_Tenant_Id_Here",
"CLIENT_ID": "Enter_the_Application_Id_Here",
"CLIENT_SECRET": "Enter_the_Client_Secret_Here"
```
Donde:
- Enter_the_Application_Id_Here: es el id. de aplicación (cliente) de la aplicación que registró anteriormente. Búsquelo en el panel Información general del registro de la aplicación.
- Enter_the_Tenant_Id_Here: sustituya este valor por el identificador de inquilino o el nombre de inquilino (por ejemplo, contoso.microsoft.com). Estos valores se pueden buscar en el panel Información general del registro de la aplicación.
- Enter_the_Client_Secret_Here: sustituya este valor por el secreto de cliente que creó anteriormente. Para generar una nueva clave, use Certificados y secretos en la configuración del registro de aplicaciones.
El uso de un secreto de texto no cifrado en el código fuente supone un mayor riesgo de seguridad para la aplicación. Aunque en el ejemplo de este inicio rápido se use un secreto de cliente de texto no cifrado, es solo por simplicidad. Se recomienda usar credenciales de certificado, en lugar de secretos de cliente en las aplicaciones cliente confidenciales, especialmente en las que pretenda implementar en producción.
Edite .env y reemplace los puntos de conexión de Microsoft Entra ID y Microsoft Graph por los valores siguientes:
- En el punto de conexión de Microsoft Entra, reemplace Enter_the_Cloud_Instance_Id_Here por https://login.microsoftonline.com.
- Reemplace el punto de conexión de Microsoft Graph por Enter_the_Graph_Endpoint_Here con https://graph.microsoft.com/.

Si intenta ejecutar la aplicación en este momento, recibirá un error HTTP 403 - Prohibido: Insufficient privileges to complete the operation. Este error se produce porque cualquier permiso de solo aplicación requiere el consentimiento del administrador: un administrador de aplicación o un administrador global debe dar su consentimiento a la aplicación. Seleccione una de las opciones siguientes según el rol:

Administradores

Si tiene asignados los roles Administrador de aplicación o Administrador global, vaya a la página Permisos de API del Registro de aplicaciones de Azure Portal y seleccione Conceder consentimiento de administrador para {Nombre de inquilino} (donde {Nombre del inquilino} es el nombre de su directorio).

Usuarios estándar

Si es un usuario estándar del inquilino, debe pedir a un administrador global que conceda consentimiento del administrador para la aplicación. Para ello, proporcione la siguiente dirección URL a su administrador:

https://login.microsoftonline.com/Enter_the_Tenant_Id_Here/adminconsent?client_id=Enter_the_Application_Id_Here

Donde:

Enter_the_Tenant_Id_Here: sustituya este valor por el identificador de inquilino o el nombre de inquilino (por ejemplo, contoso.microsoft.com).
Enter_the_Application_Id_Here: es el identificador de aplicación (cliente) de la aplicación que registró.

Paso 5: Ejecución de la aplicación

Busque la carpeta raíz del ejemplo (donde package.json reside) en una consola o un símbolo del sistema. Deberá instalar las dependencias que necesita la aplicación de ejemplo antes de ejecutarla por primera vez:

npm install

A continuación, ejecute la aplicación a través del símbolo del sistema o la consola:

node . --op getUsers

Debería ver en la salida de la consola algún fragmento de JSON que represente una lista de los usuarios del directorio de Microsoft Entra.

Sobre el código

A continuación, se describen algunos de los aspectos importantes de la aplicación de ejemplo.

MSAL Node

MSAL Node es la biblioteca que se usa para iniciar la sesión de los usuarios y solicitar los tokens que se usan para acceder a una API protegida por la plataforma de identidad de Microsoft. Como se ha descrito, en este inicio rápido se solicitan tokens por permisos de aplicación (mediante la identidad propia de la aplicación), en lugar de permisos delegados. El flujo de autenticación usado en este caso se conoce como flujo de credenciales de cliente de OAuth 2.0. Para más información sobre cómo usar MSAL Node con aplicaciones de demonio, consulte Escenario: aplicación demonio.

Para instalar MSAL Node, ejecute el siguiente comando npm.

npm install @azure/msal-node --save

Inicialización de MSAL

Puede agregar la referencia de MSAL con el código siguiente:

const msal = require('@azure/msal-node');

A continuación, realice la inicialización de MSAL con el siguiente código:

const msalConfig = {
    auth: {
        clientId: "Enter_the_Application_Id_Here",
        authority: "https://login.microsoftonline.com/Enter_the_Tenant_Id_Here",
        clientSecret: "Enter_the_Client_Secret_Here",
   }
};
const cca = new msal.ConfidentialClientApplication(msalConfig);

Donde:	Descripción
`clientId`	Es el Identificador de aplicación (cliente) de la aplicación registrada en Azure Portal. Puede encontrar este valor en la página Información general de la aplicación en Azure Portal.
`authority`	El punto de conexión STS para el usuario que se autenticará. Normalmente `https://login.microsoftonline.com/{tenant}` en la nube pública, donde {tenant} es el nombre o el identificador del inquilino.
`clientSecret`	Es el secreto de cliente creado para la aplicación en Azure Portal.

Para más información, consulte la documentación de referencia de ConfidentialClientApplication.

Solicitud de tokens

Para solicitar un token mediante la identidad de la aplicación, use el método acquireTokenByClientCredential:

const tokenRequest = {
    scopes: [ 'https://graph.microsoft.com/.default' ],
};

const tokenResponse = await cca.acquireTokenByClientCredential(tokenRequest);

Donde: Descripción

tokenRequest Contiene los ámbitos solicitados. Con clientes confidenciales se debe usar un formato similar a {Application ID URI}/.default para indicar que los ámbitos que se solicitan son los definidos estáticamente en el objeto de aplicación establecido en Azure Portal (con Microsoft Graph, {Application ID URI} apunta a https://graph.microsoft.com). En el caso de las API web personalizadas, {Application ID URI} se define en la sección Exponer una API del registro de aplicación de Azure Portal.

tokenResponse La respuesta contiene un token de acceso para los ámbitos solicitados.

Donde:	Descripción
`tokenRequest`	Contiene los ámbitos solicitados. Con clientes confidenciales se debe usar un formato similar a `{Application ID URI}/.default` para indicar que los ámbitos que se solicitan son los definidos estáticamente en el objeto de aplicación establecido en Azure Portal (con Microsoft Graph, `{Application ID URI}` apunta a `https://graph.microsoft.com`). En el caso de las API web personalizadas, `{Application ID URI}` se define en la sección Exponer una API del registro de aplicación de Azure Portal.
`tokenResponse`	La respuesta contiene un token de acceso para los ámbitos solicitados.

Ayuda y soporte técnico

Si necesita ayuda, desea informar de un problema o desea obtener información sobre las opciones de soporte técnico, consulte Opciones de ayuda y soporte técnico para desarrolladores.

Pasos siguientes

Para más información sobre el desarrollo de aplicaciones de consola o demonio con MSAL Node, consulte el tutorial:

Aplicación demonio que llama a las API web