Ajoutez l’authentification à votre application d'extension Chrome

Ce guide vous montrera comment intégrer Logto dans votre extension Chrome.

astuce

• La démonstration suivante a été testée sur Chrome v123.0.6312.87 (arm64). D'autres versions devraient également fonctionner, tant qu'elles prennent en charge les API chrome utilisées dans le SDK.
• Le projet d'exemple est disponible sur notre répertoire GitHub.

Prérequis

• Un compte Logto Cloud ou un Logto auto-hébergé.
• Une application monopage (SPA) créée dans Logto Console.
• Un projet d'extension Chrome.

Installation

npm

npm i @logto/chrome-extension

Yarn

yarn add @logto/chrome-extension

pnpm

pnpm add @logto/chrome-extension

Intégration

Le flux d'authentification

En supposant que vous ayez mis un bouton "Se connecter" dans le popup de votre extension Chrome, le flux d'authentification ressemblera à ceci :

Pour d'autres pages interactives de votre extension, vous devez simplement remplacer le participant Extension popup par le nom de la page. Dans ce tutoriel, nous nous concentrerons sur la page popup.

Concernant la connexion basée sur la redirection

1. Ce processus d'authentification (Authentication) suit le protocole OpenID Connect (OIDC), et Logto applique des mesures de sécurité strictes pour protéger la connexion utilisateur.
2. Si vous avez plusieurs applications, vous pouvez utiliser le même fournisseur d’identité (Logto). Une fois que l'utilisateur se connecte à une application, Logto complétera automatiquement le processus de connexion lorsque l'utilisateur accède à une autre application.

Pour en savoir plus sur la logique et les avantages de la connexion basée sur la redirection, consultez Expérience de connexion Logto expliquée.

Mettre à jour le manifest.json

Le SDK Logto nécessite les autorisations suivantes dans le manifest.json :

manifest.json

{
  "permissions": ["identity", "storage"],
  "host_permissions": ["https://*.logto.app/*"]
}

• permissions.identity: Requis pour l'API Chrome Identity, utilisée pour se connecter et se déconnecter.
• permissions.storage: Requis pour stocker la session de l'utilisateur.
• host_permissions: Requis pour que le SDK Logto communique avec les APIs Logto.

remarque

Si vous utilisez un domaine personnalisé sur Logto Cloud, vous devez mettre à jour le host_permissions pour correspondre à votre domaine.

Configurer un script d'arrière-plan (service worker)

Dans le script d'arrière-plan de votre extension Chrome, initialisez le SDK Logto :

service-worker.js

import LogtoClient from '@logto/chrome-extension';

export const logtoClient = new LogtoClient({
  endpoint: '<your-logto-endpoint>'
  appId: '<your-logto-app-id>',
});

Remplacez <your-logto-endpoint> et <your-logto-app-id> par les valeurs réelles. Vous pouvez trouver ces valeurs sur la page de l'application que vous venez de créer dans la Logto Console.

Si vous n'avez pas de script d'arrière-plan, vous pouvez suivre le guide officiel pour en créer un.

info

Pourquoi avons-nous besoin d'un script d'arrière-plan ?

Les pages d'extension normales comme le popup ou la page d'options ne peuvent pas s'exécuter en arrière-plan et peuvent être fermées pendant le processus d'authentification. Un script d'arrière-plan garantit que le processus d'authentification peut être correctement géré.

Ensuite, nous devons écouter le message des autres pages d'extension et gérer le processus d'authentification :

service-worker.js

chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  // Dans le code ci-dessous, puisque nous retournons `true` pour chaque action, nous devons appeler `sendResponse`
  // pour notifier l'expéditeur. Vous pouvez également gérer les erreurs ici, ou utiliser d'autres moyens pour notifier l'expéditeur.

  if (message.action === 'signIn') {
    const redirectUri = chrome.identity.getRedirectURL('/callback');
    logtoClient.signIn(redirectUri).finally(sendResponse);
    return true;
  }

  if (message.action === 'signOut') {
    const redirectUri = chrome.identity.getRedirectURL();
    logtoClient.signOut(redirectUri).finally(sendResponse);
    return true;
  }

  return false;
});

Vous remarquerez peut-être qu'il y a deux URI de redirection utilisées dans le code ci-dessus. Elles sont toutes deux créées par chrome.identity.getRedirectURL, qui est une API Chrome intégrée pour générer une URL de redirection pour les flux d'authentification. Les deux URI seront :

