Inicio de sesión de usuarios y llamada a una API en una aplicación web Node.js de ejemplo
En esta guía se usa una aplicación web Node.js de ejemplo para mostrar cómo agregar autenticación y autorización. La aplicación de ejemplo inicia sesión de usuarios en una aplicación web Node.js, que luego llama a una API .NET. Puede habilitar la autenticación y la autorización mediante los detalles del inquilino externo. La aplicación web de ejemplo usa la Biblioteca de autenticación de Microsoft (MSAL) para Node para controlar la autenticación.
En este artículo, se realizarán las siguientes tareas:
Registre y configure una API web en el centro de administración de Microsoft Entra.
Registre y configure una aplicación web cliente en el centro de administración de Microsoft Entra.
Cree un flujo de usuarios de registro e inicio de sesión en el centro de administración de Microsoft Entra y, a continuación, asocie una aplicación web cliente con ella.
Actualice una aplicación web de Node de ejemplo y una API web de ASP.NET para usar los detalles del inquilino externo.
Ejecute y pruebe la aplicación web y la API de ejemplo.
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 web y una API web
En este paso, creará los registros de aplicaciones web y de API web, 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:
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.
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 ámbitos de API
Esta API debe exponer permisos, que un cliente debe adquirir para llamar a la API:
Una API debe publicar un mínimo de un ámbito, también denominado Permiso delegado, para que las aplicaciones cliente obtengan un token de acceso para un usuario correctamente. Para publicar un ámbito, siga estos pasos:
En la página Registros de aplicaciones, seleccione la API que creó (como ciam-ToDoList-api) para abrir la página Información general.
En Administrar, seleccione Exponer una API.
En la parte superior de la página, junto a URI de id. de aplicación, seleccione el vínculo Agregar para generar un URI que sea único para esta aplicación.
Acepte el URI de identificador de aplicación propuesto, como
api://{clientId}
, y seleccione Guardar. Cuando la aplicación web solicite un token de acceso para la API web, deberá agregar este URI como prefijo para cada ámbito que se defina para la API.En Ámbitos definidos con esta API, seleccione Agregar un ámbito.
Escriba los valores siguientes que definan el acceso de lectura a la API y, a continuación, seleccione Agregar ámbito para guardar los cambios:
Propiedad valor Nombre de ámbito ToDoList.Read ¿Quién puede dar el consentimiento? Solo administradores Nombre para mostrar del consentimiento del administrador Leer una lista de tareas pendientes de los usuarios con "TodoListApi" Descripción del consentimiento del administrador Permite que la aplicación lea la lista de tareas pendientes del usuario utilizando ''TodoListApi''. State Enabled Seleccione Agregar un ámbito de nuevo y escriba los valores siguientes que definen el ámbito de acceso de lectura y escritura a la API. Seleccione Agregar ámbito para guardar los cambios:
Propiedad valor Nombre de ámbito ToDoList.ReadWrite ¿Quién puede dar el consentimiento? Solo administradores Nombre para mostrar del consentimiento del administrador Leer y escribir una lista de tareas pendientes con 'ToDoListApi' Descripción del consentimiento del administrador Permitir que la aplicación lea y escriba la lista de tareas pendientes de los usuarios mediante "ToDoListApi" State Enabled En Administrar, seleccione Manifiesto para abrir el editor de manifiesto de API.
Establezca la propiedad
accessTokenAcceptedVersion
en2
.Seleccione Guardar.
Obtenga más información sobre el principio de privilegios mínimos al publicar permisos para una API web.
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
Puede incluir 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, usar 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.
Registro de la aplicación web
Para permitir que su aplicación inicie la sesión de los usuarios con Microsoft Entra, 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;
- Introduzca un Nombre de aplicación significativo que se muestre a los usuarios de la aplicación, por ejemplo ciam-client-app.
- 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.
Para especificar el tipo de aplicación en el registro de la aplicación, siga estos pasos:
- En Administrar, seleccione Autenticación.
- En la página Configuraciones de plataforma, seleccione Agregar una plataforma y, a continuación, seleccione la opción Web.
- Para URI de redireccionamiento, escriba
http://localhost:3000/auth/redirect
. - Selecciona Configurar para guardar los cambios.
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 web
Para conceder permisos de API a su aplicación cliente (ciam-client-app), siga estos pasos:
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 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 delegados.
En la lista de permisos, seleccione ToDoList.Read, ToDoList.ReadWrite (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 se trata de un inquilino del cliente, los propios usuarios consumidores 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:
Seleccione Conceder consentimiento del administrador para <nombre del inquilino> y seleccione Sí.
Seleccione Actualizar y compruebe que aparece Concedido para <nombre del inquilino> en Estado para ambos ámbitos.
En la lista Permisos configurados, seleccione los permisos ToDoList.Read y ToDoList.ReadWrite, de uno en uno y, a continuación, copie el URI completo del permiso para su uso posterior. El URI de permiso completo tiene un aspecto similar a
api://{clientId}/{ToDoList.Read}
oapi://{clientId}/{ToDoList.ReadWrite}
.
Creación de un flujo de usuario
Siga estos pasos para crear un flujo de usuario que un cliente pueda usar para iniciar sesión o registrarse en una aplicación.
Inicie sesión en el centro de administración de Microsoft Entra como mínimo un administrador de flujo de usuario de identificador externo.
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 a Identidad> Identidades externas> Flujos de usuarios.
Seleccione + Nuevo flujo de usuario.
En la página Crear:
Escriba un nombre para el flujo de usuario, como SignInSignUpSample.
En la lista Proveedores de identidades, seleccione Cuentas de correo electrónico. Este proveedor de identidades permite a los usuarios iniciar sesión o registrarse con su dirección de correo electrónico.
En Cuentas de correo electrónico, puede seleccionar una de las dos opciones. En este tutorial, seleccione Correo electrónico con contraseña.
- Correo electrónico con contraseña: permite a los nuevos usuarios registrarse e iniciar sesión con una dirección de correo electrónico como nombre de inicio de sesión y una contraseña como credencial del primer factor.
- Código de acceso de un solo uso de correo electrónico: permite a los nuevos usuarios registrarse e iniciar sesión con una dirección de correo electrónico como el nombre de inicio de sesión y el código de acceso de un solo uso como credencial del primer factor. El código de acceso de un solo uso de correo electrónico debe estar habilitado en el nivel de inquilino (Todos los proveedores de identidades>Código de acceso de un solo uso de correo electrónico) para que esta opción esté disponible en el nivel de flujo de usuario.
En Atributos de usuario, elija los atributos que quiere recopilar del usuario tras registrarse. Al seleccionar Mostrar más, puede elegir los atributos y las notificaciones de País o región, Nombre para mostrar y Código postal. Seleccione Aceptar. (A los usuarios solo se les solicitan atributos cuando se registran por primera vez).
Seleccione Crear. El nuevo flujo de usuario aparece en la lista Flujos de usuario. Si es necesario, actualice la página.
Para habilitar el autoservicio de restablecimiento de contraseña, siga los pasos descritos en el artículo Habilitar el autoservicio de restablecimiento de contraseña.
Asociación de una aplicación web al flujo de usuarios
Aunque muchas aplicaciones se pueden asociar a su flujo de usuario, una sola aplicación solo se puede asociar a un flujo de usuario. Un flujo de usuario permite la configuración de la experiencia del usuario para aplicaciones específicas. Por ejemplo, puede configurar un flujo de usuario que requiera que los usuarios inicien sesión o se registren con la dirección de correo electrónico.
En el menú de la barra lateral, seleccione Identidad.
Seleccione External Identities y, a continuación, Flujos de usuario.
En la página Flujos de usuario, seleccione el nombre del flujo de usuario que creó anteriormente; por ejemplo, SignInSignUpSample.
En Usar, seleccione Aplicaciones.
Seleccione Agregar una aplicación.
Seleccione la aplicación de la lista, como ciam-client-app, o use el cuadro de búsqueda para buscar la aplicación y selecciónela.
Elija Seleccionar.
Clonar o descargar una aplicación web 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/Express de ejemplo:
cd 2-Authorization\4-call-api-express\App
Ejecute los siguientes comandos para instalar las dependencias de la aplicación web:
npm install && npm update
Configuración de la aplicación web y la 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 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 escontoso.onmicrosoft.com
, usecontoso
. Si no tiene el nombre del inquilino, aprenda a leer los detalles del inquilino.Enter_the_Client_Secret_Here
y reemplácelo con el valor secreto de aplicación que copió anteriormente.Enter_the_Web_Api_Application_Id_Here
y reemplácelo con 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 escontoso.onmicrosoft.com
, usecontoso
. Si no tiene el nombre del inquilino, aprenda a leer los detalles del inquilino.
Ejecute y pruebe la aplicación web y la API de ejemplo
Abra una ventana de consola y ejecute la API web mediante los siguientes comandos:
cd 2-Authorization\4-call-api-express\API\ToDoListAPI dotnet run
Ejecute el cliente de la aplicación web mediante los siguientes comandos:
cd 2-Authorization\4-call-api-express\App npm start
Abra el explorador web y vaya a http://localhost:3000.
Haga clic en el botón Iniciar sesión. Se le pedirá que inicie sesión.
En la página de inicio de sesión, escriba su dirección de correo electrónico, seleccione Siguiente, escriba la contraseña y, a continuación, seleccione Iniciar sesión. Si no tiene una cuenta, seleccione el vínculo ¿No tiene una cuenta? Cree una, que inicia el flujo de registro.
Si elige la opción de registro, después de rellenar el correo electrónico, el código de acceso de un solo uso, la nueva contraseña y más detalles de la cuenta, completará todo el flujo de registro. Verá una página similar a la que aparece en la siguiente captura de pantalla. Verá una página similar si elige la opción de inicio de sesión.
Llamada a la API
Para llamar a la API, seleccione el vínculo Ver la lista de tareas pendientes. Verá una página similar a la que aparece en la siguiente captura de pantalla.
Manipule la lista de tareas pendientes mediante la creación y eliminación de elementos.
Funcionamiento
Puede desencadenar una llamada API cada vez que vea, agregue o quite una tarea. Cada vez que se desencadena una llamada API, la aplicación web cliente adquiere un token de acceso con los permisos necesarios (ámbitos) para llamar a un punto de conexión de API. Por ejemplo, para leer una tarea, la aplicación web cliente debe adquirir un token de acceso con ToDoList.Read
permiso o ámbito.
El punto de conexión de API web debe comprobar si los permisos o ámbitos del token de acceso, proporcionados por la aplicación cliente, son válidos. Si el token de acceso es válido, el punto de conexión responde a la solicitud HTTP; de lo contrario, responde con un error HTTP 401 Unauthorized
.
Contenido relacionado
Comentarios
https://aka.ms/ContentUserFeedback.
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea:Enviar y ver comentarios de