Skip to main content
La biblioteca de Auth0.js es una biblioteca de JavaScript del lado del cliente para Auth0. Admite tanto el inicio de sesión alojado como el inicio de sesión integrado. Este artículo cubre v10, la versión actual. Revisa la documentación completa de la API de la biblioteca.

​
Migra de v9 a v10

Auth0.js v10 contiene una corrección de seguridad para CVE-2026-42280 y un cambio incompatible: Si necesitas la referencia de la API de v9, consulta el paquete auth0-js en npm y selecciona tu versión v9, o revisa el código fuente y el registro de cambios de v9 en GitHub.
El inicio de sesión integrado para aplicaciones web utiliza autenticación entre orígenes, a menos que configures un dominio personalizado para tu tenant. La autenticación entre orígenes utiliza cookies de terceros para permitir transacciones de autenticación seguras entre distintos orígenes.

​
Ejemplo listo para usar

El directorio de ejemplo de la biblioteca de Auth0.js es una aplicación lista para usar que puede ayudarte a probar Auth0.js de forma rápida y sencilla. Para ejecutarla:
  1. Si no tienes node instalado, instálalo ahora
  2. Descarga las dependencias ejecutando npm install desde la raíz de este proyecto
  3. Por último, ejecuta npm start desde la raíz de este proyecto y luego abre en el navegador la aplicación que se está ejecutando en el servidor de Node, probablemente en http://localhost:3000/example.

​
Configuración e inicialización

Las siguientes secciones cubren los métodos de instalación, cómo inicializar Auth0.js, registro, inicio de sesión, cierre de sesión y mucho más.

​
Configura tu aplicación de Auth0 para el inicio de sesión integrado

Al implementar el inicio de sesión integrado, la biblioteca usa solicitudes entre orígenes dentro de iframes ocultos para realizar la autenticación. Para garantizar que esto pueda hacerse de forma segura, Auth0 necesita conocer los dominios donde alojas tus aplicaciones. Agrega el dominio al campo Allowed Web Origins. Puedes encontrar este campo en la sección de Application Settings de tu Dashboard.

​
Opciones de instalación

Tienes varias opciones para usar Auth0.js en tu proyecto. Elige una de las siguientes según tus necesidades: Instálalo mediante npm o yarn:
Después de instalar el módulo auth0-js, inclúyelo en el paquete junto con todas sus dependencias o impórtalo con:
Como alternativa, incluye el script desde el CDN:

​
Inicialización

Inicializa una instancia nueva de la aplicación Auth0 de la siguiente manera:

​
Parámetros disponibles

Hay dos parámetros obligatorios que deben pasarse en el objeto options al instanciar webAuth, y varios más que son opcionales. Debido a problemas de desincronización del reloj, es posible que ocasionalmente te encuentres con el error The token was issued in the future. El parámetro leeway puede usarse para permitir unos segundos de margen en los tiempos de expiración del ID Token y evitar que esto ocurra.
Scope
El valor predeterminado de scope en Auth0.js v10 es openid profile email.
Ejecutar Auth0.js de forma localSi no especificas al menos el scope indicado arriba al inicializar Auth0.js y ejecutas tu sitio web desde http://localhost o http://127.0.0.1, al llamar al método getSSOData() se mostrará el siguiente error en la consola del navegador:Consent required. When using getSSOData, the user has to be authenticated with the following scope: openid profile emailEsto no ocurrirá cuando ejecutes tu aplicación en producción o si especificas el scope openid profile email. Puedes obtener más información en el documento Consentimiento del usuario y aplicaciones de terceros.

​
Inicio de sesión

Puedes elegir un método de inicio de sesión en función del tipo de autenticación que necesites en tu aplicación.

​
webAuth.authorize()