• https://<extension-id>.chromiumapp.org/callback pour la connexion.
• https://<extension-id>.chromiumapp.org/ pour la déconnexion.

Notez que ces URI ne sont pas accessibles et sont uniquement utilisées pour que Chrome déclenche des actions spécifiques pour le processus d'authentification.

Mettre à jour les paramètres de l'application Logto

Nous devons maintenant mettre à jour les paramètres de l'application Logto pour autoriser les URI de redirection que nous venons de créer.

1. Allez sur la page de l'application dans la Logto Console.
2. Dans la section "Redirect URIs", ajoutez l'URI : https://<extension-id>.chromiumapp.org/callback.
3. Dans la section "Post sign-out redirect URIs", ajoutez l'URI : https://<extension-id>.chromiumapp.org/.
4. Dans la section "CORS allowed origins", ajoutez l'URI : chrome-extension://<extension-id>. Le SDK dans l'extension Chrome utilisera cette origine pour communiquer avec les APIs Logto.
5. Cliquez sur Enregistrer les modifications.

N'oubliez pas de remplacer <extension-id> par votre ID d'extension réel. Vous pouvez trouver l'ID de l'extension sur la page chrome://extensions.

Ajouter des boutons de connexion et de déconnexion au popup

Nous y sommes presque ! Ajoutons les boutons de connexion et de déconnexion et d'autres logiques nécessaires à la page popup.

Dans le fichier popup.html :

popup.html

<button id="sign-in">Se connecter</button> <button id="sign-out">Se déconnecter</button>

Dans le fichier popup.js (en supposant que popup.js est inclus dans le popup.html) :

popup.js

document.getElementById('sign-in').addEventListener('click', async () => {
  await chrome.runtime.sendMessage({ action: 'signIn' });
  // Connexion terminée (ou échouée), vous pouvez mettre à jour l'interface utilisateur ici.
});

document.getElementById('sign-out').addEventListener('click', async () => {
  await chrome.runtime.sendMessage({ action: 'signOut' });
  // Déconnexion terminée (ou échouée), vous pouvez mettre à jour l'interface utilisateur ici.
});

Point de contrôle : Tester le flux d'authentification

Vous pouvez maintenant tester le flux d'authentification dans votre extension Chrome :

1. Ouvrez le popup de l'extension.
2. Cliquez sur le bouton "Se connecter".
3. Vous serez redirigé vers la page de connexion Logto.
4. Connectez-vous avec votre compte Logto.
5. Vous serez redirigé vers Chrome.

Vérifier l'état d'authentification

Puisque Chrome fournit des APIs de stockage unifiées, plutôt que le flux de connexion et de déconnexion, toutes les autres méthodes du SDK Logto peuvent être utilisées directement dans la page popup.

Dans votre popup.js, vous pouvez réutiliser l'instance LogtoClient créée dans le script d'arrière-plan, ou en créer une nouvelle avec la même configuration :

popup.js

import LogtoClient from '@logto/chrome-extension';

const logtoClient = new LogtoClient({
  endpoint: '<your-logto-endpoint>'
  appId: '<your-logto-app-id>',
});

// Ou réutiliser l'instance logtoClient créée dans le script d'arrière-plan
import { logtoClient } from './service-worker.js';

Ensuite, vous pouvez créer une fonction pour charger l'état d'authentification et le profil de l'utilisateur :

popup.js

const loadAuthenticationState = async () => {
  const isAuthenticated = await logtoClient.isAuthenticated();
  // Mettez à jour l'interface utilisateur en fonction de l'état d'authentification

  if (isAuthenticated) {
    const user = await logtoClient.getIdTokenClaims(); // { sub: '...', email: '...', ... }
    // Mettez à jour l'interface utilisateur avec le profil de l'utilisateur
  }
};

Vous pouvez également combiner la fonction loadAuthenticationState avec la logique de connexion et de déconnexion :

popup.js

document.getElementById('sign-in').addEventListener('click', async () => {
  await chrome.runtime.sendMessage({ action: 'signIn' });
  await loadAuthenticationState();
});

document.getElementById('sign-out').addEventListener('click', async () => {
  await chrome.runtime.sendMessage({ action: 'signOut' });
  await loadAuthenticationState();
});

