Migration vers le nouveau client d'authentification

Dans la version 8.13.0, nous avons introduit un nouveau client d'authentification. Ce nouveau client offre le choix entre un client d'authentification générique qui n'est lié à aucun fournisseur d'identité (IdP) ou un client basé sur Okta spécifique. Ces nouveaux clients d'authentification ne sont pas rétrocompatibles avec le client d'authentification existant. Si vous utilisez le client d'authentification existant, vous devrez migrer vers le nouveau client d'authentification.

Configuration

Vos variables d'environnement doivent ressembler à ce qui suit :

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

Pour en savoir plus sur les connexions silencieuses, reportez-vous à la documentation sur la connexion silencieuse.

Pour en savoir plus sur la configuration du nouveau client d'authentification, reportez-vous à notre documentation relative au client d'authentification.

Variables d'environnement non prises en charge

Les variables d'environnement suivantes du client d'authentification existant ne sont pas prises en charge dans le nouveau client d'authentification :

REACT_APP_JUTRO_AUTH_PKCE_ENABLED : PKCE est toujours activée dans le nouveau client d'authentification.
REACT_APP_JUTRO_AUTH_IDP : cette variable est directement liée à Okta et n'est pas incluse dans le nouveau client d'authentification qui est générique et non spécifique au fournisseur d'identité. Cela dit, vous pouvez toujours utiliser des paramètres de requête personnalisés pour la connexion et la déconnexion. Pour en savoir plus, reportez-vous à la documentation sur la connexion et la déconnexion.
REACT_APP_JUTRO_AUTH_AUTO_RENEW : le renouvellement automatique est activé par défaut dans le nouveau client d'authentification.
REACT_APP_JUTRO_AUTH_STORAGE : définit le type de mécanisme de stockage utilisé par le système d'authentification de Jutro.

En outre, la variable REACT_APP_JUTRO_AUTH_GENERIC_CLIENT a été supprimée, car elle n'est plus utilisée. Si vous l'avez toujours dans votre projet, vous pouvez la supprimer.

Les autres variables d'environnement sont prises en charge dans le nouveau client d'authentification. Aucune nouvelle action n'est requise.

Gestion du renouvellement automatique

Le renouvellement automatique est activé par défaut dans le nouveau client d'authentification et REACT_APP_JUTRO_AUTH_AUTO_RENEW n'est pas pris en charge. Si vous souhaitez surveiller le statut du jeton et le moment où il expire, vous pouvez obtenir ces informations à partir du jeton JWT à l'aide de notre fonction decodeJWTTokenPayload.

Pensez à implémenter un crochet personnalisé pour surveiller le statut du jeton. Voici un exemple de la façon dont vous pouvez avertir l'utilisateur que son jeton est sur le point d'expirer :

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]);
};

L'exemple suivant montre comment gérer d'autres événements, par exemple lorsque le jeton est acquis ou supprimé :

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]);
};

Supprimé de useAuth

Plusieurs valeurs et fonctions ne sont plus renvoyées par useAuth. Si vous utilisez l'un des éléments suivants, vous devrez mettre à jour votre code :

authenticated : utilisez isAuthenticated à la place
tokenManager : non pris en charge
getAccessToken : utilisez accessToken à la place
getIdToken : utilisez idToken à la place
getDefaultScopes : utilisez decodedToken ou decodedJWTTokenPayload à la place
getTransientTokens : non pris en charge
allocateToken : non pris en charge
decodeToken : a été supprimé de useAuth et est maintenant exporté depuis @jutro/auth
getDecodedIdToken : utilisez decodeToken à la place et assurez-vous de transmettre idToken comme argument
getDecodedAccessToken : utilisez decodeToken à la place et assurez-vous de transmettre accessToken comme argument

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

// ...

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

Fonctions mises à jour

Les valeurs login et logout renvoyées par useAuth acceptent différents paramètres :

Pour en savoir plus, reportez-vous à la documentation sur la connexion et la déconnexion.

Autres modifications

Renouvellement passif des jetons

Le renouvellement passif des jetons a été introduit dans la version 10.10. Le renouvellement actif n'est pas obsolète, mais il est recommandé de passer au renouvellement passif. Pour activer cette fonctionnalité, vous devez suivre les étapes suivantes :

