Passer au contenu principal

API d'authentification client

En tant que développeur, vous pouvez utiliser les composants, crochets et fonctions suivants pour implémenter l'authentification dans votre application.

Fournisseur de contexte AuthProvider​

AuthProvider est le fournisseur de contexte que vous pouvez utiliser pour encapsuler votre application. Il permet d'accéder au crochet useAuth.

AuthProvider possède les propriétés suivantes :

children​

Type
React.ReactNode
Description

Nodes wrapped by the AuthProvider component.

location​

Type
{ pathname: string }
Description

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

onLocationChange​

Type
(location: string | Record<string, unknown>) => void
Description

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

Si vous utilisez une application générée à l'aide de l'application de démarrage Jutro, vous n'avez pas besoin d'ajouter AuthProvider vous-même. Il est ajouté automatiquement dans la fonction start().

Pour en savoir plus, reportez-vous à la page Implémentation d’une logique d’authentification personnalisée.

Crochet useAuth​

Le crochet useAuth donne accès à l'état d'authentification. Il renvoie un objet AuthContext avec les variables suivantes :

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

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

Variables de contexte d’authentification​

Variables communes​

Les variables suivantes sont les mêmes, quelle que soit la méthode d’actualisation des jetons utilisée.

isPending​

Type
boolean
Description

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

error​

Type
Description

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

login​

Type
Description

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

logout​

Type
Description

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

renewTokens​

Type
(extraParams?: Record<string, string>) => Promise<void>
Description

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 d’actualisation active des jetons uniquement​

Les variables suivantes sont utilisées lorsque l’actualisation active des jetons est en cours d’utilisation. Si l’actualisation passive des jetons est en cours d’utilisation, elles sont toutes null.

isAuthenticated​

Type
boolean | null
Description

If set to true, the user is currently authenticated.

accessToken​

Type
string | null
Description

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

idToken​

Type
string | null
Description

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

userInfo​

Type
OidcUserInfo | null
Description

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

Variables d’actualisation passive des jetons uniquement​

Les variables suivantes sont utilisées lorsque l’actualisation passive des jetons est en cours d’utilisation. Ces variables fonctionnent comme les variables d’actualisation active des jetons, mais elles sont asynchrones, renouvellent les jetons si nécessaire et renvoient les données attendues. Si l’actualisation active des jetons est en cours d’utilisation ou si le renouvellement des jetons échoue, elles renvoient une promesse qui correspond à null.

getIsAuthenticated​

Type
() => Promise<boolean | null>
Description

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​

Type
() => Promise<string | null>
Description

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

getIdToken​

Type
() => Promise<string | null>
Description

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

getUserInfo​

Type
() => Promise<OidcUserInfo | null>
Description

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

Pour en savoir plus sur l’actualisation des jetons, reportez-vous à la page d’actualisation des jetons.

connexion et déconnexion​

Ces deux fonctions sont renvoyées par le crochet useAuth. Elles vous permettent de déclencher respectivement le processus de connexion et de déconnexion. Vous pouvez transmettre les arguments suivants à l'un d'entre eux :

Chemin de redirection​

Le chemin de redirection désigne le chemin vers lequel se rediriger après l'opération de connexion ou de déconnexion.

Vous pouvez configurer le chemin de redirection après la connexion ou la déconnexion de plusieurs façons. Par défaut, Jutro utilise des chemins d'accès intégrés : /callback pour la connexion et /logout pour la déconnexion. Vous pouvez également définir des chemins personnalisés à l’aide des variables de configuration : JUTRO_AUTH_REDIRECT_PATH pour la connexion et JUTRO_AUTH_LOGOUT_REDIRECT_PATH pour la déconnexion. Par ailleurs, vous pouvez définir le chemin de redirection en le transmettant en tant que premier argument aux fonctions login() et logout(). Ces paramètres sont nommés callbackPath pour login() et fromPath pour logout().

Le tableau suivant récapitule ces informations :

FonctionNom du paramètreValeur extraite du fichier de configurationChemin par défaut intégré
login()callbackPathJUTRO_AUTH_REDIRECT_PATH/callback
logout()fromPathJUTRO_AUTH_LOGOUT_REDIRECT_PATH/logout

La variable d'environnement JUTRO_AUTH_PREPEND_AUTH_CALLBACKS_WITH_BASEURL doit être définie sur true pour ajouter la valeur routerBasename à la chaîne saisie en tant que paramètre des fonctions login() ou logout().

