Clients d'authentification

Jutro fournit deux clients d'authentification : un client Okta natif et un client d'authentification générique OpenID Connect (OIDC).

Okta est un fournisseur d'identité (IdP) qui suit la norme OIDC et le client Okta natif est conçu pour le prendre en charge spécifiquement. Vous pouvez utiliser le client OIDC générique pour vous authentifier auprès d'autres fournisseurs d'identité prenant en charge la norme OIDC.

Fonctionnalités client

Les clients d'authentification Jutro fournis dans le package @jutro/auth offrent les fonctionnalités suivantes :

• Connexion à l'application.
• Déconnexion de l'application.
• Lorsqu'un nouvel onglet avec l'application est ouvert, les jetons sont partagés.
• Lorsque l'utilisateur se déconnecte dans un onglet, la déconnexion se produit dans tous les autres onglets.
• Le client actualise le jeton un nombre défini de secondes avant l’expiration.
• Le client coordonne l’actualisation des jetons entre les onglets.

Du point de vue du développeur, il existe quelques fonctionnalités plus spécifiques, telles que :

• Prise en charge du flux de code d'autorisation OIDC avec l'extension PKCE.
• Gestion des jetons pour des actions comme le stockage, la récupération et la validation.
• Possibilité de définir des champs d'application.
• Garantie de la sécurité.
• Gestion des erreurs.
• Accès aux informations de l'utilisateur.

Dépendance d'authentification facultative

La dépendance @jutro/auth est désormais facultative pour les packages @jutro/router et @jutro/components. Pour certains composants, il est toutefois nécessaire de l'ajouter aux dépendances de votre application afin de pouvoir l'utiliser. La liste suivante de composants nécessite l'ajout de @jutro/auth :

Composant	Importer depuis
ApplicationRoot	@jutro/app
Avatar	@jutro/components
DropdownMenuAvatar	@jutro/components
DropdownMenuAvatarContent	@jutro/components
AppFloorPlan	@jutro/floorplan
MicroFrontEnd	@jutro/micro-frontends
SecureRoute	@jutro/router

Configuration

Toute la configuration est effectuée avec des variables d'environnement d'exécution. Les variables suivantes sont requises :

• 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.

Si vous utilisez une application de démarrage Jutro, ces variables suffisent pour activer l'authentification. La logique est gérée dans la fonction Jutro start().

Tip: Certaines routes sont ouvertes

Si vous utilisez un AppFloorPlan lorsque l'authentification est activée, toutes vos routes sont sécurisées. Si vous souhaitez que certaines routes soient ouvertes tandis que d'autres sont sécurisées, vous devez implémenter votre propre routeur. Pour en savoir plus, reportez-vous à notre documentation sur l'authentification personnalisée.

