Saltar al contenido principal

API del cliente de autenticación

Los desarrolladores pueden utilizar los siguientes componentes, ganchos y funciones para implementar la autenticación en su aplicación.

Proveedor de contexto AuthProvider​

AuthProvider es el proveedor de contexto que puede utilizar para encapsular su aplicación. Proporciona acceso al gancho useAuth.

AuthProvider tiene las siguientes propiedades.

children​

Tipo
React.ReactNode
Descripción

Nodes wrapped by the AuthProvider component.

location​

Tipo
{ pathname: string }
Descripción

Current window location. If you use react-router-dom, pass the result of useLocation().

onLocationChange​

Tipo
(location: string | Record<string, unknown>) => void
Descripción

Callback to change window location. If you use react-router-dom, pass path => history.replace(path).

Si está trabajando con una aplicación generada con la aplicación de inicio de Jutro, no tiene que agregarse AuthProvider. Se agrega automáticamente en la función start().

Para obtener más información y una explicación sobre su uso, consulte la página Implementación de la autenticación personalizada.

Gancho useAuth​

El gancho useAuth proporciona acceso al estado de autenticación. Devuelve un objeto AuthContext con las siguientes variables:

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

const {
  isPending,
  error,
  login,
  logout,
  renewTokens,
  isAuthenticated,
  accessToken,
  idToken,
  userInfo,
  getIsAuthenticated,
  getAccessToken,
  getIdToken,
  getUserInfo,
} = useAuth();

Variables de contexto de autenticación​

Variables comunes​

Las siguientes variables son las mismas, independientemente del método de actualización de token que esté en uso.

isPending​

Tipo
boolean
Descripción

If set to true, indicates that authentication is still pending.

error​

Tipo
Descripción

This property is present only if an error occurs. It contains an AuthError object with details about the error.

login​

Tipo
Descripción

The function called to initiate a log in. For more details, see the login and logout section.

logout​

Tipo
Descripción

The function called to initiate a log out. For more details, see the login and logout section.

renewTokens​

Tipo
(extraParams?: Record<string, string>) => Promise<void>
Descripción

The function called to refresh a user's authentication tokens. This gives you more control over when the token refresh flow is triggered. For more details, see the renewToken function section.

Variables de solo actualización activa de token​

Las siguientes variables se usan para la actualización activa de token. Si se está utilizando la actualización pasiva de token, todos son null.

isAuthenticated​

Tipo
boolean | null
Descripción

If set to true, the user is currently authenticated.

accessToken​

Tipo
string | null
Descripción

This string is the user's encoded access token. For further details, see the accessToken and idToken section.

idToken​

Tipo
string | null
Descripción

This string is the user's encoded ID token. For further details, see the accessToken and idToken section.

userInfo​

Tipo
OidcUserInfo | null
Descripción

This is the user's OIDC user info. For more details, see the OIDC documentation.

Variables de solo actualización pasiva de token​

Las siguientes variables se usan para la actualización pasiva de token. Estas variables funcionan como las variables de actualización activa de token, pero son asincrónicas, renuevan los tokens si es necesario y devuelven los datos esperados. Si se está usando una actualización activa de token o falla la renovación de token, devuelven una promesa que se resuelve como null.

getIsAuthenticated​

Tipo
() => Promise<boolean | null>
Descripción

This function returns a promise that resolves to the user's current authentication status. If it resolves to true, the user is currently authenticated.

getAccessToken​

Tipo
() => Promise<string | null>
Descripción

This function returns a promise that resolves to the user's encoded access token. For further details, see the accessToken and idToken section.

getIdToken​

Tipo
() => Promise<string | null>
Descripción

This function returns a promise that resolves to the user's encoded ID token. For further details, see the accessToken and idToken section.

getUserInfo​

Tipo
() => Promise<OidcUserInfo | null>
Descripción

This function returns a promise that resolves to user's OIDC user info. For more details, see the OIDC documentation.

Para obtener más información sobre la actualización de tokens, consulte la página Actualización de tokens.

Inicio y cierre de sesión​

El gancho useAuth devuelve estas dos funciones. Le permiten activar el proceso de inicio y cierre de sesión, respectivamente. Puede pasar los siguientes argumentos a cualquiera de ellos:

Ruta de redirección​

La ruta de redirección designa la ruta a la que se redirigirá después de la operación de inicio o cierre de sesión.

Puede configurar la ruta de redirección después del inicio o cierre de sesión de varias maneras. Jutro utiliza rutas predeterminadas integradas: /callback para inicio de sesión y /logout para cierre de sesión. También puede establecer rutas personalizadas utilizando las variables de configuración: JUTRO_AUTH_REDIRECT_PATH para inicio de sesión y JUTRO_AUTH_LOGOUT_REDIRECT_PATH para cierre de sesión. Además, puede establecer la ruta de redirección pasándola como primer argumento a las funciones login() y logout(). Estos parámetros se denominan callbackPath para login() y fromPath para logout().

La siguiente tabla describe esta información:

FunciónNombre de parámetroValor extraído del archivo de configuraciónRuta predeterminada integrada
login()callbackPathJUTRO_AUTH_REDIRECT_PATH/callback
logout()fromPathJUTRO_AUTH_LOGOUT_REDIRECT_PATH/logout

La variable de entorno JUTRO_AUTH_PREPEND_AUTH_CALLBACKS_WITH_BASEURL debe establecerse en true para anteponer el valor routerBasename al string ingresado como parámetro de las funciones login() o logout().