Supprimez les variables JUTRO_AUTH_SILENT_REDIRECT_PATH et JUTRO_AUTH_SILENT_LOGIN_PATH le cas échéant. Ces variables sont spécifiques à l'approche active avec connexion silencieuse et ne sont pas nécessaires à l'approche passive.
Ajoutez offline_access à la variable JUTRO_AUTH_SCOPE.
Assurez-vous que la configuration de l'application Guidewire Hub inclut l'octroi REFRESH_TOKEN dans sa série authSettings.grantTypes.
Ajoutez la variable JUTRO_AUTH_USE_PASSIVE_TOKEN_RENEWALS=true.
Remplacez les utilisations suivantes des propriétés à partir du crochet useAuth :

Renouvellement actif	Renouvellement passif
`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>`

Pour en savoir plus sur le renouvellement passif, consultez la documentation sur le client d'authentification.

Variable d'environnement `JUTRO_AUTH_PREPEND_AUTH_CALLBACKS_WITH_BASEURL`

La variable d'environnement JUTRO_AUTH_PREPEND_AUTH_CALLBACKS_WITH_BASEURL a été introduite dans la version 10.10.

La définition de la valeur de cette variable d'environnement sur true ajoute automatiquement la valeur routerBasename aux chemins de redirection ayant été transmis en tant qu'arguments aux fonctions du client d'authentification login() et logout(). La transmission de chemins de redirection vers login() et logout() avec JUTRO_AUTH_PREPEND_AUTH_CALLBACKS_WITH_BASEURL=false affiche un avertissement d'obsolescence.

Pour en savoir plus, consultez la documentation sur le client d'authentification.

AuthContext supprimé du package d’authentification de Jutro

AuthContext ne fait plus partie du package @jutro/auth. Vous devez mettre à jour ses utilisations en fonction de votre cas spécifique :

Modifiez const auth = useContext(AuthContext) en const auth = useAuth()

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

Remplacez-le par 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 vous utilisez <AuthContext.Provider ... /> dans les tests d'unité pour fournir des données de test, vous pouvez le remplacer par des simulations de useAuth :

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,
  })),
}));

Événements de cycle de vie supprimés

Les événements de cycle de vie de la bibliothèque du client Okta ayant été supprimés, les éléments suivants ne sont plus exportés depuis @jutro/auth :

EVENT_ADDED
EVENT_EXPIRED
EVENT_RENEWED
EVENT_ERROR
EVENT_REMOVED

Consultez la section Gestion du renouvellement automatique pour savoir comment obtenir le même comportement à l'aide de idToken et decodeJWTTokenPayload.

Utilisation de la page d'accueil dans package.json

Lors de l'utilisation du nouveau client d'authentification, si vous spécifiez la page d'accueil dans package.json et que vous exécutez un serveur de développement local, votre application peut se bloquer indéfiniment ou générer des erreurs. Pour résoudre le problème, vous devez effectuer l'une des opérations suivantes :

Ouvrez l'application en utilisant http://localhost:3000/<your "homepage" value>/ (la barre oblique à la fin compte), par exemple si votre page d'accueil est /storage, vous devez ouvrir l'application en utilisant http://localhost:3000/storage/.
Supprimez la page d'accueil du fichier package.json (vous devez supprimer node_modules/.cache après cette modification). Si vos déploiements cessent de fonctionner après cette modification, vous avez probablement oublié la variable PUBLIC_URL dans vos configurations. Pour en savoir plus, reportez-vous à notre documentation sur le routage.

Déploiement d'une application sur un sous-itinéraire

Si vous déployez votre application sur un sous-itinéraire, par exemple company.com/claims-manager, vous devez ajouter l'élément suivant dans le index.html de l'application pour qu'il fonctionne correctement : <base href="%PUBLIC_URL%/" />. Pour en savoir plus, reportez-vous à la section basename de la documentation sur le routage.

AuthContext

Le composant AuthContext de @jutro/auth n'est pas compatible avec le client d'authentification OIDC. La nouvelle approche consiste à utiliser AuthProviderStatic.

Ancienne approche :

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

Nouvelle approche :

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

Pour les tests d'unités, vous pouvez également simuler le crochet useAuth :

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

Voir également

Pour en savoir plus sur la gestion du routage avec votre nouveau client d’authentification, reportez-vous à la documentation sur le routage.

Renouvellement actif	Renouvellement passif
`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>`

Configuration​

Variables d'environnement non prises en charge​

Gestion du renouvellement automatique​

Supprimé de useAuth​

Fonctions mises à jour​

Autres modifications​

Renouvellement passif des jetons​

Variable d'environnement JUTRO_AUTH_PREPEND_AUTH_CALLBACKS_WITH_BASEURL​

AuthContext supprimé du package d’authentification de Jutro​

Événements de cycle de vie supprimés​

Utilisation de la page d'accueil dans package.json​

Déploiement d'une application sur un sous-itinéraire​

AuthContext​

Voir également​