Guide du développeur de l'API Federated Credential Management

Découvrez comment utiliser FedCM pour la fédération d'identité protégeant la confidentialité.

FedCM (Federated Credential Management) est une approche protégeant la confidentialité des services d'identité fédérée (par exemple, "Se connecter avec...") qui permet aux utilisateurs de se connecter à des sites sans partager leurs informations personnelles avec le service d'identité ou le site.

Pour en savoir plus sur les cas d'utilisation de FedCM, les parcours utilisateur et la feuille de route de l'API, consultez la présentation de l'API FedCM.

Environnement de développement FedCM

Pour utiliser FedCM, vous avez besoin d'un contexte sécurisé (HTTPS ou localhost) à la fois au niveau de l'IdP et du RP dans Chrome.

Déboguer le code dans Chrome sur Android

Configurez et exécutez un serveur localement pour déboguer votre code FedCM. Vous pouvez accéder à ce serveur dans Chrome sur un appareil Android connecté à l'aide d'un câble USB avec transfert de port.

Vous pouvez utiliser les outils de développement sur ordinateur pour déboguer Chrome sur Android en suivant les instructions de la section Déboguer à distance les appareils Android.

Bloquer les cookies tiers sur Chrome

Simuler l'abandon progressif des cookies tiers en configurant Chrome pour les bloquer
Simuler la suppression progressive des cookies tiers en configurant Chrome pour les bloquer

Vous pouvez tester le fonctionnement de FedCM sans cookies tiers sur Chrome avant son application concrète.

Pour bloquer les cookies tiers, utilisez le mode navigation privée ou sélectionnez "Bloquer les cookies tiers" dans les paramètres de votre ordinateur à l'adresse chrome://settings/cookies ou sur un appareil mobile en accédant à Paramètres > Paramètres des sites > Cookies.

Utiliser l'API FedCM

L'intégration à FedCM consiste à créer un fichier connu, un fichier de configuration et des points de terminaison pour la liste des comptes, l'émission d'assertions et éventuellement des métadonnées client.

À partir de là, FedCM expose des API JavaScript que les RP peuvent utiliser pour se connecter avec le fournisseur d'identité.

Créer un fichier connu

Pour empêcher les outils de suivi d'utiliser l'API de manière abusive, un fichier connu doit être diffusé à partir de l'/.well-known/web-identity de l'eTLD+1 du fournisseur d'identité.

Par exemple, si les points de terminaison du fournisseur d'identité sont diffusés sous https://accounts.idp.example/, ils doivent diffuser un fichier connu dans https://idp.example/.well-known/web-identity, ainsi qu'un fichier de configuration du fournisseur d'identité. Voici un exemple de contenu de fichier connu:

{
  "provider_urls": ["https://accounts.idp.example/config.json"]
}

Le fichier JSON doit contenir la propriété provider_urls avec un tableau d'URL du fichier de configuration IdP pouvant être spécifiées en tant que partie du chemin d'accès de configURL dans navigator.credentials.get par les RP. Le nombre de chaînes d'URL dans le tableau est limité à une, mais cela peut changer en fonction de vos commentaires par la suite.

Créer un fichier de configuration d'IdP et des points de terminaison

Le fichier de configuration de l'IdP fournit la liste des points de terminaison requis pour le navigateur. Les fournisseurs d'identité hébergeront ce fichier de configuration ainsi que les points de terminaison et les URL requis. Toutes les réponses JSON doivent être diffusées avec le type de contenu application/json.

L'URL du fichier de configuration est déterminée par les valeurs fournies à l'appel navigator.credentials.get exécuté sur une RP.

const credential = await navigator.credentials.get({
  identity: {
    context: 'signup',
    providers: [{
      configURL: 'https://accounts.idp.example/config.json',
      clientId: '********',
      nonce: '******'
    }]
  }
});
const { token } = credential;

Spécifiez une URL complète de l'emplacement du fichier de configuration de l'IdP en tant que configURL. Lorsque navigator.credentials.get() est appelé sur la RP, le navigateur extrait le fichier de configuration avec une requête GET sans l'en-tête Origin ni l'en-tête Referer. La requête n'a pas de cookies et ne suit pas les redirections. Cela empêche le fournisseur d'identité de savoir qui a effectué la requête et quel RP tente de se connecter. Exemple :

GET /config.json HTTP/1.1
Host: accounts.idp.example
Accept: application/json
Sec-Fetch-Dest: webidentity

Le navigateur attend une réponse JSON du fournisseur d'identité, laquelle inclut les propriétés suivantes:

Propriété Description
accounts_endpoint (obligatoire) URL du point de terminaison des comptes.
client_metadata_endpoint (facultatif) URL du point de terminaison des métadonnées client.
id_assertion_endpoint (obligatoire) URL du point de terminaison d'assertion d'ID.
disconnect (facultatif) URL du point de terminaison de déconnexion.
login_url (obligatoire) URL de la page de connexion permettant à l'utilisateur de se connecter au fournisseur d'identité.
branding (facultatif) Objet contenant différentes options de branding.
branding.background_color (facultatif) Option de marque définissant la couleur d'arrière-plan du bouton "Continuer en tant que...". Utilisez la syntaxe CSS appropriée, à savoir hex-color, hsl(), rgb() ou named-color.
branding.color (facultatif) Option de marque définissant la couleur du texte du bouton "Continuer en tant que...". Utilisez la syntaxe CSS appropriée, à savoir hex-color, hsl(), rgb() ou named-color.
branding.icons (facultatif) Option de marque définissant l'objet de l'icône, affichée dans la boîte de dialogue de connexion. L'objet icon est un tableau comportant deux paramètres :
  • url (obligatoire): URL de l'image de l'icône. Cette option n'est pas compatible avec les images SVG.
  • size (facultatif): dimensions de l'icône, considérées par l'application comme étant carrées et avec une résolution simple. Ce nombre doit être supérieur ou égal à 25.

Le RP pourrait modifier la chaîne dans l'interface utilisateur de la boîte de dialogue FedCM via la valeur identity.context pour navigator.credentials.get() afin de s'adapter aux contextes d'authentification prédéfinis. La propriété facultative peut être "signin" (par défaut), "signup", "use" ou "continue".

Application du branding à la boîte de dialogue FedCM
Comment le branding est appliqué à la boîte de dialogue FedCM

Voici un exemple de corps de réponse du fournisseur d'identité:

{
  "accounts_endpoint": "/accounts.php",
  "client_metadata_endpoint": "/client_metadata.php",
  "id_assertion_endpoint": "/assertion.php",
  "disconnect_endpoint": "/disconnect.php",
  "login_url": "/login",
  "branding": {
    "background_color": "green",
    "color": "#FFEEAA",
    "icons": [{
      "url": "https://idp.example/icon.ico",
      "size": 25
    }]
  }
}

Une fois que le navigateur a récupéré le fichier de configuration, il envoie les requêtes suivantes aux points de terminaison du fournisseur d'identité:

Points de terminaison IdP
Points de terminaison du fournisseur d'identité

Point de terminaison des comptes

Le point de terminaison des comptes du fournisseur d'identité renvoie la liste des comptes auxquels l'utilisateur est actuellement connecté. Si le fournisseur d'identité accepte plusieurs comptes, ce point de terminaison renvoie tous les comptes connectés.

Le navigateur envoie une requête GET avec des cookies avec SameSite=None, mais sans paramètre client_id, ni l'en-tête Origin, ni l'en-tête Referer. Cela empêche le fournisseur d'identité de savoir à quel RP l'utilisateur tente de se connecter. Exemple :

GET /accounts.php HTTP/1.1
Host: accounts.idp.example
Accept: application/json
Cookie: 0x23223
Sec-Fetch-Dest: webidentity

À la réception de la requête, le serveur doit:

  1. Vérifiez que la requête contient un en-tête HTTP Sec-Fetch-Dest: webidentity.
  2. Faites correspondre les cookies de session avec les ID des comptes déjà connectés.
  3. Répondez en fournissant la liste des comptes.

Le navigateur attend une réponse JSON incluant une propriété accounts avec un tableau d'informations de compte avec les propriétés suivantes:

Propriété Description
id (obligatoire) Identifiant unique de l'utilisateur.
name (obligatoire) Prénom et nom de famille de l'utilisateur
email (obligatoire) Adresse e-mail de l'utilisateur.
given_name (facultatif) Prénom de l'utilisateur.
picture (facultatif) URL de l'avatar de l'utilisateur.
approved_clients (facultatif) Tableau des ID client RP auprès desquels l'utilisateur s'est enregistré.
login_hints (facultatif) Tableau de tous les types de filtres possibles compatibles avec le fournisseur d'identité pour spécifier un compte. Le tiers assujetti à des restrictions peut appeler navigator.credentials.get() avec la propriété loginHint pour afficher le compte spécifié de manière sélective.
domain_hints (facultatif) Tableau de tous les domaines auxquels le compte est associé. Le tiers assujetti à des restrictions peut appeler navigator.credentials.get() avec une propriété domainHint pour filtrer les comptes.

