Migración al nuevo cliente de autenticación

En la versión 8.13.0, introdujimos un nuevo cliente de autenticación. Este nuevo cliente ofrece la posibilidad de elegir entre un cliente de autenticación genérico que no está vinculado a ningún proveedor de identidades (IdP) específico, o un cliente basado en Okta. Estos nuevos clientes de autenticación no son retrocompatibles con el cliente de autenticación heredado. Si utiliza el cliente de autenticación heredado, deberá migrar al nuevo cliente de autenticación.

Configuración

Las variables de entorno deben verse así:

Enable Jutro authorization client usage: REACT_APP_JUTRO_AUTH_ENABLED=true
Select the client to use:
- Okta client: JUTRO_AUTH_USE_NATIVE_OKTA_CLIENT=true
- Generic OIDC client: JUTRO_AUTH_USE_NATIVE_OKTA_CLIENT=false
Add IDP configuration variables:
- REACT_APP_JUTRO_AUTH_ISSUER=https://{your-provider}.com/oauth2/{key}
- REACT_APP_JUTRO_AUTH_CLIENT_ID={your client ID goes here}
- REACT_APP_JUTRO_AUTH_REDIRECT_PATH=/auth/callback
- REACT_APP_JUTRO_AUTH_SCOPE=openid,tenant_id,email,profile,offline_access
- JUTRO_AUTH_USE_PASSIVE_TOKEN_RENEWALS=true
- JUTRO_AUTH_PREPEND_AUTH_CALLBACKS_WITH_BASEURL=true
The native Okta client handles silent logins, but if you are using the Generic OIDC client and you are using this feature you will need to add two additional configuration variables:
- REACT_APP_JUTRO_AUTH_SILENT_REDIRECT_PATH=/auth/silent/callback
- REACT_APP_JUTRO_AUTH_SILENT_LOGIN_PATH=/auth/silent/login

Para obtener más información sobre los inicios de sesión silenciosos, consulte la documentación sobre inicio de sesión silencioso.

Para obtener más información sobre cómo configurar el nuevo cliente de autenticación, consulte nuestros documentos sobre el cliente de autenticación.

Variables de entorno no admitidas

Las siguientes variables de entorno del cliente de autenticación heredado no son compatibles con el nuevo cliente de autenticación:

REACT_APP_JUTRO_AUTH_PKCE_ENABLED. PKCE siempre está habilitado en el nuevo cliente de autenticación.
REACT_APP_JUTRO_AUTH_IDP. Esta variable se relaciona directamente con Okta y no está incluida en el nuevo cliente de autenticación, que es genérico, no específico de IdP. Sin embargo, aún puede utilizar parámetros de consulta personalizados al iniciar y cerrar sesión. Consulte la documentación de inicio y cierre de sesión para obtener más información.
REACT_APP_JUTRO_AUTH_AUTO_RENEW. La renovación automática está habilitada de forma predeterminada en el nuevo cliente de autenticación.
REACT_APP_JUTRO_AUTH_STORAGE. Establece el tipo de mecanismo de almacenamiento que utiliza el sistema de autenticación de Jutro.

Además, se ha eliminado la variable REACT_APP_JUTRO_AUTH_GENERIC_CLIENT, que ya no se utiliza. Si aún la tiene en su proyecto, puede eliminarla.

Las demás variables de entorno son compatibles con el nuevo cliente de autenticación. No se requiere ninguna otra acción.

Manejo de la renovación automática

La renovación automática está habilitada de forma predeterminada en el nuevo cliente de autenticación y no se admite REACT_APP_JUTRO_AUTH_AUTO_RENEW. Si desea controlar el estado del token y estar atento a cuándo caduca, puede obtener esta información del token JWT mediante nuestra función decodeJWTTokenPayload.

Analice la posibilidad de implementar un gancho personalizado para supervisar el estado del token. A continuación, se muestra un ejemplo de cómo advertir al usuario que su token está a punto de caducar:

import React, { useEffect, useState } from 'react';
import { useAuth, decodeJWTTokenPayload } from '@jutro/auth';
import { showLogoutAlert } from '@site/components/Alerts'; // your custom alert component

export const useTokenStatus = () => {
  const { idToken } = useAuth();
  const TIME_BEFORE_EXPIRED = 30 * 1000; // 30 seconds

  useEffect(() => {
    const { exp: expiresAt } = decodeJWTTokenPayload(idToken);

    const expireEventWait = Math.max(
      parseInt(expiresAt.toString()) * 1000 - Date.now() - TIME_BEFORE_EXPIRED,
      0
    );

    const expireTimeout = setTimeout(() => {
      showLogoutAlert(TIME_BEFORE_EXPIRED); // logic you handle to warn the user
    }, expireEventWait);

    return () => {
      clearInterval(expireTimeout);
    };
  }, [idToken]);
};