Découverte OIDC (configuration d'habilitation)

OpenID Connect (OIDC) définit un mécanisme de découverte qui vous permet de configurer votre application sans avoir besoin de connaître les terminaux exacts de votre fournisseur d'identité. Le mécanisme de découverte est basé sur le terminal /.well-known/openid-configuration qui renvoie un document JSON avec toutes les informations nécessaires.

Pour en savoir plus, lisez cet article sur le mécanisme de découverte.

Dans les cas où le terminal de découverte automatique ne fonctionne pas comme prévu, vous avez besoin des variables d'environnement d'exécution suivantes pour la configuration manuelle des habilitations.

• REACT_APP_JUTRO_AUTH_AUTHORIZATION_ENDPOINT
• REACT_APP_JUTRO_AUTH_TOKEN_ENDPOINT
• REACT_APP_JUTRO_AUTH_REVOCATION_ENDPOINT
• REACT_APP_JUTRO_AUTH_END_SESSION_ENDPOINT
• REACT_APP_JUTRO_AUTH_USERINFO_ENDPOINT

Par exemple, vous devrez peut-être définir les éléments suivants :

REACT_APP_JUTRO_AUTH_AUTHORIZATION_ENDPOINT=https://YOUR_DOMAIN/authorize
REACT_APP_JUTRO_AUTH_TOKEN_ENDPOINT=https://YOUR_DOMAIN/oauth/token
REACT_APP_JUTRO_AUTH_REVOCATION_ENDPOINT=https://YOUR_DOMAIN/oauth/revoke
REACT_APP_JUTRO_AUTH_END_SESSION_ENDPOINT=https://YOUR_DOMAIN/oidc/logout
REACT_APP_JUTRO_AUTH_USERINFO_ENDPOINT=https://YOUR_DOMAIN/userinfo

Warning: Si vous définissez l’une de ces variables, vous devez toutes les définir.

Configuration de l’approche d’actualisation des jetons

Jutro propose deux approches pour l’actualisation des jetons : le renouvellement passif des jetons et la connexion silencieuse (également appelée renouvellement actif des jetons). Vous utilisez les options de configuration suivantes pour définir une approche de renouvellement des jetons :

Pour un renouvellement passif des jetons, vous devez définir la propriété JUTRO_AUTH_USE_PASSIVE_TOKEN_RENEWALS sur true.

JUTRO_AUTH_USE_PASSIVE_TOKEN_RENEWALS=true

Pour une connexion silencieuse, vous devez définir un chemin de redirection et un chemin de connexion pour la connexion silencieuse.

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 approches de renouvellement des jetons et leur configuration, reportez-vous à la section Options d’actualisation des jetons.

Warning: Vous ne pouvez pas utiliser les deux approches en même temps. Vous devez supprimer l’option de configuration JUTRO_AUTH_USE_PASSIVE_TOKEN_RENEWALS si vous voulez utiliser la connexion silencieuse.

Paramètres de requête personnalisés

Vous pouvez définir des paramètres de requête personnalisés que vous souhaitez appliquer à toutes les demandes de connexion à l'aide de la variable d'environnement REACT_APP_JUTRO_AUTH_LOGIN_QUERY_EXTRAS :

Note: Le client OIDC générique ajoute la prise en charge des paramètres de requête personnalisés aux demandes de déconnexion. Vous pouvez les définir à l'aide de la variable d'environnement REACT_APP_JUTRO_AUTH_LOGOUT_QUERY_EXTRAS.

Les valeurs que vous fournissez doivent être des valeurs JSON valides. Elles seront analysées et ajoutées à la chaîne de requête de la demande de connexion ou de déconnexion.

Par exemple, vous pouvez ajouter un paramètre prompt à la demande d'autorisation pour forcer l'utilisateur à se reconnecter.

REACT_APP_JUTRO_AUTH_LOGIN_QUERY_EXTRAS={"prompt":"login"}

Notez qu'il s'agit de variables d'environnement d'exécution, qui s'appliquent donc à toutes les demandes de connexion et de déconnexion (si vous utilisez le client OIDC générique) dans votre application. Pour ajouter des paramètres de requête personnalisés à une demande de connexion spécifique, reportez-vous à la section Connexion et déconnexion.

Jetons de déconnexion à invalider

Il arrive parfois que vous ayez besoin d'invalider uniquement certains jetons lors de la déconnexion. Par exemple, votre fournisseur OIDC peut invalider automatiquement tous les jetons associés à un jeton d'actualisation donné. Lorsque vous vous déconnectez de votre application, vous souhaitez invalider uniquement le jeton d'actualisation, car le jeton d'accès est automatiquement invalidé. Dans ce cas, vous devez définir les éléments suivants :

REACT_APP_JUTRO_AUTH_LOGOUT_TOKENS_TO_INVALIDATE=refresh_token

Dans ce cas, la fonction logout invalidera uniquement le jeton d'actualisation. Si vous ne définissez pas explicitement JUTRO_AUTH_LOGOUT_TOKENS_TO_INVALIDATE, la fonction logout invalide tous les jetons, car la valeur par défaut est access_token,refresh_token.

Fournisseur de contexte AuthProvider

AuthProvider est le fournisseur de contexte que vous pouvez utiliser pour encapsuler votre application. Pour en savoir plus, reportez-vous à la page API du client d’authentification.

Si vous souhaitez que l’ensemble de votre application soit sécurisé après la connexion, vous n’avez pas besoin de vous soucier de AuthProvider, car il est implémenté par défaut dans la fonction Jutro start().

Crochet useAuth

Le crochet useAuth donne accès à l'état d'authentification. Pour en savoir plus, reportez-vous à la page API du client d’authentification.

Erreurs d'authentification

Les codes d'erreur d'authentification Jutro sont exposés via des points d'entrée publics sous la forme AuthErrorCodes.

Il existe six codes d’erreur d’authentification Jutro :

Erreur	Cause
JUTRO_AUTH_LOGIN_ERROR	L’application n’a pas pu acquérir de jetons d’authentification.
JUTRO_AUTH_REFRESH_ERROR	L’application n’a pas pu renouveler de jetons d’authentification.
JUTRO_AUTH_USER_INFO_ERROR	L’application n’a pas pu récupérer les informations utilisateur.
JUTRO_AUTH_UNKNOWN_ERROR	Une erreur inconnue s'est produite.
JUTRO_AUTH_ACCESS_DENIED_ERROR	L’utilisateur n’est pas affecté à l’application.
JUTRO_AUTH_LOGIN_REQUIRED_ERROR	L’application n’a pas pu renouveler les jetons à l’aide de l’approche de type connexion silencieuse, car le navigateur bloque les cookies tiers.

Si vous implémentez une logique d’authentification personnalisée, vous devrez peut-être ajouter un traitement personnalisé pour certaines de ces erreurs. Pour en savoir plus, reportez-vous à la section Gestion des erreurs d’authentification personnalisée de la page Implémentation de la logique d’authentification personnalisée.

Gestion des cookies de session tiers

Les cookies de session tiers peuvent être limités sur certains navigateurs Web, ce qui peut entraîner des problèmes de gestion des sessions à l'aide de certains clients OIDC. Par ailleurs, l’approche de type connexion silencieuse en matière d’actualisation des jetons ne fonctionne pas si les cookies tiers sont restreints et enverra JUTRO_AUTH_LOGIN_REQUIRED_ERROR dans ce scénario.

Pour vous assurer que les sessions de vos utilisateurs sont gérées correctement, vous devez apporter les modifications suivantes :

• Si vous utilisez le client OIDC générique sans connexion silencieuse, supprimez les variables JUTRO_AUTH_SILENT_LOGIN_PATH et JUTRO_AUTH_SILENT_REDIRECT_PATH.

• Si vous utilisez le client OIDC générique avec connexion silencieuse, passez au renouvellement passif des jetons.

• Étendez la variable de configuration REACT_APP_JUTRO_AUTH_SCOPE en ajoutant offline_access. Par exemple : REACT_APP_JUTRO_AUTH_SCOPE=openid,tenant_id,email,profile,offline_access

• Mettez à jour la configuration de votre application Keti pour inclure l'octroi REFRESH_TOKEN dans la série authSettings.grantTypes. Pour ce faire, exécutez les étapes suivantes :
  1. Effectuez un appel GET /applications/{appId} d'API GET pour obtenir les paramètres de configuration actuels de votre application.
  2. Copiez la charge utile de l'application renvoyée.
  3. Ajoutez REFRESH_TOKEN à la section grantTypes de la charge utile copiée.
  4. Effectuez un appel PUT /applications/{appId} d'API PUT avec la nouvelle charge utile pour mettre à jour la configuration de votre application.

Authentification personnalisée

Si vous souhaitez que l’ensemble de votre application soit sécurisé après la connexion, vous n’avez pas besoin de vous soucier d’une personnalisation supplémentaire. La logique d'authentification est gérée dans la fonction Jutro start().

Si vous souhaitez contrôler la façon dont votre application applique la connexion, par exemple, si vous n’avez besoin de vous connecter que pour certaines pages, vous devrez implémenter une logique d’authentification personnalisée. Pour en savoir plus, reportez-vous à la page Implémentation d’une logique d’authentification personnalisée.