Exemple de corps de réponse:

{
  "accounts": [{
    "id": "1234",
    "given_name": "John",
    "name": "John Doe",
    "email": "john_doe@idp.example",
    "picture": "https://idp.example/profile/123",
    "approved_clients": ["123", "456", "789"],
    "login_hints": ["demo1", "demo1@idp.example"]
  }, {
    "id": "5678",
    "given_name": "Johnny",
    "name": "Johnny",
    "email": "johnny@idp.example",
    "picture": "https://idp.example/profile/456",
    "approved_clients": ["abc", "def", "ghi"],
    "login_hints": ["demo2", "demo2@idp.example"],
    "domain_hints": ["corp.example"]
  }]
}

Si l'utilisateur n'est pas connecté, envoyez la réponse HTTP 401 (Non autorisé).

La liste de comptes renvoyée est utilisée par le navigateur et ne sera pas disponible pour le tiers assujetti à des restrictions.

Point de terminaison des métadonnées client

Le point de terminaison des métadonnées du client du fournisseur d'identité renvoie les métadonnées du tiers de confiance, telles que les règles de confidentialité et les conditions d'utilisation du RP. Les tiers assujettis à des restrictions doivent fournir au préalable des liens vers leurs règles de confidentialité et leurs conditions d'utilisation au fournisseur d'identité. Ces liens s'affichent dans la boîte de dialogue de connexion lorsque l'utilisateur ne s'est pas encore enregistré sur la RP auprès du fournisseur d'identité.

Le navigateur envoie une requête GET à l'aide de client_id navigator.credentials.get sans cookies. Exemple :

GET /client_metadata.php?client_id=1234 HTTP/1.1
Host: accounts.idp.example
Origin: https://rp.example/
Accept: application/json
Sec-Fetch-Dest: webidentity

À la réception de la requête, le serveur doit:

  1. Déterminez le tiers assujetti à des restrictions pour client_id.
  2. Répondez avec les métadonnées du client.

Les propriétés du point de terminaison des métadonnées client incluent:

Propriété Description
privacy_policy_url (facultatif) URL des règles de confidentialité du tiers assujetti à des restrictions.
terms_of_service_url (facultatif) URL des conditions d'utilisation du tiers assujetti à des restrictions.

Le navigateur attend une réponse JSON du point de terminaison:

{
  "privacy_policy_url": "https://rp.example/privacy_policy.html",
  "terms_of_service_url": "https://rp.example/terms_of_service.html",
}

Les métadonnées de client renvoyées sont utilisées par le navigateur et ne seront pas disponibles pour le RP.

Point de terminaison d'assertion d'ID

Le point de terminaison d'assertion de l'ID du fournisseur d'identité renvoie une assertion pour l'utilisateur connecté. Lorsque l'utilisateur se connecte à un site Web RP à l'aide de l'appel navigator.credentials.get(), le navigateur envoie une requête POST avec des cookies avec SameSite=None et un type de contenu application/x-www-form-urlencoded à ce point de terminaison, avec les informations suivantes:

