Apportez votre propre interface utilisateur

Logto vous permet d'apporter votre propre interface utilisateur pour remplacer complètement l'interface de l'expérience de connexion intégrée, en plus des options de personnalisation de l'interface préconçues. Cette fonctionnalité vous permet de téléverser un fichier zip contenant vos ressources UI personnalisées (HTML, CSS, JavaScript, images, etc.), de les héberger sur les serveurs de Logto Cloud, et de les utiliser comme expérience de connexion pour les utilisateurs de votre tenant.

remarque:

Cette fonctionnalité nécessite que votre interface personnalisée soit compatible avec les applications monopage (SPA), et il est recommandé d'utiliser systématiquement une version de production pour des performances optimales.

Explorer la fonctionnalité d’interface personnalisée dans Logto Console

Commencer avec le projet officiel

La façon la plus rapide de démarrer une interface de connexion personnalisée est de cloner le projet Logto experience. Il s'agit de l'interface de connexion intégrée de Logto qui couvre toutes les fonctionnalités et les meilleures pratiques de Logto. Vous pouvez la personnaliser selon vos besoins.

Après avoir récupéré le code, il suffit d’exécuter la commande suivante pour construire le projet :

pnpm install && pnpm build

remarque:

L'ensemble du projet Logto est un monorepo pnpm. Si vous souhaitez exécuter le package experience de manière autonome (sans pnpm), remplacez les dépendances workspace: dans package.json par des numéros de version spécifiques (comme ^1.0.0).

Une fois la construction terminée, vous trouverez toutes les ressources compilées dans le répertoire dist. Créez ensuite une archive ZIP du répertoire dist — cette archive sera utilisée pour le téléversement sur Logto Cloud ultérieurement.

Exigences pour les ressources UI personnalisées

Avant de téléverser vos ressources UI personnalisées, assurez-vous qu'elles respectent les exigences suivantes :

• Les ressources à téléverser doivent être regroupées dans un seul fichier zip.
• Le fichier zip doit contenir un fichier index.html à la racine.
• Le fichier zip ne doit pas dépasser 20 Mo.
• Le fichier zip ne doit contenir aucun fichier individuel de plus de 10 Mo.
• Le fichier zip ne doit pas contenir plus de 200 fichiers au total.

Téléversez vos ressources UI personnalisées

remarque:

Procédez avec prudence lors de l'utilisation de cette fonctionnalité en production, car elle affectera immédiatement l'expérience de connexion de vos utilisateurs.

1. Accédez à Console > Connexion & compte > Personnalisation > Apportez votre UI.
2. Cliquez pour sélectionner ou faites glisser et déposez votre fichier zip créé à l'étape précédente, le processus de téléversement démarrera automatiquement.
3. Une fois le téléversement terminé, enregistrez les modifications et votre interface personnalisée sera servie immédiatement.
4. La fenêtre "Aperçu de la connexion" sera désactivée lorsque vous utilisez votre interface de connexion personnalisée. Cependant, vous pouvez toujours cliquer sur le bouton "Aperçu en direct" pour tester votre page de connexion personnalisée dans un nouvel onglet du navigateur.

Configurer des sources CSP personnalisées

Logto applique un en-tête Content Security Policy (CSP) aux pages UI personnalisées. Si votre interface personnalisée charge des scripts tiers ou se connecte à des services externes, ajoutez les origines supplémentaires dans Console > Connexion & compte > Personnalisation > Apportez votre UI.

Vous pouvez configurer :

• script-src : Autorise les modules JavaScript ou les sources de scripts, comme les fournisseurs de CAPTCHA, d'analytique ou de gestionnaire de balises.
• connect-src : Autorise les points de terminaison réseau utilisés par fetch, XMLHttpRequest, EventSource et les connexions WebSocket.

Exemple :

{
  "scriptSrc": ["https://scripts.example.com"],
  "connectSrc": ["https://api.example.com", "wss://events.example.com"]
}

Utilisez des origines HTTPS pour les deux directives. connect-src accepte également les origines wss:// pour les connexions WebSocket. Logto ajoute ces sources à la politique de sécurité existante uniquement lorsque vos ressources UI personnalisées sont actives.

Configurer l’en-tête Cross-Origin-Opener-Policy

Par défaut, Logto n’envoie aucun en-tête Cross-Origin-Opener-Policy (COOP), de sorte qu’une application qui ouvre la page de connexion dans une popup peut continuer à communiquer avec elle via window.opener. Si vos applications ne connectent pas les utilisateurs via des popups, vous pouvez isoler votre interface de connexion personnalisée des autres fenêtres du navigateur. Choisissez une politique sous Cross-Origin-Opener-Policy dans Console > Connexion & compte > Personnalisation > Apportez votre UI :

