SDK de Auth0 para aplicaciones de una sola página: flujo de código de autorización con PKCE.

SDK de Auth0 para aplicaciones de una sola página que usan el flujo de código de autorización con PKCE.

El SDK de Auth0 para aplicaciones de página única es una nueva biblioteca de JavaScript para implementar autenticación y autorización en aplicaciones de página única (SPA) con Auth0. Proporciona una API de alto nivel y se encarga de muchos de los detalles para que puedas proteger las SPA siguiendo prácticas recomendadas y escribiendo menos código.

El SDK de Auth0 para SPA gestiona los detalles de concesión y del protocolo, la caducidad y renovación de los tokens, así como su almacenamiento y almacenamiento en caché. Internamente, implementa Universal Login y el flujo de código de autorización con PKCE.

La biblioteca y la documentación de la API están alojadas en GitHub.

Si encuentras algún problema o error al usar el nuevo SDK de JavaScript, consulta las preguntas frecuentes para ver si tu problema se trata allí.

Instalación

Tiene varias opciones para usar el SDK de SPA de Auth0 en su proyecto:

• Desde el CDN: <script src="https://cdn.auth0.com/js/auth0-spa-js/2.0/auth0-spa-js.production.js"></script>. Para obtener más información, consulte las preguntas frecuentes.
• Con npm: npm install @auth0/auth0-spa-js
• Con yarn: yarn add @auth0/auth0-spa-js

Primeros pasos

Crear el cliente

Primero, debes crear una nueva instancia del objeto cliente Auth0Client. Crea la instancia de Auth0Client antes de renderizar o inicializar la aplicación. Puedes hacerlo con el método async/await o con promesas. Solo debes crear una instancia del cliente.

Al usar createAuth0Client, se hacen automáticamente un par de cosas:

• Se crea una instancia de Auth0Client.
• Se llama a getTokenSilently para actualizar la sesión del usuario.
• Se suprimen todos los errores de getTokenSilently, excepto login_required.

Usa async/await

Usar promesas

También puede crear el cliente directamente con el constructor Auth0Client. Esto puede resultar útil si desea:

• Omitir la llamada a getTokenSilently durante la inicialización.
• Implementar un manejo de errores personalizado.
• Inicializar el SDK de forma síncrona.

Inicie sesión y obtenga información del usuario

A continuación, cree un botón en el que los usuarios puedan hacer clic para iniciar sesión:

<button id="login">Click to Login</button>

Escuche los eventos de clic del botón que creó. Cuando se produzca el evento, use el método de inicio de sesión deseado para autenticar al usuario (loginWithRedirect() en este ejemplo). Después de que el usuario se haya autenticado, puede recuperar su perfil con el método getUser().

Usa async/await

document.getElementById('login').addEventListener('click', async () => {
  await auth0.loginWithRedirect({
    authorizationParams: {
      redirect_uri: 'http://localhost:3000/'
    }
  });
  //sesión iniciada. puedes obtener el perfil del usuario así:
  const user = await auth0.getUser();
  console.log(user);
});

Usar promesas

document.getElementById('login').addEventListener('click', () => {
  auth0.loginWithRedirect({
    authorizationParams: {
      redirect_uri: 'http://localhost:3000/'
    }
  }).then(token => {
    //sesión iniciada. puedes obtener el perfil del usuario así:
    auth0.getUser().then(user => {
      console.log(user);
    });
  });
});

Llamar a una API

Para llamar a tu API, empieza por obtener el Token de acceso del usuario. Luego, usa el Token de acceso en tu solicitud. En este ejemplo, se utiliza el método getTokenSilently para recuperar el Token de acceso:

<button id="callApi">Llamar a una API</button>

Usa async/await

document.getElementById('callApi').addEventListener('click', async () => {
  const accessToken = await auth0.getTokenSilently();
  const result = await fetch('https://exampleco.com/api', {
    method: 'GET',
    headers: {
      Authorization: 'Bearer ' + accessToken
    }
  });
  const data = await result.json();
  console.log(data);
});

Uso de promesas