El método authorize() puede usarse para iniciar sesión mediante o conexiones sociales, como se muestra en los ejemplos a continuación. Este método invoca el endpoint /authorize de la Authentication API y puede recibir distintos parámetros a través del objeto options. Para el inicio de sesión alojado, se debe llamar al método /authorize(). webAuth.authorize({//Cualquier opción adicional puede ir aquí}); Para los inicios de sesión sociales, será necesario especificar el parámetro connection: webAuth.authorize({connection: 'twitter'});

​
webAuth.popup.authorize()

Para la autenticación mediante ventana emergente se puede usar el método popup.authorize. La autenticación mediante ventana emergente no puede utilizarse en páginas de inicio de sesión alojadas. Normalmente, este tipo de autenticación se usa en aplicaciones de una sola página para no perder el estado actual al hacer una redirección de página completa. Autorización predeterminada mediante ventana emergente (Universal Login):
Y para iniciar sesión con redes sociales mediante una ventana emergente usando authorize:

​
Gestiona los resultados de autenticación con ventana emergente

Al usar la autenticación con ventana emergente, tendrás que proporcionar un redirectUri en el que la página de destino comunique los resultados de la autorización al callback mediante el método webAuth.popup.callback. Una implementación sencilla sería algo así:
Un manejador ideal contendría solo esta funcionalidad mínima (es decir, que evite recargar toda la aplicación solo para procesar la respuesta). Tendrás que añadir el redirectUri a la lista de Allowed Callback URLs en la página de configuración de la aplicación del Dashboard.

​
webAuth.login()

El inicio de sesión integrado para aplicaciones web usa la autenticación entre orígenes, a menos que configure un dominio personalizado para su tenant. La autenticación entre orígenes utiliza cookies de terceros para permitir transacciones de autenticación seguras entre distintos orígenes.
El método login puede utilizarse para el inicio de sesión integrado mediante autenticación entre orígenes en conexiones de base de datos, usando /co/authenticate.

​
webAuth.crossOriginVerification()

El método crossOriginVerification() puede utilizarse para facilitar la autenticación entre orígenes a los clientes que tienen deshabilitadas las cookies de terceros en sus navegadores. Para obtener más información sobre su uso, consulta Autenticación entre orígenes.

​
buildAuthorizeUrl(options)

El método buildAuthorizeUrl puede usarse para construir la URL /authorize a fin de iniciar una nueva transacción. Usa este método si quieres implementar autenticación basada en el navegador (pasiva). El parámetro state es un valor opaco que Auth0 te devolverá. Este método ayuda a prevenir ataques CSRF y debe especificarse si rediriges a la URL tú mismo en lugar de llamar a webAuth.authorize(). Para obtener más información, consulta State Parameter.

​
Inicio de sesión único con autenticación integrada

El inicio de sesión integrado admite (SSO) cuando sus aplicaciones comparten la siguiente arquitectura:
  1. Las aplicaciones que intentan usar SSO son aplicaciones de primera parte. No se admite compartir sesiones integradas con aplicaciones de terceros.
  2. Las aplicaciones y su tenant de Auth0 comparten un dominio de nivel superior mediante un dominio personalizado. Los dominios tradicionales de Auth0 usan el formato foo.auth0.com; los dominios personalizados permiten que sus aplicaciones y su tenant de Auth0 compartan el mismo dominio de nivel superior, lo que también ayuda a prevenir ataques CSRF.
Cuando su arquitectura cumple estos criterios, el SSO integrado con Auth0.js es una buena opción. Universal Login gestiona automáticamente el SSO en varios dominios o con aplicaciones de terceros mediante su capa de sesión, y ambos pueden coexistir en la misma aplicación; por ejemplo, Universal Login para el inicio de sesión principal y Auth0.js para la inscripción integrada de factores o los flujos step-up. Para comparar las ventajas y desventajas, consulte Inicio de sesión alojado vs. inicio de sesión integrado.

​
Inicio de sesión sin contraseña

La autenticación permite a los usuarios iniciar sesión recibiendo un código de un solo uso por correo electrónico o mensaje de texto. El proceso requiere que inicies el flujo sin contraseña, generando y enviando un código al usuario (o un código dentro de un enlace) y, a continuación, validando sus credenciales mediante el método de verificación. Esto puede presentarse en forma de una pantalla de inicio de sesión que solicite su correo electrónico o número de teléfono y el código que acabas de enviarle. También puede implementarse como un enlace sin contraseña en lugar de un código enviado al usuario. Bastaría con que hicieran clic en el enlace de su correo electrónico o mensaje de texto para que este llame a tu endpoint y verifique estos datos automáticamente usando el mismo método de verificación (solo que sin que el usuario tenga que introducir manualmente un código). Para usar la autenticación sin contraseña, inicializa Auth0.js con un redirectUri y establece responseType: 'token'.

​
Iniciar la autenticación sin contraseña

El primer paso para la autenticación sin contraseña con Auth0.js es el método passwordlessStart, que admite varios parámetros dentro de su objeto options: Ten en cuenta que, para iniciar el proceso de autenticación sin contraseña, debes enviar exactamente uno de los parámetros opcionales phoneNumber y email.

​
Completar la autenticación sin contraseña

Si envías un código, tendrás que pedirle al usuario que lo introduzca. Procesarás el código y autenticarás al usuario con el método passwordlessLogin, que tiene varios parámetros que pueden enviarse en su objeto options: Al igual que con passwordlessStart, debe enviarse exactamente uno de los parámetros opcionales phoneNumber o email para verificar la transacción sin contraseña. Para usar passwordlessLogin, especifica redirectUri y responseType al inicializar WebAuth.

​
Extrae el authResult y obtén información del usuario

Una vez completada la autenticación, puedes usar el método parseHash para analizar el fragmento hash de una URL cuando se redirige al usuario de vuelta a tu aplicación y extraer así el resultado de una respuesta de autenticación de Auth0. Puedes hacerlo en una página de callback que luego redirija a tu aplicación principal o directamente en la propia página, según convenga en cada caso. El método parseHash recibe un objeto options que contiene los siguientes parámetros: El contenido del objeto authResult que devuelve parseHash depende de los parámetros de autenticación que se hayan utilizado. Puede incluir:
Como se muestra arriba, se puede llamar al método client.userInfo pasando el accessToken devuelto. Este hará una solicitud al endpoint /userinfo y devolverá el objeto user, que contiene la información del usuario, con un formato similar al del ejemplo siguiente.
Ahora puede hacer otras cosas con esta información según las necesidades de su aplicación, como obtener toda la información del perfil del usuario con la , como se describe a continuación.

​
Uso de nonce

De forma predeterminada (y si responseType contiene id_token), Auth0.js generará un nonce aleatorio cuando llames a webAuth.authorize, lo almacenará en el almacenamiento local y lo recuperará en webAuth.parseHash. El comportamiento predeterminado debería funcionar en la mayoría de los casos, pero en algunos escenarios puede ser necesario que el desarrollador controle el nonce. Si quieres usar un nonce generado por el desarrollador, debes proporcionarlo como una opción tanto en webAuth.authorize como en webAuth.parseHash. webAuth.authorize({<Tooltip tip="Nonce: Arbitrary number issued once in an authentication protocol to detect and prevent replay attacks." cta="View Glossary" href="/docs/glossary?term=nonce">nonce</Tooltip>: '1234', responseType: 'token id_token'}); webAuth.parseHash({nonce: '1234'}, callback); Si llamas a webAuth.checkSession en lugar de webAuth.authorize, solo tienes que especificar tu nonce personalizado como una opción en checkSession:
El método webAuth.checkSession verificará automáticamente que la claim nonce del ’ devuelto sea la misma que la opción.

​
Códigos de error y descripciones

Cuando Auth0.js se usa para el inicio de sesión integrado, utiliza el endpoint /co/authenticate, que puede generar los siguientes errores:
Las descripciones de los errores están pensadas para que las personas puedan entenderlas. La descripción no debe ser analizada por ningún código y puede cambiar en cualquier momento.
Además, también puedes recibir un error 403 genérico sin una propiedad error ni error_description. El cuerpo de la respuesta simplemente incluiría algo similar a lo siguiente: Origin https://test.app is not allowed.

​
Cerrar sesión

Para cerrar la sesión de un usuario, usa el método logout(). Este método acepta un objeto de opciones que puede incluir los siguientes parámetros. Si se incluye el parámetro clientID, la URL returnTo proporcionada debe figurar en las Allowed Logout URLs de la aplicación en el Dashboard de Auth0. Sin embargo, si no se incluye el parámetro clientID, la URL returnTo debe figurar en las Allowed Logout URLs configuradas a nivel de cuenta en el Dashboard de Auth0.

​
Registro

Para registrar un usuario, usa el método signup. Este método acepta un objeto de opciones que puede incluir los siguientes parámetros. Los registros deben realizarse en conexiones de base de datos. Aquí tienes un ejemplo del método signup y código de ejemplo para un formulario.

​
Uso de checkSession para obtener nuevos tokens

El método checkSession te permite obtener un nuevo token de Auth0 para un usuario que ya está autenticado con Auth0 en tu dominio. El método acepta cualquier parámetro válido de OAuth2 que normalmente se enviaría a authorize. Si los omites, usará los que se proporcionaron al inicializar Auth0. La llamada a checkSession puede usarse para obtener un nuevo token para la API que se especificó como la al inicializar webAuth:
Consulta Extraer el AuthResult y obtener la información del usuario para conocer el formato de authResult. O bien, se puede obtener el token para una API distinta de la usada al inicializar webAuth especificando un audience y un scope:
Ten en cuenta que checkSession() activa cualquier regla que hayas configurado, por lo que deberías revisar tus reglas en el Dashboard antes de usarla. La redirección real a /authorize se produce dentro de un iframe, por lo que no recargará tu aplicación ni te redirigirá fuera de ella. Sin embargo, el navegador debe tener habilitadas las cookies de terceros. De lo contrario, checkSession() no podrá acceder a la sesión actual del usuario (lo que hace imposible obtener un nuevo token sin mostrar nada al usuario). Lo mismo ocurrirá si los usuarios tienen la ITP de Safari habilitada. Recuerda añadir la URL desde la que se origina la solicitud de autorización a la lista de Allowed Web Origins de tu aplicación de Auth0 en el Dashboard, dentro de Settings de tu aplicación.
Si se trata de una conexión social y estás usando claves de desarrollo de Auth0, la llamada a checkSession siempre devolverá login_required.

​
Sondeo con checkSession()

En algunos escenarios con varias aplicaciones, en los que se desea Single Logout (cuando un usuario cierra sesión en una aplicación, también debe cerrarse en las demás), una aplicación puede configurarse para consultar periódicamente a Auth0 mediante checkSession() y comprobar si existe una sesión. Si la sesión no existe, puedes cerrar la sesión del usuario en la aplicación. El mismo método de sondeo puede utilizarse para implementar autenticación silenciosa en un escenario de inicio de sesión único (SSO). El intervalo de sondeo entre comprobaciones con checkSession() debe ser de al menos 15 minutos entre llamadas para evitar posibles problemas futuros con la limitación de tasa de esta llamada.

​
Solicitudes de restablecimiento de contraseña

Si quieres configurar la funcionalidad de restablecimiento de contraseña, usarás el método changePassword y pasarás un objeto options con un parámetro connection y otro email.
El usuario recibe un correo electrónico con un enlace para restablecer su contraseña.

​
Gestión de usuarios

La Management API ofrece funciones que te permiten vincular y desvincular cuentas de usuario independientes de distintos proveedores, así como actualizar los metadatos del usuario. Para obtener más información, consulta Vinculación de cuentas de usuario. Para empezar, primero debes obtener un que pueda utilizarse para llamar a la Management API. Puedes hacerlo especificando la audiencia https://{yourDomain}/api/v2/ al inicializar Auth0.js; en ese caso, obtendrás el token de acceso como parte del flujo de autenticación. Si usas dominios personalizados, tendrás que crear una nueva instancia de webAuth con tu dominio de Auth0 en lugar del dominio personalizado para usarla en las llamadas a la Management API, ya que esta solo funciona con dominios de Auth0. También puedes hacerlo con checkSession(): Debes especificar los permisos concretos que necesitas. Puedes solicitar los siguientes permisos:
  • read:current_user
  • update:current_user_identities
  • create:current_user_metadata
  • update:current_user_metadata
  • delete:current_user_metadata
  • create:current_user_device_credentials
  • delete:current_user_device_credentials
Una vez que tengas el token de acceso, puedes crear una nueva instancia de auth0.Management pasándole el dominio de Auth0 de la cuenta y el token de acceso.

​
Obtener el perfil del usuario

Para obtener los datos del perfil del usuario, utiliza el método getUser() con userId y un callback como parámetros. El método devuelve el perfil del usuario. Ten en cuenta que el userID requerido aquí será el mismo que se obtuvo mediante el método client.userInfo. auth0Manage.getUser(userId, cb);

​
Actualizar el perfil de usuario

Al actualizar los metadatos del usuario, primero deberá crear un objeto userMetadata y luego llamar al método patchUserMetadata, pasándole el ID del usuario y el objeto userMetadata que haya creado. Los valores de este objeto sobrescribirán los valores existentes que tengan la misma clave o agregarán otros nuevos para las claves que aún no existan en los metadatos del usuario. Para obtener más información, consulte Metadata. auth0Manage.patchUserMetadata(userId, userMetadata, cb); Vincular cuentas de usuario permitirá que una persona pueda autenticarse con cualquiera de sus cuentas y, sin importar cuál use, siga accediendo al mismo perfil al iniciar sesión. Auth0 trata todas estas cuentas como perfiles independientes de forma predeterminada, así que, si quieres que las cuentas de un usuario estén vinculadas, esta es la forma de hacerlo. El método linkUser acepta dos parámetros: el userId principal y el ID Token del usuario secundario (el token obtenido después de iniciar sesión con esta identidad). El ID de usuario en cuestión es el identificador único de la cuenta de usuario principal. El ID debe pasarse con el prefijo del proveedor, por ejemplo, auth0|1234567890 o facebook|1234567890, al usar este método. Consulta User Account Linking para obtener más información. auth0Manage.linkUser(userId, secondaryUserToken, cb); Después de vincular las cuentas, la segunda cuenta dejará de existir como una entrada independiente en la base de datos de usuarios y solo se podrá acceder a ella como parte de la cuenta principal. Cuando las cuentas están vinculadas, los metadatos de la cuenta secundaria no se fusionan con los de la cuenta principal y, si en algún momento se desvinculan, la cuenta secundaria tampoco conservará los metadatos de la cuenta principal cuando vuelva a quedar separada.