En el ejemplo siguiente se muestra cómo manejar otros eventos, como cuándo se obtiene o elimina el token:

import React, { useEffect, useRef } from 'react';
import { useAuth, decodeJWTTokenPayload } from '@jutro/auth';

export const useLogTokenStatus = () => {
  const { idToken, error } = useAuth();
  const tokenRef = useRef('');

  useEffect(() => {
    if (idToken && !tokenRef.current) {
      console.log('EVENT: ', 'TOKEN_ACQUIRED');
    }
    if (idToken && tokenRef.current) {
      console.log('EVENT: ', 'TOKEN_RENEWED');
    }
    tokenRef.current = idToken;
  }, [idToken]);
};

Eliminados de useAuth

useAuth ya no devuelve diversos valores y funciones. Si utiliza alguno de los siguientes, deberá actualizar su código:

authenticated; use isAuthenticated en su lugar
tokenManager no es compatible
getAccessToken; use accessToken en su lugar
getIdToken; use idToken en su lugar
getDefaultScopes; use decodedToken o decodedJWTTokenPayload en su lugar
getTransientTokens no es compatible
allocateToken no es compatible
decodeToken se ha eliminado de useAuth y ahora es una exportación desde @jutro/auth
getDecodedIdToken; use decodeToken en su lugar, y asegúrese de pasar idToken como argumento
getDecodedAccessToken; use decodeToken en su lugar, y asegúrese de pasar accessToken como argumento

import { useAuth, decodeToken } from '@jutro/auth';

// ...

const { accessToken, idToken } = useAuth();
const decodedAccessToken = decodeToken(accessToken);
const decodedIdToken = decodeToken(idToken);

Funciones actualizadas

login y logout devueltos desde useAuth aceptan parámetros diferentes.

Consulte la documentación de inicio y cierre de sesión para obtener más información.

Otros cambios

Renovación pasiva de tokens

La renovación pasiva de tokens se introdujo en la versión 10.10. La renovación activa no quedó obsoleta, pero se recomienda pasar a la renovación pasiva. Para habilitar esta función, debe realizar los siguientes pasos:

Elimine las variables JUTRO_AUTH_SILENT_REDIRECT_PATH y JUTRO_AUTH_SILENT_LOGIN_PATH, si están presentes. Estas variables son específicas del método activo con inicio de sesión silencioso y no son necesarias para el método pasivo.
Agregue offline_access a la variable JUTRO_AUTH_SCOPE.
Asegúrese de que la configuración de la aplicación Guidewire Hub incluya la concesión REFRESH_TOKEN en su matriz authSettings.grantTypes.
Agregue la variable JUTRO_AUTH_USE_PASSIVE_TOKEN_RENEWALS=true.
Reemplace los siguientes usos de propiedades desde el gancho useAuth:

Renovación activa	Renovación pasiva
`isAuthenticated: boolean \| null`	`getIsAuthenticated: () => Promise<boolean \| null>`
`accessToken: string \| null`	`getAccessToken: () => Promise<string \| null>`
`idToken: string \| null`	`getIdToken: () => Promise<string \| null>`
`userInfo: OidcUserInfo \| null`	`getUserInfo: () => Promise<OidcUserInfo \| null>`

Para obtener más información sobre la renovación pasiva, consulte la documentación del cliente de autenticación.

Variable de entorno `JUTRO_AUTH_PREPEND_AUTH_CALLBACKS_WITH_BASEURL`

La variable de entorno JUTRO_AUTH_PREPEND_AUTH_CALLBACKS_WITH_BASEURL se introdujo en la versión 10.10.

Si se establece el valor de esta variable de entorno en true, se antepondrá automáticamente el valor routerBasename para redirigir las rutas pasadas como argumentos a las funciones de cliente de autenticación login() y logout(). Al pasar rutas de redirección hacia login() y logout() con JUTRO_AUTH_PREPEND_AUTH_CALLBACKS_WITH_BASEURL=false, aparecerá una advertencia de elemento obsoleto.

Para obtener más información, consulte la documentación del cliente de autenticación.

AuthContext eliminado del paquete de autenticación de Jutro

AuthContext ya no forma parte del paquete @jutro/auth. Debe actualizar los usos según su caso específico:

Cambiar const auth = useContext(AuthContext) por const auth = useAuth()

<AuthContext.Provider ... /> - depending on how you are using it, you can do one of the following:

Reemplácelo por AuthProviderStatic:

  <AuthContext.Provider value={...}>
  ...
  </AuthContext.Provider>

  // changed to

import { AuthProviderStatic } from `@jutro/auth`;

<AuthProviderStatic
  userInfo={{ name: 'Authenticated User', sub: '' }}
  accessToken="accessToken"
  idToken="idToken"
  >
...
</AuthProviderStatic>

Si utiliza <AuthContext.Provider ... /> en pruebas unitarias para proporcionar datos de prueba, puede reemplazarlo por useAuth simulado:

jest.mock('@jutro/auth', () => ({
  useAuth: jest.fn(() => ({
    logout: jest.fn(),
    userInfo: {
      name: 'John Doe',
      email: 'john@doe.com',
      picture: './styles/images/avatar/avatar.png',
    },
    isAuthenticated: true,
  })),
}));

Eventos eliminados del ciclo de vida

Dado que los eventos del ciclo de vida de la biblioteca cliente de Okta se han eliminado, los siguientes elementos ya no se exportan desde @jutro/auth:

EVENT_ADDED
EVENT_EXPIRED
EVENT_RENEWED
EVENT_ERROR
EVENT_REMOVED

Consulte la sección Manejo de la renovación automática para obtener más información sobre cómo lograr el mismo comportamiento con idToken y decodeJWTTokenPayload.

Uso de la página de inicio en package.json

Cuando utilice el nuevo cliente de autenticación, si especifica la página de inicio en package.json y ejecuta un servidor de desarrollo local, es posible que la aplicación se bloquee indefinidamente o arroje errores. Para solucionar el problema, deberá realizar una de las siguientes acciones:

Abra la aplicación usando http://localhost:3000/<your "homepage" value>/ (la barra diagonal al final es importante), por ejemplo, si su página de inicio es /storage, debe abrir la aplicación usando http://localhost:3000/storage/.
Elimine la página de inicio de package.json (debe eliminar node_modules/.cache después de este cambio). Si sus implementaciones dejan de funcionar después de ese cambio, probablemente le haya faltado la variable PUBLIC_URL en su configuración. Para obtener más detalles, consulte nuestros documentos sobre el enrutamiento.

Implementación de una aplicación en una subruta

Si está implementando su aplicación en una subruta, por ejemplo company.com/claims-manager, debe agregar el siguiente elemento en index.html de la aplicación para que funcione correctamente: <base href="%PUBLIC_URL%/" />. Consulte la sección Nombre base en la documentación sobre enrutamiento para obtener más información.

AuthContext

El componente AuthContext de @jutro/auth no es compatible con el cliente de autenticación OIDC. El nuevo método es utilizar AuthProviderStatic.

Método antiguo:

<AuthContext.Provider value={{ authenticated: true }}>
  <NavigateStorage navigation={navigation} /> // this calls useAuth inside
</AuthContext.Provider>

Método nuevo:

<AuthProviderStatic
  userInfo={{ name: 'Authenticated User', sub: '' }}
  accessToken="accessToken"
  idToken="idToken">
  <NavigateStorage navigation={navigation} /> // this calls useAuth inside
</AuthProviderStatic>

Otra alternativa para las pruebas unitarias es simular el gancho useAuth:

jest.mock('@jutro/auth', () => ({
  useAuth: jest.fn(() => ({
    logout: jest.fn(),
    accessToken: 'accessToken',
    idToken: 'idToken',
    userInfo: { name: 'Authenticated User', sub: '' },
    isAuthenticated: true,
  })),
}));

Consulte también

Para obtener más información sobre cómo administrar el enrutamiento con su nuevo cliente de autenticación, consulte la documentación sobre enrutamiento.

Renovación activa	Renovación pasiva
`isAuthenticated: boolean \| null`	`getIsAuthenticated: () => Promise<boolean \| null>`
`accessToken: string \| null`	`getAccessToken: () => Promise<string \| null>`
`idToken: string \| null`	`getIdToken: () => Promise<string \| null>`
`userInfo: OidcUserInfo \| null`	`getUserInfo: () => Promise<OidcUserInfo \| null>`

Configuración​

Variables de entorno no admitidas​

Manejo de la renovación automática​

Eliminados de useAuth​

Funciones actualizadas​

Otros cambios​

Renovación pasiva de tokens​

Variable de entorno JUTRO_AUTH_PREPEND_AUTH_CALLBACKS_WITH_BASEURL​

AuthContext eliminado del paquete de autenticación de Jutro​

Eventos eliminados del ciclo de vida​

Uso de la página de inicio en package.json​

Implementación de una aplicación en una subruta​

AuthContext​

Consulte también​