Option	En-tête envoyé	Effet
Non défini (aucun en-tête)	Aucun	Par défaut. Toute intégration basée sur popup continue de fonctionner.
same-origin-allow-popups	Cross-Origin-Opener-Policy: same-origin-allow-popups	Coupe la fenêtre qui a ouvert la page de connexion. Les popups ouvertes par votre UI personnalisée gardent window.opener tant qu'elles restent sur d'autres sites.
same-origin	Cross-Origin-Opener-Policy: same-origin	Coupe aussi les popups ouvertes par votre UI personnalisée.

Vous pouvez également définir le champ crossOriginOpenerPolicy avec l'API Management update sign-in experience. Elle accepte unsafe-none (par défaut, aucun en-tête envoyé), same-origin-allow-popups et same-origin.

attention:

Avant de choisir une politique, vérifiez comment vos applications et votre interface personnalisée utilisent les popups :

• Les applications qui ouvrent la page de connexion dans une popup et dépendent de window.opener, par exemple pour recevoir le résultat via postMessage, cesseront de fonctionner avec l'une ou l'autre des politiques. Gardez la valeur par défaut tant que vous avez de telles applications, ou migrez-les d'abord vers un flux de connexion basé sur la redirection.
• Les popups ouvertes par votre UI personnalisée perdent window.opener dès qu'elles reviennent sur votre UI personnalisée, par exemple vers une page de callback de connexion sociale. Les popups qui restent sur un autre site et envoient leur résultat depuis là, comme la popup de connexion d'un fournisseur, continuent de fonctionner avec same-origin-allow-popups. Avec same-origin, les popups perdent window.opener dès leur ouverture.

Si vous avez besoin d'une politique, privilégiez same-origin-allow-popups plutôt que same-origin.

Logto envoie l'en-tête uniquement lorsque vos ressources UI personnalisées sont servies. Les pages de connexion intégrées, les pages /oidc/* et Account Center (/account) n'envoient jamais d'en-tête COOP, de sorte que les scanners de sécurité peuvent toujours le signaler comme manquant sur ces pages.

Développez votre interface personnalisée

Interagir avec Experience API

Votre interface personnalisée doit interagir avec l'Experience API pour effectuer diverses actions telles que la connexion, l'inscription, la réinitialisation du mot de passe, l'association de comptes sociaux, l'activation de MFA, et plus encore. Pour mieux comprendre les flux utilisateurs et les détails d'implémentation, nous vous recommandons de consulter notre RFC de conception Experience API qui fournit des spécifications techniques complètes et des exemples.

Vous devez également accéder à d'autres configurations de l'expérience de connexion, telles que les couleurs de la marque, le logo de l'entreprise, le favicon, la politique de mot de passe, les phrases localisées, voire le CSS personnalisé, via l'[endpoint Experience API de connexion] (https://openapi.logto.io/operation/operation-getsigninexperienceconfig).

Gérer le CAPTCHA lorsqu’il est activé

L'expérience de connexion intégrée de Logto gère automatiquement le CAPTCHA. Si votre tenant utilise Apportez votre UI et active la protection CAPTCHA contre les bots, votre interface personnalisée doit compléter l'intégration CAPTCHA côté frontend avant d'appeler PUT /api/experience.

Envoyez le jeton du fournisseur retourné en tant que captchaToken dans le corps de la requête PUT /api/experience. Consultez les guides spécifiques aux fournisseurs pour plus de détails :

• reCAPTCHA Enterprise avec Apportez votre UI
• Cloudflare Turnstile avec Apportez votre UI

Projets d’exemple

Nous proposons une collection de projets d'exemple pour vous aider à comprendre et à commencer rapidement à implémenter une interface personnalisée. Veuillez consulter le dépôt GitHub Logto Experience project pour plus de détails.

De plus, nous continuerons à proposer davantage de projets d'exemple simplifiés et basés sur des scénarios pour couvrir les cas d'utilisation les plus courants. Restez à l'écoute pour nos prochaines mises à jour !

Développement local et débogage

Pour le développement local et le débogage, nous fournissons l'outil Logto Tunnel CLI pour :

• Proxifier les requêtes Experience API de votre machine locale vers l'endpoint Logto Cloud.
• Tester localement la mise en œuvre de votre interface personnalisée.

Cela permet aux utilisateurs de tester et de déboguer leur interface personnalisée localement avant de la téléverser sur Logto Cloud.

Veuillez consulter Déboguer et tester votre interface personnalisée localement pour plus de détails.

Téléversez vos ressources UI personnalisées via la CLI

En plus du téléversement via la Console, vous pouvez également utiliser la CLI Logto pour téléverser vos ressources UI personnalisées. Ceci est particulièrement utile pour les workflows de déploiement automatisés.

Veuillez consulter Téléverser des ressources UI personnalisées via la CLI pour plus de détails.

Restaurer l’expérience de connexion intégrée de Logto

Si vous souhaitez restaurer l'expérience de connexion intégrée de Logto, cliquez simplement sur le bouton de suppression sur la carte Apportez votre UI. Après avoir enregistré les modifications, l'interface de connexion sera rétablie à la valeur par défaut de Logto.

Ressources associées

RFCS : Experience API

Exemples d'expérience

Apportez votre propre interface de connexion à Logto Cloud