Note: La variable de entorno JUTRO_AUTH_PREPEND_AUTH_CALLBACKS_WITH_BASEURL se introdujo en la versión 10.10 de Jutro y la configuración JUTRO_AUTH_PREPEND_AUTH_CALLBACKS_WITH_BASEURL=false se considera obsoleta. Para obtener instrucciones sobre cómo utilizar las funciones login() o logout() sin anteponer automáticamente routerBasename, consulte una versión de la documentación anterior a la 10.10.
Note: Restricción de valores para JUTRO_AUTH_LOGOUT_REDIRECT_PATH

La variable de entorno JUTRO_AUTH_LOGOUT_REDIRECT_PATH puede ser la ruta final de la URL de cierre de sesión o la URL completa.

Por ejemplo, supongamos que la aplicación se implementa en la URL guidewire.com/my-best-app falsa y la ruta de redirección de cierre de sesión deseada es guidewire.com/my-best-app/logout:

JUTRO_AUTH_LOGOUT_REDIRECT_PATH=/my-best-app/logout                         // correct - will render as https://guidewire.com/my-best-app/logout
JUTRO_AUTH_LOGOUT_REDIRECT_PATH=/logout                                     // correct - will render as https://guidewire.com/my-best-app/logout
JUTRO_AUTH_LOGOUT_REDIRECT_PATH=https://guidewire.com/my-best-app/logout    // correct - will render as https://guidewire.com/my-best-app/logout
JUTRO_AUTH_LOGOUT_REDIRECT_PATH=guidewire.com/my-best-app/logout            // incorrect - will render as https://guidewire.com/my-best-app/guidewire.com/my-best-app/logout

additionalParams​

La presencia de este parámetro depende de la función y del cliente que se esté utilizando. En el caso de la función login, está presente en ambos clientes. Para la función logout, no está presente para el cliente genérico de Okta.

login() additionalParams​

En ambos clientes, la función login() tiene un argumento additionalParams opcional. Este argumento toma un objeto con parámetros de consulta adicionales que desee agregar a la solicitud de inicio de sesión.

Puede establecerlos globalmente con la variable de entorno en tiempo de ejecución JUTRO_AUTH_LOGIN_QUERY_EXTRAS.

login('/my-account', { idp: 'some-idp' });

Para establecer estos valores dinámicamente en función de las variables de entorno, incluya el siguiente código en el archivo .env o como variable de implementación:

JUTRO_AUTH_LOGIN_QUERY_EXTRAS = {"idp":"${YOUR_IDP_ID}"}

Para confirmar que funciona correctamente, utilice el siguiente código de manera local. Si funciona bien, esto se resolverá en un objeto con un string vacío en la clave idp, si no se proporciona YOUR_IDP_ID. Si se proporciona YOUR_IDP_ID, el valor se establecerá en consecuencia.

import { getConfigValue } from '@jutro/config';
...
console.log(JSON.parse(getConfigValue('JUTRO_AUTH_LOGIN_QUERY_EXTRAS')));
logout() additionalParams​

Si usa el cliente OIDC genérico, la función logout() también tiene un argumento additionalParams opcional.

Puede establecerlos globalmente con la variable de entorno de tiempo de ejecución JUTRO_AUTH_LOGOUT_QUERY_EXTRAS.

Para establecer estos valores dinámicamente en función de las variables de entorno, incluya el siguiente código en el archivo .env o como variable de implementación:

JUTRO_AUTH_LOGOUT_QUERY_EXTRAS = {"idp":"${YOUR_IDP_ID}"}

Para confirmar que funciona correctamente, utilice el siguiente código de manera local. Si funciona bien, esto se resolverá en un objeto con un string vacío en la clave idp, si no se proporciona YOUR_IDP_ID. Si se proporciona YOUR_IDP_ID, el valor se establecerá en consecuencia.

import { getConfigValue } from '@jutro/config';
...
console.log(JSON.parse(getConfigValue('JUTRO_AUTH_LOGOUT_QUERY_EXTRAS')));

Función renewTokens​

De forma predeterminada, un flujo de actualización de token se ejecuta 40 segundos antes del momento de caducidad (aunque este comportamiento puede variar si se utiliza un método alternativo de actualización de token). Si desea tener más control sobre el flujo de actualización de tokens, puede usar la función renewTokens desde el gancho useAuth. Le permite iniciar el flujo de actualización de tokens en cualquier momento arbitrario.

Por ejemplo, para que un botón fuerce una actualización de token al hacer clic en él, use este código:

import React from 'react';
import { useAuth } from '@jutro/auth';
// ...
const { renewTokens } = useAuth();
// ...
<button onClick={() => renewTokens()}>Force tokens renewal</button>;

Múltiples llamadas a renewTokens no iniciarán varios flujos; solo lo hará la primera llamada y las posteriores devolverán la misma promesa. Se puede iniciar un nuevo flujo de renovación solo después de que se haya completado el anterior.

Note: renewTokens devuelve un Promise<void>, pero no es seguro leer el nuevo valor del token directamente desde él, ya que puede mostrar el valor anterior. La forma correcta de acceder a un nuevo token es esta:
const { accessToken, renewTokens } = useAuth();
// ...
useEffect(() => {
  console.log('new token', accessToken);
}, [accessToken]);
// ...
<button onClick={() => renewTokens()}>Force tokens renewal</button>;

accessToken e idToken​

Puede usar las propiedades accessToken o idToken para recuperar el token de autenticación de un usuario. Esta propiedad se utiliza con las funciones decodificar token y decodeJWTTokenPayload del paquete @jutro/auth.

decodeToken​

La función decodeToken decodifica el token de autenticación de un usuario.

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

const { accessToken } = useAuth();
const decodedToken = decodeToken(accessToken);

decodeJWTTokenPayload​

La función decodeJWTTokenPayload decodifica solo la carga útil del token sin el encabezado, la firma o cualquier otro campo que pueda contener.

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

const { accessToken } = useAuth();
const decodedJWTTokenPayload = decodeJWTTokenPayload(accessToken);