Propriété Description
client_id (obligatoire) Identifiant du client du tiers assujetti à des restrictions.
account_id (obligatoire) Identifiant unique de l'utilisateur qui se connecte.
nonce (facultatif) Nonce de requête, fourni par la RP.
disclosure_text_shown Il en résulte une chaîne "true" ou "false" (plutôt qu'une valeur booléenne). Le résultat est "false" si le texte de la mention n'a pas été affiché. Cela se produit lorsque l'ID client du tiers assujetti à des restrictions a été inclus dans la liste de propriétés approved_clients de la réponse du point de terminaison des comptes ou si le navigateur a constaté une inscription par le passé en l'absence de approved_clients.
is_auto_selected Si une réauthentification automatique est effectuée sur la RP, is_auto_selected indique "true". Sinon, "false". Cela est utile pour prendre en charge d'autres fonctionnalités de sécurité. Par exemple, certains utilisateurs peuvent préférer un niveau de sécurité plus élevé qui nécessite une médiation utilisateur explicite lors de l'authentification. Si un fournisseur d'identité reçoit une requête de jeton sans médiation, il peut traiter la requête différemment. Par exemple, renvoyez un code d'erreur permettant au tiers assujetti à des restrictions d'appeler à nouveau l'API FedCM avec mediation: required.

Exemple d'en-tête HTTP:

POST /assertion.php HTTP/1.1
Host: accounts.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=Ct60bD&disclosure_text_shown=true&is_auto_selected=true

À la réception de la requête, le serveur doit:

  1. Répondez à la requête avec CORS (Cross-Origin Resource Sharing).
  2. Vérifiez que la requête contient un en-tête HTTP Sec-Fetch-Dest: webidentity.
  3. Faites correspondre l'en-tête Origin à l'origine de la RP déterminée par l'client_id. Refusez s'ils ne correspondent pas.
  4. Faites correspondre account_id avec l'ID du compte auquel vous êtes déjà connecté. Refusez s'ils ne correspondent pas.
  5. Répondre avec un jeton. Si la requête est rejetée, renvoyez une réponse d'erreur.

C'est le fournisseur d'identité qui émet le jeton. Toutefois, il est généralement signé à l'aide d'informations telles que l'ID de compte, l'ID client, l'origine de l'émetteur nonce, afin que le tiers assujetti à des restrictions puisse vérifier que le jeton est authentique.

Le navigateur attend une réponse JSON incluant la propriété suivante:

Propriété Description
token (obligatoire) Un jeton est une chaîne qui contient des affirmations concernant l'authentification. 
{
  "token": "***********"
}

Le jeton renvoyé est transmis à la RP par le navigateur, afin que celui-ci puisse valider l'authentification.

Renvoyer une réponse d'erreur

id_assertion_endpoint peut également renvoyer une réponse "error" qui comporte deux champs facultatifs:

  • code: le fournisseur d'identité peut choisir l'une des erreurs connues dans la liste des erreurs spécifiées OAuth 2.0 (invalid_request, unauthorized_client, access_denied, server_error et temporarily_unavailable) ou utiliser n'importe quelle chaîne arbitraire. Dans ce dernier cas, Chrome affiche l'interface utilisateur de l'erreur avec un message d'erreur générique et transmet le code au tiers assujetti à des restrictions.
  • url: identifie une page Web lisible par l'humain avec des informations sur l'erreur pour fournir des informations supplémentaires aux utilisateurs. Ce champ est utile aux utilisateurs, car les navigateurs ne peuvent pas fournir de messages d'erreur enrichis dans une interface utilisateur native. (par exemple, des liens vers les étapes suivantes, les coordonnées du service client, etc.). Si un utilisateur souhaite en savoir plus sur les détails de l'erreur et savoir comment la corriger, il peut consulter la page fournie à partir de l'interface utilisateur du navigateur pour en savoir plus. L'URL doit correspondre au même site que le fournisseur d'identité configURL.
// id_assertion_endpoint response
{
  "error" : {
     "code": "access_denied",
     "url" : "https://idp.example/error?type=access_denied"
  }
}

Déconnecter le point de terminaison

En appelant IdentityCredential.disconnect(), le navigateur envoie à ce point de terminaison de déconnexion une requête POST multi-origine avec des cookies avec SameSite=None et un type de contenu application/x-www-form-urlencoded, avec les informations suivantes:

Propriété Description
account_hint Indice pour le compte du fournisseur d'identité.
client_id Identifiant du client du tiers assujetti à des restrictions. 
POST /disconnect.php HTTP/1.1
Host: idp.example
Origin: rp.example
Content-Type: application/x-www-form-urlencoded
Cookie: 0x123
Sec-Fetch-Dest: webidentity

account_hint=account456&client_id=rp123

À la réception de la requête, le serveur doit:

  1. Répondez à la requête avec CORS (Cross-Origin Resource Sharing).
  2. Vérifiez que la requête contient un en-tête HTTP Sec-Fetch-Dest: webidentity.
  3. Faites correspondre l'en-tête Origin à l'origine de la RP déterminée par l'client_id. Refusez s'ils ne correspondent pas.
  4. Faites correspondre account_hint avec les ID des comptes déjà connectés.
  5. Déconnectez le compte utilisateur du tiers assujetti à des restrictions.
  6. Répondez au navigateur avec les informations de compte utilisateur identifiées au format JSON.

Voici un exemple de charge utile JSON de réponse:

{
  "account_id": "account456"
}

À la place, si le fournisseur d'identité souhaite que le navigateur déconnecte tous les comptes associés au RP, transmettez une chaîne qui ne correspond à aucun ID de compte, par exemple "*".

URL de connexion

Avec l'API Login Status, le fournisseur d'identité doit informer le navigateur de l'état de la connexion de l'utilisateur. Toutefois, l'état peut ne pas être synchronisé (lorsque la session expire, par exemple). Dans un tel scénario, le navigateur peut autoriser dynamiquement l'utilisateur à se connecter au fournisseur d'identité via l'URL de la page de connexion spécifiée dans le fichier de configuration idp login_url.

La boîte de dialogue FedCM affiche un message suggérant une connexion, comme illustré ci-dessous.

A
Boîte de dialogue FedCM suggérant de se connecter à l'IdP.

Lorsque l'utilisateur clique sur le bouton Continue (Continuer), le navigateur ouvre une fenêtre pop-up pour la page de connexion du fournisseur d'identité.

Une
Exemple de boîte de dialogue qui s'affiche lorsque l'utilisateur clique sur le bouton "Sign in to the IdP" (Se connecter au fournisseur d'identité).

La boîte de dialogue est une fenêtre de navigateur standard qui contient des cookies propriétaires. Ce qui se passe dans la boîte de dialogue dépend de l'IdP, et aucun gestionnaire de fenêtre n'est disponible pour envoyer une requête de communication multi-origine à la page du RP. Une fois l'utilisateur connecté, le fournisseur d'identité doit:

  • Envoyez l'en-tête Set-Login: logged-in ou appelez l'API navigator.login.setStatus("logged-in") pour informer le navigateur que l'utilisateur a été connecté.
  • Appelez IdentityProvider.close() pour fermer la boîte de dialogue.
A
Un utilisateur se connecte à un RP après s'être connecté à l'IdP via FedCM.

Informer le navigateur de l'état de connexion de l'utilisateur auprès du fournisseur d'identité

Avec l'API Login Status, un site Web, en particulier un IdP, informe le navigateur de l'état de connexion de l'utilisateur sur le fournisseur d'identité. Avec cette API, le navigateur peut réduire les requêtes inutiles adressées au fournisseur d'identité et limiter les attaques de synchronisation potentielles.

Les fournisseurs d'identité peuvent signaler l'état de connexion de l'utilisateur au navigateur en envoyant un en-tête HTTP ou en appelant une API JavaScript lorsque l'utilisateur est connecté au fournisseur d'identité ou lorsqu'il est déconnecté de tous ses comptes d'IdP. Pour chaque fournisseur d'identité (identifié par son URL de configuration), le navigateur conserve une variable à trois états représentant l'état de connexion avec les valeurs possibles logged-in, logged-out et unknown. L'état par défaut est unknown.

Pour signaler que l'utilisateur est connecté, envoyez un en-tête HTTP Set-Login: logged-in dans une navigation de niveau supérieur ou une requête de sous-ressource sur le même site à l'origine du fournisseur d'identité:

Set-Login: logged-in

Vous pouvez également appeler l'API JavaScript navigator.login.setStatus("logged-in") à partir de l'origine du fournisseur d'identité dans une navigation de premier niveau:

navigator.login.setStatus("logged-in")

Ces appels enregistrent l'état de connexion de l'utilisateur comme logged-in. Lorsque l'état de connexion de l'utilisateur est défini sur logged-in, le RP qui appelle FedCM envoie des requêtes au point de terminaison des comptes du fournisseur d'identité et affiche les comptes disponibles dans la boîte de dialogue FedCM.

Pour signaler que l'utilisateur est déconnecté de tous ses comptes, envoyez l'en-tête HTTP Set-Login: logged-out dans une navigation de premier niveau ou une requête de sous-ressource sur le même site au niveau de l'origine du fournisseur d'identité:

Set-Login: logged-out

Vous pouvez également appeler l'API JavaScript navigator.login.setStatus("logged-out") à partir de l'origine du fournisseur d'identité dans une navigation de premier niveau:

navigator.login.setStatus("logged-out")

Ces appels enregistrent l'état de connexion de l'utilisateur comme logged-out. Lorsque l'état de connexion de l'utilisateur est logged-out, l'appel à FedCM échoue en mode silencieux sans envoyer de requête au point de terminaison des comptes du fournisseur d'identité.

L'état unknown est défini avant que le fournisseur d'identité n'envoie un signal à l'aide de l'API Login Status. Unknown a été introduit pour améliorer la transition, car un utilisateur peut être déjà connecté au fournisseur d'identité lors du lancement de cette API. Il est possible que le fournisseur d'identité ne puisse pas le signaler au navigateur au moment où FedCM est appelé pour la première fois. Dans ce cas, Chrome envoie une requête au point de terminaison des comptes du fournisseur d'identité et met à jour l'état en fonction de la réponse du point de terminaison des comptes:

  • Si le point de terminaison renvoie une liste de comptes actifs, définissez l'état sur logged-in et ouvrez la boîte de dialogue FedCM pour afficher ces comptes.
  • Si le point de terminaison ne renvoie aucun compte, définissez l'état sur logged-out et échouez à l'appel FedCM.

Autoriser l'utilisateur à se connecter via un flux de connexion dynamique

Même si le fournisseur d'identité continue d'informer l'état de la connexion de l'utilisateur dans le navigateur, il est possible qu'il ne soit pas synchronisé, par exemple à l'expiration de la session. Le navigateur tente d'envoyer une requête avec identifiants au point de terminaison des comptes lorsque l'état de la connexion est logged-in, mais le serveur ne renvoie aucun compte, car la session n'est plus disponible. Dans un tel scénario, le navigateur peut autoriser de manière dynamique l'utilisateur à se connecter au fournisseur d'identité via une fenêtre pop-up.

Se connecter au tiers de confiance avec le fournisseur d'identité

Une fois que la configuration et les points de terminaison du fournisseur d'identité sont disponibles, les tiers assujettis à des restrictions peuvent appeler navigator.credentials.get() pour demander aux utilisateurs de se connecter au RP avec le fournisseur d'identité.

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

if ('IdentityCredential' in window) {
  // If the feature is available, take action
}

Pour demander à autoriser les utilisateurs à se connecter à l'IdP à partir du RP, procédez comme suit, par exemple:

const credential = await navigator.credentials.get({
  identity: {
    providers: [{
      configURL: 'https://accounts.idp.example/config.json',
      clientId: '********',
      nonce: '******'
    }]
  }
});
const { token } = credential;

La propriété providers utilise un tableau d'objets IdentityProvider ayant les propriétés suivantes:

Propriété Description
configURL (obligatoire) Chemin d'accès complet au fichier de configuration de l'IdP.
clientId (obligatoire) Identifiant du client du tiers assujetti à des restrictions, émis par le fournisseur d'identité.
nonce (facultatif) Chaîne aléatoire qui garantit que la réponse est émise pour cette requête spécifique. Empêche les attaques par rejeu.
loginHint (facultatif) En spécifiant l'une des valeurs login_hints fournies par les points de terminaison des comptes, la boîte de dialogue FedCM affiche le compte spécifié de manière sélective.
domainHint (facultatif) En spécifiant l'une des valeurs domain_hints fournies par les points de terminaison des comptes, la boîte de dialogue FedCM affiche le compte spécifié de manière sélective.

Le navigateur gère les cas d'utilisation d'inscription et de connexion différemment selon l'existence de approved_clients dans la réponse du point de terminaison de la liste des comptes. Le navigateur n'affiche pas le texte d'information "To continue with..." si l'utilisateur s'est déjà inscrit au tiers assujetti à des restrictions.

L'état d'inscription est déterminé selon que les conditions suivantes sont remplies ou non:

  • Si approved_clients inclut les clientId du tiers assujetti à des restrictions.
  • Si le navigateur se souvient que l'utilisateur s'est déjà inscrit au tiers assujetti à des restrictions.
Un utilisateur se connecte à un tiers assujetti à des restrictions via FedCM

Lorsque la RP appelle navigator.credentials.get(), les activités suivantes ont lieu:

  1. Le navigateur envoie des requêtes et récupère plusieurs documents :
    1. Le fichier connu et le fichier de configuration de l'IdP, qui déclarent les points de terminaison.
    2. Une liste de comptes
    3. Facultatif: URL des règles de confidentialité et des conditions d'utilisation de la RP, récupérées à partir du point de terminaison des métadonnées du client.
  2. Le navigateur affiche la liste des comptes que l'utilisateur peut utiliser pour se connecter, ainsi que les conditions d'utilisation et les règles de confidentialité, le cas échéant.
  3. Une fois que l'utilisateur a choisi un compte avec lequel se connecter, une requête au point de terminaison d'assertion de l'ID est envoyée au fournisseur d'identité pour récupérer un jeton.
  4. Le tiers assujetti à des restrictions peut valider le jeton pour authentifier l'utilisateur.
appel d'API de connexion
Appel d'API Login

Les tiers assujettis à des restrictions sont censés être compatibles avec les navigateurs non compatibles avec FedCM. Par conséquent, les utilisateurs doivent pouvoir utiliser un processus de connexion non-FedCM existant. Tant que les cookies tiers n'auront pas été complètement supprimés, cela ne devrait pas poser de problème.

Une fois le jeton validé par le serveur de tiers assujettis à des restrictions, celui-ci peut enregistrer l'utilisateur ou l'autoriser à se connecter et à démarrer une nouvelle session.

API Login Hint

Une fois l'utilisateur connecté, la partie de confiance lui demande parfois de s'authentifier de nouveau. Toutefois, l'utilisateur peut ne pas savoir avec certitude quel compte il a utilisé. Si le tiers assujetti à des restrictions peut spécifier le compte avec lequel se connecter, il sera plus facile pour l'utilisateur de choisir un compte.

Les tiers assujettis à des restrictions peuvent afficher un compte spécifique de manière sélective en appelant navigator.credentials.get() avec la propriété loginHint avec l'une des valeurs login_hints extraites du point de terminaison de la liste des comptes, comme illustré dans l'exemple de code suivant:

return await navigator.credentials.get({
  identity: {
    providers: [{
      configURL: "https://idp.example/manifest.json",
      clientId: "123",
      nonce: nonce,
      loginHint : "demo1@example.com"
    }]
  }
});

Si aucun compte ne correspond au loginHint, la boîte de dialogue FedCM affiche une invite de connexion, qui permet à l'utilisateur de se connecter à un compte d'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 ajouté à l'indication de connexion et aux paramètres de requête de l'indication de domaine.

API Domain Hint

Dans certains cas, le tiers assujetti à des restrictions sait déjà que seuls les comptes associés à un domaine donné sont autorisés à se connecter au site. Cela est particulièrement courant dans les entreprises où le site consulté est limité à un domaine d'entreprise. Pour offrir une meilleure expérience utilisateur, l'API FedCM autorise le tiers assujetti à des restrictions d'afficher uniquement les comptes pouvant être utilisés pour se connecter au tiers assujetti à des restrictions. Cela permet d'éviter qu'un utilisateur tente de se connecter au tiers assujetti à des restrictions à l'aide d'un compte situé en dehors du domaine de l'entreprise pour qu'un message d'erreur s'affiche par la suite (ou qu'un message d'erreur s'affiche quand la connexion n'a pas fonctionné), car le type de compte approprié n'a pas été utilisé.

Les tiers assujettis à des restrictions peuvent n'afficher que les comptes correspondants en appelant navigator.credentials.get() avec la propriété domainHint avec l'une des valeurs domain_hints extraites du point de terminaison de la liste des comptes, comme illustré dans l'exemple de code suivant:

return await navigator.credentials.get({
  identity: {
    providers: [{
      configURL: "https://idp.example/manifest.json",
      clientId: "abc",
      nonce: nonce,
      domainHint : "corp.example"
    }]
  }
});

Si aucun compte ne correspond au domainHint, la boîte de dialogue FedCM affiche une invite de connexion, qui permet à l'utilisateur de se connecter à un compte d'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 ajouté à l'indication de connexion et aux paramètres de requête de l'indication de domaine.

Exemple d'invite de connexion lorsqu'aucun compte ne correspond à domainHint.
Exemple d'invite de connexion lorsqu'aucun compte ne correspond à domainHint.

Afficher un message d'erreur

Parfois, le fournisseur d'identité peut ne pas être en mesure d'émettre un jeton pour des raisons légitimes : lorsque le client n'est pas autorisé, le serveur est temporairement indisponible. Si le fournisseur d'identité renvoie une réponse d'erreur, le tiers assujetti à des restrictions peut l'intercepter. De plus, Chrome avertit l'utilisateur en affichant une interface de navigateur avec les informations d'erreur fournies par le fournisseur d'identité.

A
Boîte de dialogue FedCM affichant le message d'erreur après l'échec de la tentative de connexion de l'utilisateur. La chaîne est associée au type d'erreur.
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 leur autorisation initiale

La réauthentification automatique FedCM ("réauthentification automatique") permet aux utilisateurs de se réauthentifier automatiquement lorsqu'ils reviennent après leur authentification initiale à l'aide de FedCM. "L'authentification initiale" signifie que l'utilisateur crée un compte ou se connecte au site Web du tiers assujetti à des restrictions en appuyant pour la première fois sur le bouton Continuer en tant que de la boîte de dialogue de connexion de FedCM dans la même instance de navigateur.

Bien que l'expérience utilisateur explicite soit logique avant que l'utilisateur ait créé le compte fédéré pour empêcher le suivi (l'un des principaux objectifs de FedCM), elle est inutilement fastidieuse une fois que l'utilisateur l'a parcourue une fois: une fois que l'utilisateur a autorisé la communication entre le tiers assujetti à des restrictions et l'IdP, il n'y a aucun avantage en termes de confidentialité ou de sécurité pour l'application d'une autre confirmation explicite de l'utilisateur pour un élément qu'il a déjà confirmé précédemment.

Avec la réauthentification automatique, le navigateur modifie son comportement en fonction de l'option que vous spécifiez pour mediation lors de l'appel de 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. Elle se comporte de la même manière que pour PasswordCredential et FederatedCredential. Elle est également partiellement compatible avec PublicKeyCredential. La propriété accepte les quatre valeurs suivantes:

  • 'optional'(par défaut): si possible, se réauthentifier automatiquement. Dans le cas contraire, une médiation est nécessaire. Nous vous recommandons de choisir cette option sur la page de connexion.
  • 'required': une médiation est toujours nécessaire pour poursuivre, par exemple en cliquant sur le bouton "Continuer" dans l'interface utilisateur. Choisissez cette option si vos utilisateurs doivent accorder explicitement une autorisation à chaque authentification.
  • 'silent': si possible, la réauthentification automatique échoue sans nécessiter de médiation. 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, la page d'un article sur un site Web de livraison ou la page d'un article sur un site Web d'actualités).
  • 'conditional': utilisé pour WebAuthn et non disponible pour FedCM pour le moment.

Avec cet appel, la procédure d'authentification automatique se produit dans les conditions suivantes:

  • FedCM peut être utilisé. Par exemple, l'utilisateur n'a pas désactivé FedCM de manière globale ou pour le tiers assujetti à des restrictions 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.
  • La reauthentification automatique ne s'est pas produite au cours des 10 dernières minutes.
  • Le tiers assujetti à des restrictions 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 le navigator.credentials.get() FedCM est appelé.

Lorsque la valeur est mediation: optional, la réauthentification automatique peut être indisponible pour des raisons que seul le navigateur connaît. Le tiers assujetti à des restrictions 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'expérience utilisateur en conséquence. De plus, lorsque cette option n'est pas disponible, l'utilisateur peut être invité à se connecter avec une médiation utilisateur explicite, qui est un flux avec mediation: required.

Un utilisateur s'authentifie automatiquement via FedCM.

Appliquez la médiation avec preventSilentAccess()

Réauthentifier automatiquement les utilisateurs immédiatement après leur déconnexion n'améliorerait pas l'expérience utilisateur. C'est pourquoi FedCM bénéficie d'une période silencieuse de 10 minutes après une nouvelle 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 Chrome pour ordinateur, accédez à chrome://password-manager/settings > Se connecter automatiquement.
  • Dans Chrome pour Android, accédez à 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 l'option, l'utilisateur peut désactiver la réauthentification automatique. Ce paramètre est stocké et synchronisé sur tous les appareils, si l'utilisateur est connecté à un compte Google sur l'instance Chrome et si la synchronisation est activée.

Déconnecter l'IdP du RP

Si un utilisateur s'est déjà connecté au tiers assujetti à des restrictions à l'aide du fournisseur d'identité via FedCM, la relation est mémorisée par le navigateur localement sous forme de liste de comptes connectés. Le RP peut initier une déconnexion en appelant la fonction IdentityCredential.disconnect(). Cette fonction peut être appelée à partir d'une trame RP de premier niveau. Le RP doit transmettre un configURL, le clientId qu'il utilise sous le fournisseur d'identité et un accountHint pour que le fournisseur d'identité soit déconnecté. Un indice de compte peut correspondre à une chaîne arbitraire, à condition que le point de terminaison de déconnexion puisse identifier le compte. Il peut s'agir, par exemple, d'une adresse e-mail ou d'un ID utilisateur qui ne correspond pas nécessairement à l'ID de compte fourni par le point de terminaison de la liste de 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 tiers assujetti à des restrictions à l'aide du fournisseur d'identité via FedCM.
  • L'API est appelée depuis un iFrame sans règle d'autorisation FedCM.
  • Le configURL n'est pas valide ou le point de terminaison de déconnexion est manquant.
  • Échec de la vérification de la CSP (Content Security Policy).
  • Une demande de déconnexion est en attente.
  • L'utilisateur a désactivé FedCM dans les paramètres du navigateur.

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

Appeler FedCM depuis un iFrame multi-origine

FedCM peut être appelé à partir d'un iFrame multi-origine à 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>

Pour voir un exemple concret, cliquez ici.

Si la trame parente souhaite limiter les origines à 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 d'autorisation, consultez la page Contrôler les fonctionnalités du navigateur à l'aide des règles d'autorisation.