Voici un exemple de la page popup avec l'état d'authentification :

Autres considérations

• Bundling du service worker : Si vous utilisez un bundler comme Webpack ou Rollup, vous devez explicitement définir la cible sur browser ou similaire pour éviter le bundling inutile des modules Node.js.
• Résolution des modules : Le SDK Logto pour les extensions Chrome est un module uniquement ESM.

Consultez notre projet d'exemple pour un exemple complet avec TypeScript, Rollup et d'autres configurations.

Obtenir des informations sur l'utilisateur

Afficher les informations de l'utilisateur

Pour afficher les informations de l'utilisateur, vous pouvez utiliser la méthode logtoClient.getIdTokenClaims(). Par exemple, sur votre page d'accueil :

Home.js

const userInfo = await logtoClient.getIdTokenClaims();

// Générer un tableau d'affichage pour les revendications du jeton d’identifiant
const table = document.createElement('table');
const thead = document.createElement('thead');
const tr = document.createElement('tr');
const thName = document.createElement('th');
const thValue = document.createElement('th');
thName.innerHTML = 'Nom';
thValue.innerHTML = 'Valeur';
tr.append(thName, thValue);
thead.append(tr);
table.append(thead);

const tbody = document.createElement('tbody');

for (const [key, value] of Object.entries(userInfo)) {
  const tr = document.createElement('tr');
  const tdName = document.createElement('td');
  const tdValue = document.createElement('td');
  tdName.innerHTML = key;
  tdValue.innerHTML = typeof value === 'string' ? value : JSON.stringify(value);
  tr.append(tdName, tdValue);
  tbody.append(tr);
}

table.append(tbody);

Demander des revendications supplémentaires

Il se peut que certaines informations utilisateur soient manquantes dans l'objet retourné par getIdTokenClaims(). Cela est dû au fait que OAuth 2.0 et OpenID Connect (OIDC) sont conçus pour suivre le principe du moindre privilège (PoLP), et Logto est construit sur ces normes.

Par défaut, des revendications limitées sont retournées. Si vous avez besoin de plus d'informations, vous pouvez demander des portées supplémentaires pour accéder à plus de revendications.

info

Une "revendication" est une assertion faite à propos d'un sujet ; une "portée" est un groupe de revendications. Dans le cas actuel, une revendication est une information sur l'utilisateur.

Voici un exemple non normatif de la relation portée - revendication :

astuce

La revendication "sub" signifie "sujet", qui est l'identifiant unique de l'utilisateur (c'est-à-dire l'ID utilisateur).

Le SDK Logto demandera toujours trois portées : openid, profile et offline_access.

Pour demander des portées supplémentaires, vous pouvez configurer les configurations Logto :

index.js

import LogtoClient, { UserScope } from '@logto/browser';

const logtoClient = new LogtoClient({
  appId: '<your-application-id>',
  endpoint: '<your-logto-endpoint>',
  scopes: [UserScope.Email, UserScope.Phone],
});

Ensuite, vous pouvez accéder aux revendications supplémentaires dans la valeur de retour de logtoClient.getIdTokenClaims() :

const claims = await getIdTokenClaims();
// Vous pouvez maintenant accéder aux revendications supplémentaires `claims.email`, `claims.phone`, etc.

Revendications nécessitant des requêtes réseau

Pour éviter de surcharger le jeton d’identifiant (ID token), certaines revendications nécessitent des requêtes réseau pour être récupérées. Par exemple, la revendication custom_data n'est pas incluse dans l'objet utilisateur même si elle est demandée dans les portées. Pour accéder à ces revendications, vous pouvez utiliser la méthode logtoClient.fetchUserInfo() :

const userInfo = await logtoClient.fetchUserInfo();
// Vous pouvez maintenant accéder à la revendication `userInfo.custom_data`

Cette méthode récupérera les informations de l'utilisateur en faisant une requête à l' point de terminaison userinfo. Pour en savoir plus sur les portées et revendications disponibles, consultez la section Portées et revendications.

Portées et revendications

Logto utilise les conventions de portées et revendications OIDC pour définir les Portées et Revendications pour récupérer les informations utilisateur à partir du Jeton d’identifiant et du point de terminaison OIDC userinfo. Les termes "Portée" et "Revendication" proviennent des spécifications OAuth 2.0 et OpenID Connect (OIDC).

