Implémenter une solution d'identité avec FedCM côté tiers de confiance

Les parties de confiance doivent suivre les étapes suivantes pour activer FedCM sur leur site :

• Assurez-vous que les points de terminaison FedCM sont autorisés sur le site du RP.
• Utilisez l'API JavaScript FedCM pour lancer l'authentification de l'utilisateur.
• Fournissez leurs métadonnées (comme les URL des règles de confidentialité et des conditions d'utilisation) à l'IdP (ou à plusieurs IdP à partir de Chrome 136).
• [facultatif] Personnalisez l'expérience utilisateur en choisissant un mode UX, en fournissant des indices de connexion ou de domaine, en transmettant des paramètres personnalisés, en demandant des informations utilisateur spécifiques, en fournissant un message d'erreur personnalisé ou en choisissant comment réauthentifier les utilisateurs.

Appeler l'API FedCM sur la partie de confiance

Une fois la configuration de l'IdP et les points de terminaison disponibles, les RP peuvent appeler navigator.credentials.get() pour demander à autoriser un utilisateur à se connecter au RP avec l'IdP.

Avant d'appeler l'API, vous devez confirmer que FedCM est disponible sur le navigateur de l'utilisateur. Pour vérifier si FedCM est disponible, entourez votre implémentation FedCM avec ce code :

  if ('IdentityCredential' in window) {
    // If the feature is available, take action
  } else {
    // FedCM is not supported, use a different identity solution
  }

Pour permettre à un utilisateur de se connecter à l'IdP sur une RP à l'aide de FedCM, la RP peut appeler navigator.credentials.get(). À partir de Chrome 136, le RP peut prendre en charge plusieurs IdP en spécifiant un tableau de plusieurs fournisseurs d'identité dans un seul appel navigator.credentials.get(), par exemple :

  const credential = await navigator.credentials.get({
      identity: {
        // Specify the IdP (or multiple IdPs, supported from Chrome 136) this Relying Party supports
        providers: [
        {
              configURL: 'https://accounts.idp-1.example/config.json',
              clientId: '********'
        },
        {
          configURL: 'https://accounts.idp-2.example/config.json',
          clientId: '********'
        }]
      }
    },
  );
  const { token } = credential;
  
  // Get the current IdP's configURL to identify which provider the user is signed in with
  const currentIdpConfigUrl = credential.configURL;
  if (currentIdpConfigUrl === 'https://idp1.example/foo.json') {
    // handle the case where the user signed in with idp1
  } else if (currentIdpConfigUrl === 'https://idp2.example/bar.json') {
    // handle the case where the user signed in with idp2
    }

Essayez la fonctionnalité de plusieurs IdP en vous connectant avec IdP1 et IdP2.

Propriété de contexte

Avec la propriété context facultative, le RP peut modifier la chaîne dans l'UI de la boîte de dialogue FedCM (par exemple, "Se connecter à rp.example…", "Utiliser idp.example…") pour s'adapter aux contextes d'authentification prédéfinis, par exemple. La propriété context peut avoir les valeurs suivantes :

• signin (par défaut)
• signup
• use

Par exemple, si vous définissez context sur use, le message suivant s'affiche :

Le navigateur gère différemment les cas d'utilisation d'inscription et de connexion selon l'existence de approved_clients dans la réponse de l'endpoint de la liste des comptes. Le navigateur n'affichera pas le texte d'information Pour continuer avec… si l'utilisateur s'est déjà inscrit au programme de récompenses.
La propriété providers accepte un tableau d'objets IdentityProvider qui possèdent les propriétés suivantes :

Propriété "providers"

La propriété providers accepte un tableau d'objets IdentityProvider comportant les propriétés suivantes :

Mode Actif

FedCM est compatible avec différentes configurations de mode UX. Le mode passif est le mode par défaut. Les développeurs n'ont pas besoin de le configurer.

Pour utiliser FedCM en mode actif :

1. Vérifiez la disponibilité de la fonctionnalité dans le navigateur de l'utilisateur.
2. Appelez l'API avec un geste utilisateur éphémère, tel qu'un clic sur un bouton.
3. Transmettez le paramètre mode à l'appel d'API :

  let supportsFedCmMode = false;
  try {
    navigator.credentials.get({
      identity: Object.defineProperty(
        // Check if this Chrome version supports the Mode API.
        {}, 'mode', {
          get: function () { supportsFedCmMode = true; }
        }
      )
    });
  } catch(e) {}

  if (supportsFedCmMode) {
    // The button mode is supported. Call the API with mode property:
    return await navigator.credentials.get({
      identity: {
        providers: [{
          configURL: 'https://idp.example/config.json',
          clientId: '123',
        }],
        // The 'mode' value defines the UX mode of FedCM.
        // - 'active': Must be initiated by user interaction (e.g., clicking a button).
        // - 'passive': Can be initiated without direct user interaction.
        mode: 'active'
      }
    });
  }

Essayez le mode actif avec cette démonstration.

Icône personnalisée en mode actif

Le mode actif permet aux IdP d'inclure l'icône du logo officiel du RP directement dans la réponse du point de terminaison des métadonnées du client. Le RP doit fournir ses données de branding à l'avance.

Appeler FedCM depuis un iFrame d'origine différente

FedCM peut être appelé depuis un iFrame d'origine croisée à l'aide d'une règle d'autorisation identity-credentials-get, si le frame parent le permet. Pour ce faire, ajoutez l'attribut allow="identity-credentials-get" au tag iframe comme suit :

  <iframe src="https://fedcm-cross-origin-iframe.glitch.me" allow="identity-credentials-get"></iframe>

Vous pouvez voir un exemple.

Si le frame parent souhaite limiter les origines pour appeler FedCM, envoyez un en-tête Permissions-Policy avec une liste des origines autorisées.

  Permissions-Policy: identity-credentials-get=(self "https://fedcm-cross-origin-iframe.glitch.me")

Pour en savoir plus sur le fonctionnement de la règle relative aux autorisations, consultez Contrôler les fonctionnalités du navigateur avec la règle relative aux autorisations.

API Login Hint

À l'aide de l'indice de connexion, le RP peut recommander le compte avec lequel un utilisateur doit se connecter. Cela peut être utile pour réauthentifier les utilisateurs qui ne sont pas sûrs du compte qu'ils ont utilisé auparavant.

Les RP peuvent afficher sélectivement un compte spécifique en appelant navigator.credentials.get() avec la propriété loginHint et l'une des valeurs login_hints extraites du point de terminaison de la liste des comptes, comme indiqué dans l'exemple de code suivant :

  return await navigator.credentials.get({
    identity: {
      providers: [{
        configURL: 'https://idp.example/manifest.json',
        clientId: '123',
        // Accounts endpoint can specify a 'login_hints' array for an account.
        // When RP specifies a 'exampleHint' value, only those accounts will be
        // shown to the user whose 'login_hints' array contains the 'exampleHint'
        // value
        loginHint : 'exampleHint'
      }]
    }
  });

Lorsqu'aucun compte ne correspond à loginHint, la boîte de dialogue FedCM affiche une invite de connexion, qui permet à l'utilisateur de se connecter à un compte IdP correspondant à l'indice demandé par le RP. Lorsque l'utilisateur appuie sur l'invite, une fenêtre pop-up s'ouvre avec l'URL de connexion spécifiée dans le fichier de configuration. Le lien est ensuite complété par les paramètres de requête d'indice de connexion et d'indice de domaine.

API Domain Hint

Les RP peuvent choisir de n'afficher que les comptes associés à un certain domaine. Cela peut être utile pour les RP dont l'accès est limité à un domaine d'entreprise.

Pour n'afficher que des comptes de domaine spécifiques, le RP doit appeler navigator.credentials.get() avec la propriété domainHint et l'une des valeurs domain_hints extraites du point de terminaison de la liste des comptes, comme indiqué dans l'exemple de code suivant :

  return await navigator.credentials.get({
    identity: {
      providers: [{
        configURL: 'https://idp.example/manifest.json',
        clientId: 'abc',
        // Accounts endpoint can specify a 'domain_hints' array for an account.
        // When RP specifies a '@domain.example' value, only those accounts will be
        // shown to the user whose 'domain_hints' array contains the
        // '@domain.example' value
        domainHint : '@domain.example'
      }]
    }
  });

Lorsqu'aucun compte ne correspond à domainHint, la boîte de dialogue FedCM affiche une invite de connexion, qui permet à l'utilisateur de se connecter à un compte IdP correspondant à l'indice demandé par le RP. Lorsque l'utilisateur appuie sur l'invite, une fenêtre pop-up s'ouvre avec l'URL de connexion spécifiée dans le fichier de configuration. Le lien est ensuite complété par les paramètres de requête d'indice de connexion et d'indice de domaine.

Pour en savoir plus, consultez la démonstration.

Paramètres personnalisés

La fonctionnalité Paramètres personnalisés permet au RP de fournir des paramètres clé-valeur supplémentaires au point de terminaison d'assertion d'identité. L'API Parameters permet aux RP de transmettre des paramètres supplémentaires au fournisseur d'identité pour demander des autorisations pour des ressources allant au-delà de la connexion de base. Transmettre des paramètres supplémentaires peut être utile dans les scénarios suivants :

• Le RP doit demander dynamiquement les autorisations supplémentaires dont dispose l'IdP, telles que l'adresse de facturation ou l'accès à l'agenda. L'utilisateur peut autoriser ces autorisations via un flux UX contrôlé par le fournisseur d'identité, lancé à l'aide de la fonctionnalité Continuer sur. Le fournisseur d'identité partage ensuite ces informations.

Pour utiliser l'API, le RP ajoute des paramètres à la propriété params en tant qu'objet dans l'appel navigator.credentials.get() :

  let {token} = await navigator.credentials.get({
    identity: {
      providers: [{
        clientId: '1234',
        configURL: 'https://idp.example/fedcm.json',
        // Key/value pairs that need to be passed from the
        // RP to the IdP but that don't really play any role with
        // the browser.
        params: {
          IDP_SPECIFIC_PARAM: '1',
          foo: 'BAR'
        }
      },
    }
  });

Le navigateur le traduira automatiquement en requête POST à l'IdP avec des paramètres sous la forme d'un seul objet JSON sérialisé et encodé au format URL :

  // The assertion endpoint is drawn from the config file
  POST /fedcm_assertion_endpoint HTTP/1.1
  Host: idp.example
  Origin: https://rp.example/
  Content-Type: application/x-www-form-urlencoded
  Cookie: 0x23223
  Sec-Fetch-Dest: webidentity

  // params are translated into urlencoded version of `{"IDP_SPECIFIC_PARAM":"1","foo":"bar"}`
  account_id=123&client_id=client1234&params=%22%7B%5C%22IDP_SPECIFIC_PARAM%5C%22%3A1%2C%5C%22foo%5C%22%3A%5C%22BAR%5C%22%7D%22.

Si le RP a besoin d'autorisations supplémentaires, l'IdP peut fournir un lien de redirection. Par exemple, dans node.js :

  if (rpRequestsPermissions) {
    // Response with a URL if the RP requests additional permissions
    return res.json({
      continue_on: '/example-redirect',
    });
  }

Champs

Le RP peut spécifier les informations utilisateur dont il a besoin que l'IdP partage avec lui. Il peut s'agir d'une combinaison de nom, d'adresse e-mail, de nom d'utilisateur, de numéro de téléphone et de photo de profil. Les informations demandées seront incluses dans l'UI de divulgation de la boîte de dialogue FedCM.

Les utilisateurs qui s'inscrivent verront un message les informant que idp.example partagera les informations demandées avec rp.example s'ils choisissent de s'inscrire. Si la réponse du point de terminaison des comptes n'inclut pas un champ demandé par le RP, le texte d'information ne l'inclura pas. Le fournisseur d'identité apprendra tous les champs demandés à partir du point de terminaison d'assertion d'identité et décidera s'il doit recueillir d'autres autorisations de l'utilisateur pour continuer.

Pour utiliser la fonctionnalité "Champs", le RP doit ajouter un tableau fields dans l'appel navigator.credentials.get(). Les champs peuvent contenir des propriétés telles que name, email, tel, username ou picture. Cette liste pourra être étendue à l'avenir. Une requête avec fields se présente comme suit :

   let { token } = await navigator.credentials.get({
    identity: {
      providers: [{
        // RP requests the IdP to share only username and profile picture
        fields: [ 'username', 'picture'],
        clientId: '1234',
        configURL: 'https://idp.example/fedcm.json',
      },
    }
  });

Le navigateur le traduira automatiquement en requête HTTP au point de terminaison d'assertion d'identité, qui inclut le paramètre fields spécifié par le RP, avec les champs que le navigateur a divulgués à l'utilisateur dans un paramètre disclosure_shown_for. Pour assurer la rétrocompatibilité, le navigateur enverra également disclosure_text_shown=true si le texte de divulgation a été affiché et que les champs demandés incluent les trois champs : 'name', 'email' et 'picture'. À partir de Chrome 141, la valeur de disclosure_text_shown n'indique pas si le texte de divulgation a réellement été affiché à l'utilisateur.

  POST /id_assertion_endpoint HTTP/1.1
  Host: idp.example
  Origin: https://rp.example/
  Content-Type: application/x-www-form-urlencoded
  Cookie: 0x23223
  Sec-Fetch-Dest: webidentity

  // The RP only requested to share email and picture. The browser will send `disclosure_text_shown=false`, as the 'name' field value is missing
  account_id=123&client_id=client1234&disclosure_text_shown=false&fields=email,picture&disclosure_shown_for=email,picture

Si fields est un tableau vide, l'agent utilisateur ignore l'UI de divulgation.

C'est le cas même si la réponse du point de terminaison des comptes ne contient pas d'ID client correspondant au RP dans approved_clients.

Dans ce cas, la valeur disclosure_text_shown envoyée au point de terminaison d'assertion d'identité est "false" dans le corps HTTP :

  POST /id_assertion_endpoint HTTP/1.1
  Host: idp.example
  Origin: https://rp.example/
  Content-Type: application/x-www-form-urlencoded
  Cookie: 0x23223
  Sec-Fetch-Dest: webidentity

  account_id=123&client_id=client1234&nonce=234234&disclosure_text_shown=false

Afficher un message d'erreur

Il peut arriver que le fournisseur d'identité ne puisse pas émettre de jeton pour des raisons légitimes, par exemple lorsque le client n'est pas autorisé ou que le serveur est temporairement indisponible. Si l'IdP renvoie une réponse "error", le RP peut l'intercepter et Chrome peut en informer l'utilisateur en affichant l'interface utilisateur du navigateur avec les informations d'erreur fournies par l'IdP.

  try {
    const cred = await navigator.credentials.get({
      identity: {
        providers: [
          {
            configURL: 'https://idp.example/manifest.json',
            clientId: '1234',
          },
        ],
      }
    });
  } catch (e) {
    const code = e.code;
    const url = e.url;
  }

Réauthentifier automatiquement les utilisateurs après l'authentification initiale

La réauthentification automatique FedCM (ou "réauthentification automatique" en abrégé) permet aux utilisateurs de se réauthentifier automatiquement. Les conditions suivantes doivent être remplies pour que l'utilisateur soit réauthentifié automatiquement :

• L'utilisateur a déjà effectué l'authentification initiale à l'aide de FedCM. Dans ce contexte, "l'authentification initiale" signifie que l'utilisateur crée un compte ou se connecte au site Web du RP en appuyant sur le bouton Continuer en tant que… dans la boîte de dialogue de connexion FedCM pour la première fois sur la même instance de navigateur.
• L'utilisateur ne dispose que d'un seul compte de retour. Si des comptes existants sont associés à plusieurs IdP, l'utilisateur ne sera pas automatiquement réauthentifié.

Bien que l'expérience utilisateur explicite soit logique avant que l'utilisateur n'ait créé le compte fédéré pour empêcher le suivi (qui est l'un des principaux objectifs de FedCM), elle est inutilement fastidieuse une fois que l'utilisateur l'a effectuée une fois : une fois que l'utilisateur a accordé l'autorisation de communication entre le RP et l'IdP, il n'y a aucun avantage en termes de confidentialité ou de sécurité à imposer une autre confirmation explicite de l'utilisateur pour quelque chose qu'il a déjà reconnu.

Avec la réauthentification automatique, le navigateur modifie son comportement en fonction de l'option que vous spécifiez pour mediation lorsque vous appelez navigator.credentials.get().

  const cred = await navigator.credentials.get({
    identity: {
      providers: [{
        configURL: 'https://idp.example/fedcm.json',
        clientId: '1234',
      }],
    },
    mediation: 'optional', // this is the default
  });

  // `isAutoSelected` is `true` if auto-reauthn was performed.
  const isAutoSelected = cred.isAutoSelected;

mediation est une propriété de l'API Credential Management. Son comportement est identique à celui de PasswordCredential et FederatedCredential. Il est également partiellement compatible avec PublicKeyCredential. La propriété accepte les quatre valeurs suivantes :

• 'optional'(par défaut) : réauthentification automatique si possible, nécessite une médiation dans le cas contraire. Nous vous recommandons de choisir cette option sur la page de connexion.
• 'required' : nécessite toujours une médiation pour continuer, par exemple en cliquant sur le bouton "Continuer" dans l'UI. Sélectionnez cette option si vos utilisateurs doivent accorder explicitement l'autorisation chaque fois qu'ils doivent s'authentifier.
• 'silent' : réauthentification automatique si possible, échec silencieux sans nécessiter de médiation si ce n'est pas possible. Nous vous recommandons de choisir cette option sur les pages autres que la page de connexion dédiée, mais sur lesquelles vous souhaitez que les utilisateurs restent connectés. Par exemple, une page d'article sur un site Web d'actualités ou une page d'article sur un site Web de livraison.
• 'conditional' : utilisé pour WebAuthn et non disponible pour FedCM pour le moment.

Avec cet appel, la réauthentification automatique se produit dans les conditions suivantes :

• FedCM est disponible. Par exemple, l'utilisateur n'a pas désactivé FedCM, que ce soit de manière globale ou pour le RP dans les paramètres.
• L'utilisateur n'a utilisé qu'un seul compte avec l'API FedCM pour se connecter au site Web sur ce navigateur.
• L'utilisateur est connecté au fournisseur d'identité avec ce compte.
• L'authentification automatique n'a pas eu lieu au cours des 10 dernières minutes.
• Le RP n'a pas appelé navigator.credentials.preventSilentAccess() après la connexion précédente.

Lorsque ces conditions sont remplies, une tentative de réauthentification automatique de l'utilisateur démarre dès que l'navigator.credentials.get() FedCM est appelé.

Lorsque mediation: optional, la réauthentification automatique peut être indisponible pour des raisons que seul le navigateur connaît. Le RP peut vérifier si la réauthentification automatique est effectuée en examinant la propriété isAutoSelected.

Cela permet d'évaluer les performances de l'API et d'améliorer l'UX en conséquence. De plus, lorsqu'il n'est pas disponible, l'utilisateur peut être invité à se connecter avec une médiation explicite de l'utilisateur, qui est un flux avec mediation: required.

Appliquer la médiation avec preventSilentAccess()

La réauthentification automatique des utilisateurs immédiatement après leur déconnexion n'offrirait pas une expérience utilisateur très agréable. C'est pourquoi FedCM prévoit une période de silence de 10 minutes après une réauthentification automatique pour éviter ce comportement. Cela signifie que la réauthentification automatique se produit au maximum une fois toutes les 10 minutes, sauf si l'utilisateur se reconnecte dans les 10 minutes. Le RP doit appeler navigator.credentials.preventSilentAccess() pour demander explicitement au navigateur de désactiver la réauthentification automatique lorsqu'un utilisateur se déconnecte explicitement du RP, par exemple en cliquant sur un bouton de déconnexion.

  function signout() {
    navigator.credentials.preventSilentAccess();
    location.href = '/signout';
  }

Les utilisateurs peuvent désactiver la réauthentification automatique dans les paramètres.

Les utilisateurs peuvent désactiver la réauthentification automatique dans le menu des paramètres :

• Dans la version pour ordinateur de Chrome, accédez à chrome://password-manager/settings > Se connecter automatiquement.
• Sur Android Chrome, ouvrez Paramètres > Gestionnaire de mots de passe > appuyez sur l'icône en forme de roue dentée en haut à droite > Connexion automatique.

En désactivant le bouton bascule, l'utilisateur peut désactiver complètement le comportement de réauthentification automatique. Ce paramètre est stocké et synchronisé sur les appareils si l'utilisateur est connecté à un compte Google sur l'instance Chrome et que la synchronisation est activée.

Déconnecter le fournisseur d'identité du fournisseur de services

Si un utilisateur s'est déjà connecté à la RP à l'aide de l'IdP via FedCM, la relation est mémorisée localement par le navigateur sous la forme d'une liste de comptes associés. Le RP peut lancer une déconnexion en appelant la fonction IdentityCredential.disconnect(). Cette fonction peut être appelée à partir d'un frame RP de premier niveau. Le RP doit transmettre un configURL, le clientId qu'il utilise sous l'IdP et un accountHint pour que l'IdP soit déconnecté. Un indice de compte peut être une chaîne arbitraire tant que le point de terminaison de déconnexion peut identifier le compte (par exemple, une adresse e-mail ou un ID utilisateur qui ne correspond pas nécessairement à l'ID de compte fourni par le point de terminaison de la liste des comptes) :

  // Disconnect an IdP account 'account456' from the RP 'https://idp.com/'. This is invoked on the RP domain.
  IdentityCredential.disconnect({
    configURL: 'https://idp.com/config.json',
    clientId: 'rp123',
    accountHint: 'account456'
  });

IdentityCredential.disconnect() renvoie un Promise. Cette promesse peut générer une exception pour les raisons suivantes :

• L'utilisateur ne s'est pas connecté au RP à l'aide de l'IdP via FedCM.
• L'API est appelée depuis un iFrame sans règle d'autorisation FedCM.
• L'URL de configuration n'est pas valide ou le point de terminaison de déconnexion est manquant.
• Échec de la vérification de la Content Security Policy (CSP).
• Une demande de dissociation est en attente.
• L'utilisateur a désactivé FedCM dans les paramètres du navigateur.

Lorsque le point de terminaison de déconnexion de l'IdP renvoie une réponse, le RP et l'IdP sont déconnectés du navigateur et la promesse est résolue. Les ID des comptes dissociés sont spécifiés dans la réponse du point de terminaison de dissociation.

Étapes suivantes

Implémenter FedCM du côté de l'IdP

Découvrez comment implémenter votre solution d'identité avec FedCM du côté du fournisseur d'identité.

Personnalisation et désactivation

Découvrez comment les utilisateurs et les développeurs peuvent gérer la participation à FedCM, y compris l'activation ou la désactivation, sur les plates-formes et les sites.