document.getElementById('callApi').addEventListener('click', () => {
  auth0
    .getTokenSilently()
    .then(accessToken =>
      fetch('https://exampleco.com/api', {
        method: 'GET',
        headers: {
          Authorization: 'Bearer ' + accessToken
        }
      })
    )
    .then(result => result.json())
    .then(data => {
      console.log(data);
    });
});

Cerrar sesión

Agrega un botón para que los usuarios puedan cerrar sesión:

<button id="logout">Logout</button>

$('#logout').click(async () => {
  auth0.logout({
    logoutParams: {
      returnTo: 'http://localhost:3000/'
    }
  });
});

Cambiar las opciones de almacenamiento

De forma predeterminada, SDK de SPA de Auth0 almacena los tokens en memoria. Sin embargo, esto no ofrece persistencia entre recargas de página y entre pestañas del navegador. En su lugar, puede optar por almacenar los tokens en el almacenamiento local configurando la propiedad cacheLocation como localstorage al inicializar el SDK. Esto puede ayudar a mitigar algunos de los efectos de las tecnologías de privacidad del navegador que impiden el acceso a la cookie de sesión de Auth0 cookie de sesión al almacenar Tokens de acceso durante más tiempo.

Almacenar tokens en el almacenamiento local del navegador ofrece persistencia entre recargas de página y entre pestañas del navegador. Sin embargo, si un atacante logra ejecutar JavaScript en la SPA mediante un ataque de secuencias de comandos entre sitios (XSS), puede recuperar los tokens almacenados en el almacenamiento local. Una vulnerabilidad que permita un ataque XSS exitoso puede estar tanto en el código fuente de la SPA como en cualquier código JavaScript de terceros (como Bootstrap, jQuery o Google Analytics) incluido en la SPA.

Obtenga más información sobre el almacenamiento de tokens.

Usar Tokens de actualización rotativos

El SDK de SPA de Auth0 puede configurarse para usar Tokens de actualización rotativos para obtener nuevos tokens de acceso de forma silenciosa. Estos pueden usarse para sortear las tecnologías de privacidad del navegador que impiden acceder a la cookie de sesión de Auth0 al autenticar de forma silenciosa, además de ofrecer detección de reutilización integrada.

Configure el SDK para ello estableciendo useRefreshTokens en true durante la inicialización:

Tokens de actualización también deberán configurarse para tu inquilino antes de poder usarse en tu SPA.

Una vez configurado, el SDK solicitará el scope offline_access durante el proceso de autorización. Además, getTokenSilently llamará directamente al endpoint /oauth/token para intercambiar tokens de actualización por tokens de acceso. El SDK respetará la configuración de almacenamiento al guardar los tokens de actualización. Si el SDK se configuró con el mecanismo predeterminado de almacenamiento en memoria, los tokens de actualización se perderán al recargar la página.

Uso

A continuación se muestran ejemplos de uso de varios métodos del SDK. Tenga en cuenta que en estos ejemplos se usa jQuery.

Inicio de sesión con redirección

Redirige al endpoint /authorize de Auth0 para iniciar el flujo de Universal Login:

$('#loginRedirect').click(async () => {
  await auth0.loginWithRedirect({
    authorizationParams: {
      redirect_uri: 'http://localhost:3000/'
    }
  });
});

Inicio de sesión con ventana emergente

Usa una ventana emergente para iniciar sesión mediante la página de Universal Login:

$('#loginPopup').click(async () => {
  await auth0.loginWithPopup();
});

Si el usuario tarda más del tiempo de espera predeterminado de 60 segundos en completar el flujo de autenticación, la autenticación se interrumpirá y deberá capturar el error en su código para hacer una de estas dos cosas:

Sugerir que el usuario vuelva a intentarlo y cerrar manualmente la ventana emergente con error.popup.close:

$('#loginPopup').click(async () => {
  try {
    await auth0.loginWithPopup();
  } catch {error}
  if (error instanceof auth0.PopupTimeoutError) {
    // lógica personalizada para informar al usuario que reintente
    error.popup.close();
  }
});

O bien, cree una opción popup personalizada en el objeto options:

$('#loginPopup').click(async () => {
  const popup = window.open(
    '',
    'auth0:authorize:popup',
    'left=100,top=100,width=400,height=600,resizable'
  );
  try {
    await auth0.loginWithPopup({ popup });
  } catch {error}
  if (error instanceof auth0.PopupTimeoutError) {
    // lógica personalizada para informar al usuario que reintente
    error.popup.close();
  }
});

Callback de redirección de inicio de sesión

Cuando el navegador sea redirigido desde Auth0 de vuelta a tu SPA, debes llamar a handleRedirectCallback para completar el flujo de inicio de sesión:

$('#loginRedirectCallback').click(async () => {
  await auth0.handleRedirectCallback();
});

Obtener un Token de acceso sin interacción

Obtenga un nuevo Token de acceso de forma silenciosa mediante un iframe oculto y prompt=none, o usando un Token de actualización rotativo. Los Tokens de actualización se usan cuando useRefreshTokens se establece en true al configurar el SDK.

Obtener un Token de acceso de forma silenciosa sin usar Tokens de actualización no funcionará en navegadores que bloquean las cookies de terceros, como Safari y Brave. Para obtener más información sobre la solución alternativa del dominio personalizado, consulte Solucionar problemas al renovar tokens cuando se usa Safari.

Si se usan el almacenamiento en memoria (el valor predeterminado) y los tokens de actualización, los nuevos tokens se obtienen mediante un web worker en los navegadores compatibles:

$('#getToken').click(async () => {
  const token = await auth0.getTokenSilently();
});

El método getTokenSilently() requiere que tengas habilitada la opción Allow Skipping User Consent en la configuración de la API del Dashboard. Además, el consentimiento del usuario no se puede omitir en ‘localhost’.

Obtener un Token de acceso con una ventana emergente

Los Tokens de acceso también se pueden obtener mediante una ventana emergente. A diferencia de getTokenSilently, este método para obtener un Token de acceso funciona en navegadores en los que las cookies de terceros están bloqueadas de forma predeterminada:

$('#getTokenPopup').click(async () => {
  const token = await auth0.getTokenWithPopup({
    authorizationParams: {
      audience: 'https://mydomain/api/',
      scope: 'read:rules'
    }
  });
});

Obtener un Token de acceso para una audiencia distinta

Puedes pasar opciones a getTokenSilently para obtener un Token de acceso con una audiencia y un scope distintos de los solicitados en el momento de la autenticación del usuario.

Esto solo funciona cuando no se usan Tokens de actualización (useRefreshTokens: false), ya que un Token de actualización está vinculado a la audiencia y al scope específicos que se solicitaron en el momento de la autenticación del usuario.

$('#getToken_audience').click(async () => {
  const differentAudienceOptions = {
    authorizationParams: {
      audience: 'https://mydomain/another-api/',
      scope: 'read:rules',
      redirect_uri: 'http://localhost:3000/callback.html'
    }
  };
  const token = await auth0.getTokenSilently(differentAudienceOptions);
});

Obtener el usuario

Puede obtener los datos del perfil del usuario autenticado mediante una llamada al método getUser:

$('#getUser').click(async () => {
  const user = await auth0.getUser();
});

Obtener los claims del ID Token

Puedes obtener los claims del ID Token del usuario autenticado mediante el método getIdTokenClaims:

$('#getIdTokenClaims').click(async () => {
  const claims = await auth0.getIdTokenClaims();
  // si necesitas el id_token sin procesar, puedes acceder a él
  // usando la propiedad __raw
  const id_token = claims.__raw;
});

Cerrar sesión (predeterminado)

Puede iniciar el cierre de sesión llamando al método logout:

$('#logout').click(async () => {
  auth0.logout({
    logoutParams: {
      returnTo: 'http://localhost:3000/'
    }
  });
});

Cerrar sesión sin ID de cliente

Puede iniciar el cierre de sesión sin especificar un ID de cliente llamando al método logout e incluyendo clientId: null:

$('#logoutNoClientId').click(async () => {
  auth0.logout({
    clientId: null,
    logoutParams: {
      returnTo: 'http://localhost:3000/'
    }
  });
});

Más información

• Validar tokens de acceso