Voici la liste des Portées (Scopes) prises en charge et les Revendications (Claims) correspondantes :

openid

Nom de la revendication	Type	Description	Besoin d'userinfo ?
sub	string	L'identifiant unique de l'utilisateur	Non

profile

Nom de la revendication	Type	Description	Besoin d'userinfo ?
name	string	Le nom complet de l'utilisateur	Non
username	string	Le nom d'utilisateur de l'utilisateur	Non
picture	string	URL de la photo de profil de l'utilisateur final. Cette URL DOIT faire référence à un fichier image (par exemple, un fichier image PNG, JPEG ou GIF), plutôt qu'à une page Web contenant une image. Notez que cette URL DOIT spécifiquement référencer une photo de profil de l'utilisateur final adaptée à l'affichage lors de la description de l'utilisateur final, plutôt qu'une photo arbitraire prise par l'utilisateur final.	Non
created_at	number	Heure à laquelle l'utilisateur final a été créé. Le temps est représenté comme le nombre de millisecondes depuis l'époque Unix (1970-01-01T00:00:00Z).	Non
updated_at	number	Heure à laquelle les informations de l'utilisateur final ont été mises à jour pour la dernière fois. Le temps est représenté comme le nombre de millisecondes depuis l'époque Unix (1970-01-01T00:00:00Z).	Non

D'autres revendications standard incluent family_name, given_name, middle_name, nickname, preferred_username, profile, website, gender, birthdate, zoneinfo, et locale seront également incluses dans la portée profile sans avoir besoin de demander le point de terminaison userinfo. Une différence par rapport aux revendications ci-dessus est que ces revendications ne seront renvoyées que lorsque leurs valeurs ne sont pas vides, tandis que les revendications ci-dessus renverront null si les valeurs sont vides.

remarque

Contrairement aux revendications standard, les revendications created_at et updated_at utilisent des millisecondes au lieu de secondes.

email

Nom de la revendication	Type	Description	Besoin d'userinfo ?
email	string	L'adresse e-mail de l'utilisateur	Non
email_verified	boolean	Si l'adresse e-mail a été vérifiée	Non

phone

Nom de la revendication	Type	Description	Besoin d'userinfo ?
phone_number	string	Le numéro de téléphone de l'utilisateur	Non
phone_number_verified	boolean	Si le numéro de téléphone a été vérifié	Non

address

Veuillez vous référer à OpenID Connect Core 1.0 pour les détails de la revendication d'adresse.

custom_data

Nom de la revendication	Type	Description	Besoin d'userinfo ?
custom_data	object	Les données personnalisées de l'utilisateur	Oui

identities

Nom de la revendication	Type	Description	Besoin d'userinfo ?
identities	object	Les identités liées de l'utilisateur	Oui
sso_identities	array	Les identités SSO liées de l'utilisateur	Oui

urn:logto:scope:organizations

Nom de la revendication	Type	Description	Besoin d'userinfo ?
organizations	string[]	Les identifiants d'organisation auxquels l'utilisateur appartient	Non
organization_data	object[]	Les données d'organisation auxquelles l'utilisateur appartient	Oui

urn:logto:scope:organization_roles

Nom de la revendication	Type	Description	Besoin d'userinfo ?
organization_roles	string[]	Les rôles d'organisation auxquels l'utilisateur appartient avec le format <organization_id>:<role_name>	Non

---

En considérant la performance et la taille des données, si "Besoin d'userinfo ?" est "Oui", cela signifie que la revendication n'apparaîtra pas dans le Jeton d’identifiant (ID token), mais sera renvoyée dans la réponse du point de terminaison userinfo.

Ressources API

Nous vous recommandons de lire d'abord 🔐 Contrôle d’accès basé sur les rôles (RBAC) pour comprendre les concepts de base de Logto RBAC et comment configurer correctement les ressources API.

Configurer le client Logto

Une fois que vous avez configuré les ressources API, vous pouvez les ajouter lors de la configuration de Logto dans votre application :

index.js

import LogtoClient from '@logto/browser';

const logtoClient = new LogtoClient({
  // ...other configs
  resources: ['https://shopping.your-app.com/api', 'https://store.your-app.com/api'], // Ajouter des ressources API
});