Note: La variable d'environnement JUTRO_AUTH_PREPEND_AUTH_CALLBACKS_WITH_BASEURL a été introduite dans la version 10.10 de Jutro et le paramètre JUTRO_AUTH_PREPEND_AUTH_CALLBACKS_WITH_BASEURL=false est considéré comme obsolète. Pour obtenir des instructions sur l'utilisation des fonctions login() ou logout() sans ajouter automatiquement routerBasename, passez à une version de la documentation antérieure à 10.10.
Note: Restriction sur les valeurs de JUTRO_AUTH_LOGOUT_REDIRECT_PATH

La variable d'environnement JUTRO_AUTH_LOGOUT_REDIRECT_PATH peut être le chemin de fin de l'URL de déconnexion ou l'URL complète.

Par exemple, supposons que l'application soit déployée sur l'URL factice guidewire.com/my-best-app et que le chemin de redirection de déconnexion souhaité soit 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 présence de ce paramètre dépend de la fonction et du client que vous utilisez. Pour la fonction login, il est présent dans les deux clients. Pour la fonction logout, il n'est pas présent pour le client Okta générique.

login() additionalParams​

Dans les deux clients, la fonction login() a un argument facultatif additionalParams. Cet argument utilise un objet avec des paramètres de requête supplémentaires que vous souhaitez ajouter à la demande de connexion.

Vous pouvez les définir globalement à l'aide de la variable d'environnement d'exécution JUTRO_AUTH_LOGIN_QUERY_EXTRAS.

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

Afin de définir ces valeurs de manière dynamique en fonction des variables d'environnement, incluez le code suivant dans le fichier .env ou en tant que variable de déploiement :

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

Pour confirmer qu'il fonctionne correctement, utilisez le code suivant localement. S'il fonctionne correctement, cette opération doit se résoudre en un objet avec une chaîne vide dans la clé idp si YOUR_IDP_ID n’est pas fourni. Si YOUR_IDP_ID est fourni, la valeur est définie en conséquence.

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

Si vous utilisez le client OIDC générique, la fonction logout() a également un argument facultatif additionalParams.

Vous pouvez les définir globalement à l'aide de la variable d'environnement d'exécution JUTRO_AUTH_LOGOUT_QUERY_EXTRAS.

Afin de définir ces valeurs de manière dynamique en fonction des variables d'environnement, incluez le code suivant dans le fichier .env ou en tant que variable de déploiement :

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

Pour confirmer qu'il fonctionne correctement, utilisez le code suivant localement. S'il fonctionne correctement, cette opération doit se résoudre en un objet avec une chaîne vide dans la clé idp si YOUR_IDP_ID n’est pas fourni. Si YOUR_IDP_ID est fourni, la valeur est définie en conséquence.

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

Fonction renewTokens​

Par défaut, un flux d’actualisation des jetons est exécuté 40 secondes avant l’heure d’expiration (bien que ce comportement puisse varier si une autre approche d’actualisation des jetons est utilisée). Si vous souhaitez mieux contrôler le flux d'actualisation des jetons, vous pouvez utiliser la fonction renewTokens du crochet useAuth. Cela vous permet de lancer le flux d'actualisation des jetons à tout moment.

Par exemple, pour qu'un bouton force l'actualisation d'un jeton lorsqu'on clique dessus, vous pouvez utiliser ce code :

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

Les appels multiples à renewTokens ne lanceront pas plusieurs flux : seul le premier appel le fera, et tous les appels suivants renverront la même promesse. Un nouveau flux de renouvellement ne peut être initié qu'une fois le précédent terminé.

Note: renewTokens renvoie un Promise<void>, mais il est imprudent de lire la nouvelle valeur du jeton directement à partir de celui-ci, car il risque d'afficher l'ancienne valeur. La manière correcte d'accéder au nouveau jeton est la suivante :
const { accessToken, renewTokens } = useAuth();
// ...
useEffect(() => {
  console.log('new token', accessToken);
}, [accessToken]);
// ...
<button onClick={() => renewTokens()}>Force tokens renewal</button>;

accessToken et idToken​

Vous pouvez utiliser les propriétés accessToken ou idToken pour récupérer le jeton d’authentification d’un utilisateur. Cette propriété est utilisée avec les fonctions decode token et decodeJWTTokenPayload du package @jutro/auth.

decodeToken​

La fonction decodeToken décode le jeton d’authentification d’un utilisateur.

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

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

decodeJWTTokenPayload​

La fonction decodeJWTTokenPayload décode uniquement la charge utile du jeton sans l'en-tête, la signature ou tout autre champ que le jeton peut contenir.

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

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