Chaque ressource API a ses propres permissions (portées).

Par exemple, la ressource https://shopping.your-app.com/api a les permissions shopping:read et shopping:write, et la ressource https://store.your-app.com/api a les permissions store:read et store:write.

Pour demander ces permissions, vous pouvez les ajouter lors de la configuration de Logto dans votre application :

index.js

import LogtoClient from '@logto/chrome-extension';

const logtoClient = new LogtoClient({
// ...other configs
portées: ['shopping:read', 'shopping:write', 'store:read', 'store:write'],
ressources: ['https://shopping.your-app.com/api', 'https://store.your-app.com/api'], // Ajouter des ressources API
});

Vous pouvez remarquer que les portées sont définies séparément des ressources API. Cela est dû au fait que les Indicateurs de ressource pour OAuth 2.0 spécifient que les portées finales pour la requête seront le produit cartésien de toutes les portées de tous les services cibles.

Ainsi, dans le cas ci-dessus, les portées peuvent être simplifiées à partir de la définition dans Logto, les deux ressources API peuvent avoir les portées read et write sans le préfixe. Ensuite, dans la configuration de Logto :

index.js

import LogtoClient, { UserScope } from '@logto/chrome-extension';

const logtoClient = new LogtoClient({
// ...other configs
scopes: ['read', 'write'],
resources: ['https://shopping.your-app.com/api', 'https://store.your-app.com/api'],
});

Pour chaque ressource API, il demandera à la fois les portées read et write.

remarque

Il est acceptable de demander des portées qui ne sont pas définies dans les ressources API. Par exemple, vous pouvez demander la portée email même si les ressources API n'ont pas la portée email disponible. Les portées non disponibles seront ignorées en toute sécurité.

Après une connexion réussie, Logto émettra les portées appropriées aux ressources API en fonction des rôles de l'utilisateur.

Récupérer le jeton d’accès pour la ressource API

Pour récupérer le jeton d’accès pour une ressource API spécifique, vous pouvez utiliser la méthode getAccessToken :

const accessToken = await logtoClient.getAccessToken('https://store.your-app.com/api');
console.log('Jeton d’accès', accessToken);

Cette méthode renverra un jeton d’accès JWT qui peut être utilisé pour accéder à la ressource API lorsque l’utilisateur a les Permissions associées. Si le jeton d’accès mis en cache actuel a expiré, cette méthode essaiera automatiquement d’utiliser un jeton de rafraîchissement pour obtenir un nouveau jeton d’accès.

Récupérer les jetons d’organisation

Si l'Organisation est nouvelle pour vous, veuillez lire 🏢 Organisations (Multi-tenancy) pour commencer.

Vous devez ajouter la portée UserScope.Organizations lors de la configuration du client Logto :

index.js

import LogtoClient, { UserScope } from '@logto/chrome-extension';

const logtoClient = new LogtoClient({
// ...other configs
scopes: [UserScope.Organisations],
});

Une fois l'utilisateur connecté, vous pouvez récupérer le jeton d’organisation pour l'utilisateur :

index.js

// Obtenez les organizationIds à partir des userInfo

const claims = await logtoClient.getIdTokenClaims();
const organizationIds = claims.organizations;

/**
 * Ou à partir des revendications du jeton d’identifiant
 *
 * const claims = await logtoClient.getIdTokenClaims();
 * const organizationIds = claims.organizations;
 */

// Obtenez le jeton d’accès de l’organisation
if (organizationIds.length > 0) {
  const organizationId = organizationIds[0];
  const organizationAccessToken = await logtoClient.getOrganizationToken(organizationId);
  console.log('Jeton d’accès de l’organisation', organizationAccessToken);
}

./code/_scopes-and-claims-code.mdx./code/_config-organization-code.mdx

Attacher le jeton d’accès aux en-têtes de requête

Placez le jeton dans le champ Authorization des en-têtes HTTP avec le format Bearer (Bearer YOUR_TOKEN), et vous êtes prêt à partir.

remarque

Le flux d'intégration du jeton Bearer peut varier en fonction du framework ou du demandeur que vous utilisez. Choisissez votre propre méthode pour appliquer l'en-tête de requête Authorization.

Lectures complémentaires

Flux utilisateur final : flux d'authentification, flux de compte et flux d'organisation Configurer les connecteurs Protéger votre API